--- title: n8n description: Monitor the health and performance of n8n. breadcrumbs: Docs > Integrations > n8n --- # n8n Supported OS Integration version1.0.0 {% callout %} # Important note for users on the following Datadog sites: us2.ddog-gov.com {% alert level="info" %} To find out if this integration is available in your organization, see your [Datadog Integrations](https://app.datadoghq.com/integrations) page or ask your organization administrator. To initiate an exception request to enable this integration for your organization, email [support@ddog-gov.com](mailto:support@ddog-gov.com). {% /alert %} {% /callout %} An overview of n8n overall healthn8n logsn8n workflow performance ## Overview{% #overview %} This check monitors [n8n](https://n8n.io/) through the Datadog Agent. n8n (pronounced n-eight-n) is a workflow automation platform that connects API-enabled apps with minimal code. This check collects the following n8n metrics: - Cache metrics: Monitor cache effectiveness (hit rate), identify performance bottlenecks, and detect cache errors. - Message event bus metrics: Monitor event processing health, detect bottlenecks in event handling, track event bus connectivity, and identify processing failures. - Workflow metrics: Track workflow success rates, identify slow or failing workflows, monitor concurrent execution load, and analyze execution patterns. - Queue metrics: Monitor queue health, identify processing bottlenecks, track job success rates, analyze wait times, and detect retry patterns or persistent failures. ## Setup{% #setup %} Follow the instructions below to install and configure this check for an Agent running on a host. For containerized environments, see the [Autodiscovery Integration Templates](https://docs.datadoghq.com/containers/kubernetes/integrations.md) for guidance on applying these instructions. ### Installation{% #installation %} The n8n check is included in the [Datadog Agent](https://app.datadoghq.com/account/settings/agent/latest) package. No additional installation is needed. #### Enable the n8n metrics endpoint{% #enable-the-n8n-metrics-endpoint %} The `/metrics` endpoint is disabled by default and must be enabled in your n8n configuration. **Note**: The `/metrics` endpoint is only available for self-hosted instances and is not available on n8n Cloud. Set the following environment variables to enable metrics: ```bash # Required: Enable the metrics endpoint N8N_METRICS=true # Optional: Include additional metric categories N8N_METRICS_INCLUDE_DEFAULT_METRICS=true N8N_METRICS_INCLUDE_CACHE_METRICS=true N8N_METRICS_INCLUDE_MESSAGE_EVENT_BUS_METRICS=true N8N_METRICS_INCLUDE_WORKFLOW_ID_LABEL=true N8N_METRICS_INCLUDE_API_ENDPOINTS=true # Optional: Customize the metric prefix (default is 'n8n_') N8N_METRICS_PREFIX=n8n_ ``` For more details, see the n8n documentation on [enabling Prometheus metrics](https://docs.n8n.io/hosting/configuration/configuration-examples/prometheus/). #### Configure the Datadog Agent{% #configure-the-datadog-agent %} 1. Edit the `n8n.d/conf.yaml` file in the `conf.d/` folder at the root of your Agent's configuration directory. See the [sample n8n.d/conf.yaml](https://github.com/DataDog/integrations-core/blob/master/n8n/datadog_checks/n8n/data/conf.yaml.example) for all available configuration options. 1. [Restart the Agent](https://docs.datadoghq.com/agent/configuration/agent-commands.md#start-stop-and-restart-the-agent). ### Log collection{% #log-collection %} *Available for Agent versions 6.0+.* #### Enable n8n logging{% #enable-n8n-logging %} Configure n8n to output logs by setting the following environment variables: ```bash # Set the log level (error, warn, info, debug) N8N_LOG_LEVEL=info # Output logs to console (for containerized environments) or file N8N_LOG_OUTPUT=console # If using file output, specify the log file location # N8N_LOG_FILE_LOCATION=/var/log/n8n/n8n.log ``` #### Structured event logs{% #structured-event-logs %} n8n can output structured JSON logs to `n8nEventLog.log` containing detailed workflow execution events. To enable structured event logs, set log output to `file`: ```bash N8N_LOG_OUTPUT=file N8N_LOG_FILE_LOCATION=/var/log/n8n/ ``` The event log includes the following event types: | Event Type | Description | | ----------------------------- | ----------------------------------- | | `n8n.workflow.started` | Workflow execution has begun | | `n8n.workflow.success` | Workflow completed successfully | | `n8n.workflow.failed` | Workflow execution failed | | `n8n.node.started` | Individual node started execution | | `n8n.node.finished` | Individual node completed execution | | `n8n.audit.workflow.executed` | Audit trail for workflow execution | Each event contains metadata including `executionId`, `workflowId`, `workflowName`, `nodeType`, `nodeName`, and timestamps to correlate with metrics. #### Configure the Datadog Agent to collect logs{% #configure-the-datadog-agent-to-collect-logs %} 1. Collecting logs is disabled by default in the Datadog Agent. Enable it in your `datadog.yaml` file: ```yaml logs_enabled: true ``` 1. Add this configuration block to your `n8n.d/conf.yaml` file: ```yaml logs: - type: file path: /var/log/n8n/*.log source: n8n service: n8n ``` For containerized environments using Docker, use the following configuration instead: ```yaml logs: - type: docker source: n8n service: n8n ``` 1. [Restart the Agent](https://docs.datadoghq.com/agent/configuration/agent-commands.md#start-stop-and-restart-the-agent). ### Validation{% #validation %} [Run the Agent's status subcommand](https://docs.datadoghq.com/agent/configuration/agent-commands.md#agent-status-and-information) and look for `n8n` under the Checks section. ## Data Collected{% #data-collected %} ### Metrics{% #metrics %} | | | | | **n8n.active.workflow.count**(gauge) | Total number of active workflows. | | **n8n.api.request.duration.seconds.bucket**(count) | Histogram bucket for API request duration in seconds | | **n8n.api.request.duration.seconds.count**(count) | The count of API request duration in seconds | | **n8n.api.request.duration.seconds.sum**(count) | The sum of API request duration in seconds | | **n8n.api.requests.count**(count) | Total API requests | | **n8n.cache.errors.count**(count) | Cache errors | | **n8n.cache.hits.count**(count) | Cache hits | | **n8n.cache.latency.seconds.bucket**(count) | Histogram bucket for cache operation latency in seconds | | **n8n.cache.latency.seconds.count**(count) | The count of cache operation latency in seconds | | **n8n.cache.latency.seconds.sum**(count) | The sum of cache operation latency in seconds | | **n8n.cache.misses.count**(count) | Cache misses | | **n8n.cache.operations.count**(count) | Total cache operations | | **n8n.eventbus.connections.total**(gauge) | Active event bus backend connections | | **n8n.eventbus.events.count**(count) | Total events published on the event bus | | **n8n.eventbus.events.failed.count**(count) | Total failed event processing | | **n8n.eventbus.events.processed.count**(count) | Total processed events | | **n8n.eventbus.queue.size**(gauge) | Current event queue size | | **n8n.http.request.duration.seconds.count**(count) | The count of the http responses duration labeled with: status_code | | **n8n.http.request.duration.seconds.sum**(count) | The sum of the http responses duration labeled with: status_code | | **n8n.instance.role.leader**(gauge) | Whether this main instance is the leader (1) or not (0). | | **n8n.last.activity**(gauge) | Time elapsed since the last instance activity (backend request).*Shown as second* | | **n8n.nodejs.active.handles**(gauge) | Number of active libuv handles grouped by handle type. Every handle type is C++ class name. | | **n8n.nodejs.active.handles.total**(gauge) | Total number of active handles. | | **n8n.nodejs.active.requests**(gauge) | Number of active libuv requests grouped by request type. Every request type is C++ class name. | | **n8n.nodejs.active.requests.total**(gauge) | Total number of active requests. | | **n8n.nodejs.active.resources**(gauge) | Number of active resources that are currently keeping the event loop alive, grouped by async resource type. | | **n8n.nodejs.active.resources.total**(gauge) | Total number of active resources. | | **n8n.nodejs.event.loop.lag.seconds**(gauge) | Event loop lag in seconds | | **n8n.nodejs.eventloop.lag.max.seconds**(gauge) | The maximum recorded event loop delay. | | **n8n.nodejs.eventloop.lag.mean.seconds**(gauge) | The mean of the recorded event loop delays. | | **n8n.nodejs.eventloop.lag.min.seconds**(gauge) | The minimum recorded event loop delay. | | **n8n.nodejs.eventloop.lag.p50.seconds**(gauge) | The 50th percentile of the recorded event loop delays. | | **n8n.nodejs.eventloop.lag.p90.seconds**(gauge) | The 90th percentile of the recorded event loop delays. | | **n8n.nodejs.eventloop.lag.p99.seconds**(gauge) | The 99th percentile of the recorded event loop delays. | | **n8n.nodejs.eventloop.lag.seconds**(gauge) | Lag of event loop in seconds. | | **n8n.nodejs.eventloop.lag.stddev.seconds**(gauge) | The standard deviation of the recorded event loop delays. | | **n8n.nodejs.external.memory.bytes**(gauge) | Node.js external memory size in bytes. | | **n8n.nodejs.gc.duration.seconds.bucket**(count) | Histogram bucket for garbage collection duration by kind | | **n8n.nodejs.gc.duration.seconds.count**(count) | The count of garbage collection duration by kind | | **n8n.nodejs.gc.duration.seconds.sum**(count) | The sum of garbage collection duration by kind | | **n8n.nodejs.heap.size.total.bytes**(gauge) | Process heap size from Node.js in bytes. | | **n8n.nodejs.heap.size.used.bytes**(gauge) | Process heap size used from Node.js in bytes. | | **n8n.nodejs.heap.space.size.available.bytes**(gauge) | Process heap space size available from Node.js in bytes. | | **n8n.nodejs.heap.space.size.total.bytes**(gauge) | Process heap space size total from Node.js in bytes. | | **n8n.nodejs.heap.space.size.used.bytes**(gauge) | Process heap space size used from Node.js in bytes. | | **n8n.nodejs.heap.total.bytes**(gauge) | Total heap size allocated in bytes | | **n8n.nodejs.heap.used.bytes**(gauge) | Heap memory used in bytes | | **n8n.process.cpu.seconds.count**(count) | Total user and system CPU time spent in seconds. | | **n8n.process.cpu.system.seconds.count**(count) | Total system CPU time spent in seconds. | | **n8n.process.cpu.user.seconds.count**(count) | Total user CPU time spent in seconds. | | **n8n.process.heap.bytes**(gauge) | Process heap size in bytes. | | **n8n.process.max.fds**(gauge) | Maximum number of open file descriptors. | | **n8n.process.open.fds**(gauge) | Number of open file descriptors. | | **n8n.process.resident.memory.bytes**(gauge) | Resident memory size in bytes. | | **n8n.process.start.time.seconds**(gauge) | Start time of the process since unix epoch in seconds. | | **n8n.process.uptime.seconds**(gauge) | Process uptime in seconds. | | **n8n.process.virtual.memory.bytes**(gauge) | Virtual memory size in bytes. | | **n8n.queue.job.active.total**(gauge) | Number of jobs currently being processed | | **n8n.queue.job.attempts.count**(count) | Total number of job attempts | | **n8n.queue.job.completed.count**(count) | Number of jobs completed successfully | | **n8n.queue.job.delayed.total**(gauge) | Number of jobs scheduled to run later | | **n8n.queue.job.dequeued.count**(count) | Number of jobs dequeued (picked up from queue) | | **n8n.queue.job.enqueued.count**(count) | Number of jobs added to the queue | | **n8n.queue.job.failed.count**(count) | Number of jobs that have failed | | **n8n.queue.job.waiting.duration.seconds.bucket**(count) | Histogram bucket for duration jobs spend waiting before being processed | | **n8n.queue.job.waiting.duration.seconds.count**(count) | The count of duration jobs spend waiting before being processed | | **n8n.queue.job.waiting.duration.seconds.sum**(count) | The sum of duration jobs spend waiting before being processed | | **n8n.queue.job.waiting.total**(gauge) | Number of jobs currently waiting in the queue | | **n8n.queue.jobs.count**(count) | Total number of queue jobs | | **n8n.queue.jobs.duration.seconds.bucket**(count) | Histogram bucket for job duration in seconds | | **n8n.queue.jobs.duration.seconds.count**(count) | The count of job duration in seconds | | **n8n.queue.jobs.duration.seconds.sum**(count) | The sum of job duration in seconds | | **n8n.readiness.check**(gauge) | Readiness check status (1 if ready with status code 200 otherwise 0) with status code tag | | **n8n.workflow.executions.active**(gauge) | Number of active workflow executions | | **n8n.workflow.executions.count**(count) | Total number of workflow executions | | **n8n.workflow.executions.duration.seconds.bucket**(count) | Histogram bucket for workflow execution duration in seconds | | **n8n.workflow.executions.duration.seconds.count**(count) | The count of workflow execution duration in seconds | | **n8n.workflow.executions.duration.seconds.sum**(count) | The sum of workflow execution duration in seconds | | **n8n.workflow.failed.count**(count) | Total number of workflows that failed | | **n8n.workflow.started.count**(count) | Total number of workflows started | | **n8n.workflow.success.count**(count) | Total number of workflows completed successfully | ## Uninstallation{% #uninstallation %} To uninstall this integration from your Agent, run the following command: ```bash datadog-agent integration remove datadog-n8n ``` Alternatively, to disable the integration, rename the `n8n.d/conf.yaml` file to `n8n.d/conf.yaml.example`. ## Support{% #support %} Need help? Contact [Datadog Support](https://app.datadoghq.com/help).