docs: Add more detail on how to use grafana with n8n metrics#4628
Open
konstantintieber wants to merge 4 commits into
Open
docs: Add more detail on how to use grafana with n8n metrics#4628konstantintieber wants to merge 4 commits into
konstantintieber wants to merge 4 commits into
Conversation
✅ Deploy Preview for n8n-docs ready!
To edit notification comments on pull requests, go to your Netlify project configuration. |
![cubic-dev-ai[bot]](https://avatars.githubusercontent.com/in/1082092?s=60&v=4){kind=small}
Contributor
There was a problem hiding this comment.
3 issues found across 3 files
Prompt for AI agents (unresolved issues)
Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.
<file name="docs/hosting/grafana/grafana.md">
<violation number="1" location="docs/hosting/grafana/grafana.md:20">
P2: The Prometheus YAML example uses tab indentation, which makes the copied configuration invalid YAML.</violation>
<violation number="2" location="docs/hosting/grafana/grafana.md:82">
P2: The "non-2xx" PromQL filter is incorrect; it excludes only 200 instead of all 2xx status codes.</violation>
<violation number="3" location="docs/hosting/grafana/grafana.md:128">
P2: The form "non-2xx" PromQL filter is incorrect; it excludes only 200 instead of all 2xx status codes.</violation>
</file>
Architecture diagram
sequenceDiagram
participant User as External User
participant n8n as n8n Instance
participant Prom as Prometheus
participant Graf as Grafana
Note over User,Graf: Prometheus Metrics Collection & Grafana Visualization
User->>n8n: HTTP request (webhook/form)
n8n->>n8n: Record request duration (histogram)<br/>if N8N_METRICS_INCLUDE_WEBHOOK_METRICS<br/>or N8N_METRICS_INCLUDE_FORM_METRICS=true
n8n-->>User: HTTP response
Prom->>n8n: Scrape /metrics endpoint (configured in prometheus.yml)
n8n-->>Prom: Metric data (histograms, gauges)
Note over n8n,Prom: Security: /metrics should not be public
alt N8N_METRICS_INCLUDE_WORKFLOW_INFO=true
n8n->>n8n: Expose n8n_workflow_info gauge<br/>with workflow_id + workflow_name labels
Prom->>n8n: Scrape workflow info
n8n-->>Prom: Gauge data
end
Graf->>Prom: Query metrics (PromQL)
alt Query type
Graf-->>Graf: Rate, latency, error rate panels<br/>Join workflow_id with n8n_workflow_info for names
end
Prom-->>Graf: Aggregated results
Graf-->>Graf: Display dashboards (request rate, p95 latency, error rate)
Note over n8n: Key env vars:<br/>N8N_METRICS=true (enable endpoint)<br/>N8N_METRICS_INCLUDE_WEBHOOK_METRICS=true<br/>N8N_METRICS_INCLUDE_FORM_METRICS=true<br/>N8N_METRICS_INCLUDE_WORKFLOW_INFO=true
Note over Prom: Scrape config targets n8n:5678/metrics
Reply with feedback, questions, or to request a fix. Tag @cubic-dev-ai to re-run a review, or fix all with cubic.
| | Submission rate per workflow | `sum by (workflow_id) (rate(n8n_form_submission_duration_seconds_count[5m]))` | | ||
| | p95 processing time across all forms | `histogram_quantile(0.95, sum by (le) (rate(n8n_form_submission_duration_seconds_bucket[5m])))` | | ||
| | p95 processing time per workflow | `histogram_quantile(0.95, sum by (le, workflow_id) (rate(n8n_form_submission_duration_seconds_bucket[5m])))` | | ||
| | Error rate (non-2xx) | `sum by (workflow_id) (rate(n8n_form_submission_duration_seconds_count{status_code!="200"}[5m]))` | |
Contributor
There was a problem hiding this comment.
P2: The form "non-2xx" PromQL filter is incorrect; it excludes only 200 instead of all 2xx status codes.
Prompt for AI agents
Check if this issue is valid — if so, understand the root cause and fix it. At docs/hosting/grafana/grafana.md, line 128:
<comment>The form "non-2xx" PromQL filter is incorrect; it excludes only 200 instead of all 2xx status codes.</comment>
<file context>
@@ -0,0 +1,147 @@
+| Submission rate per workflow | `sum by (workflow_id) (rate(n8n_form_submission_duration_seconds_count[5m]))` |
+| p95 processing time across all forms | `histogram_quantile(0.95, sum by (le) (rate(n8n_form_submission_duration_seconds_bucket[5m])))` |
+| p95 processing time per workflow | `histogram_quantile(0.95, sum by (le, workflow_id) (rate(n8n_form_submission_duration_seconds_bucket[5m])))` |
+| Error rate (non-2xx) | `sum by (workflow_id) (rate(n8n_form_submission_duration_seconds_count{status_code!="200"}[5m]))` |
+| Average processing duration | `rate(n8n_form_submission_duration_seconds_sum[5m]) / rate(n8n_form_submission_duration_seconds_count[5m])` |
+
</file context>
Suggested change
| | Error rate (non-2xx) | `sum by (workflow_id) (rate(n8n_form_submission_duration_seconds_count{status_code!="200"}[5m]))` | | |
| | Error rate (non-2xx) | `sum by (workflow_id) (rate(n8n_form_submission_duration_seconds_count{status_code!~"2.."}[5m]))` | |
| | Request rate per workflow | `sum by (workflow_id) (rate(n8n_webhook_request_duration_seconds_count[5m]))` | | ||
| | p95 latency across all webhooks | `histogram_quantile(0.95, sum by (le) (rate(n8n_webhook_request_duration_seconds_bucket[5m])))` | | ||
| | p95 latency per workflow | `histogram_quantile(0.95, sum by (le, workflow_id) (rate(n8n_webhook_request_duration_seconds_bucket[5m])))` | | ||
| | Error rate (non-2xx) | `sum by (workflow_id) (rate(n8n_webhook_request_duration_seconds_count{status_code!="200"}[5m]))` | |
Contributor
There was a problem hiding this comment.
P2: The "non-2xx" PromQL filter is incorrect; it excludes only 200 instead of all 2xx status codes.
Prompt for AI agents
Check if this issue is valid — if so, understand the root cause and fix it. At docs/hosting/grafana/grafana.md, line 82:
<comment>The "non-2xx" PromQL filter is incorrect; it excludes only 200 instead of all 2xx status codes.</comment>
<file context>
@@ -0,0 +1,147 @@
+| Request rate per workflow | `sum by (workflow_id) (rate(n8n_webhook_request_duration_seconds_count[5m]))` |
+| p95 latency across all webhooks | `histogram_quantile(0.95, sum by (le) (rate(n8n_webhook_request_duration_seconds_bucket[5m])))` |
+| p95 latency per workflow | `histogram_quantile(0.95, sum by (le, workflow_id) (rate(n8n_webhook_request_duration_seconds_bucket[5m])))` |
+| Error rate (non-2xx) | `sum by (workflow_id) (rate(n8n_webhook_request_duration_seconds_count{status_code!="200"}[5m]))` |
+| Average request duration | `rate(n8n_webhook_request_duration_seconds_sum[5m]) / rate(n8n_webhook_request_duration_seconds_count[5m])` |
+
</file context>
Suggested change
| | Error rate (non-2xx) | `sum by (workflow_id) (rate(n8n_webhook_request_duration_seconds_count{status_code!="200"}[5m]))` | | |
| | Error rate (non-2xx) | `sum by (workflow_id) (rate(n8n_webhook_request_duration_seconds_count{status_code!~"2.."}[5m]))` | |
Comment on lines
+20
to
+25
| scrape_configs: | ||
| - job_name: n8n | ||
| static_configs: | ||
| - targets: | ||
| - <n8n-host>:<n8n-port> | ||
| metrics_path: /metrics |
Contributor
There was a problem hiding this comment.
P2: The Prometheus YAML example uses tab indentation, which makes the copied configuration invalid YAML.
Prompt for AI agents
Check if this issue is valid — if so, understand the root cause and fix it. At docs/hosting/grafana/grafana.md, line 20:
<comment>The Prometheus YAML example uses tab indentation, which makes the copied configuration invalid YAML.</comment>
<file context>
@@ -0,0 +1,147 @@
+Add a scrape job for n8n in your `prometheus.yml`:
+
+```yaml
+scrape_configs:
+ - job_name: n8n
+ static_configs:
</file context>
Suggested change
| scrape_configs: | |
| - job_name: n8n | |
| static_configs: | |
| - targets: | |
| - <n8n-host>:<n8n-port> | |
| metrics_path: /metrics | |
| scrape_configs: | |
| - job_name: n8n | |
| static_configs: | |
| - targets: | |
| - <n8n-host>:<n8n-port> | |
| metrics_path: /metrics |
Deploying n8n-docs with
|
| Latest commit: |
db1604d
|
| Status: | ✅ Deploy successful! |
| Preview URL: | https://01ece3d9.n8n-docs-d9c.pages.dev |
| Branch Preview URL: | https://ligo-560-grafana-docs.n8n-docs-d9c.pages.dev |
|
No description provided. |
|
|
||
| The `/metrics` endpoint is disabled by default, but it's possible to enable it using the `N8N_METRICS` environment variable. | ||
|
|
||
| /// warning | Don't expose the metrics endpoint publicly |
Contributor
Author
There was a problem hiding this comment.
This is the only change that could be merged already.
| @@ -0,0 +1,137 @@ | |||
| --- | |||
| contentType: howto | |||
Contributor
Author
There was a problem hiding this comment.
These docs only become relevant if and once n8n-io/n8n#30416 is merged
|
Thanks @konstantintieber! We'll hold off on reviewing this until the PR is ready to go in the main repo. |
RoRoJ
added
author:internal
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
3 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary by cubic
Adds a Grafana how-to to visualize n8n Prometheus metrics.
Includes Prometheus scrape config and Grafana setup, example PromQL for webhook/form latency, workflow name lookup via
n8n_workflow_info, nav entry, a warning to keep/metricsinternal, a note that it isn’t available on n8n Cloud, and duplicate cleanup—supporting LIGO-560 by documenting webhook observability for the webhook manager.Written for commit b9edc10. Summary will update on new commits.