> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://www.comet.com/docs/opik/llms.txt.

# Observability for n8n with Opik

> Start here to integrate Opik into your n8n-based workflow automation for end-to-end LLM observability.

[n8n](https://n8n.io) is a powerful workflow automation platform that allows you to connect various services and automate tasks through a visual interface. With the `n8n-observability` package, you can automatically trace workflow executions and node operations using OpenTelemetry.

> **Warning**
>
> This integration only works with **self-hosted n8n** installations. It is not compatible with n8n Cloud.

![n8n tracing in Opik](/docs/opik/_fern-img/3857b0415b7a5500d720494299b3de241cd3e94d8d32c0210e5d67ea1f175007.webp)

## Features

* 🔍 **Automatic tracing** of workflow executions and individual node operations
* 📊 **Standard OpenTelemetry** instrumentation using the official Node.js SDK
* 🎯 **Zero-code setup** via n8n's hook system
* 🔌 **OTLP compatible** - works with Opik's OpenTelemetry endpoint
* ⚙️ **Configurable** I/O capture, node filtering, and more

## Account Setup

[Comet](https://www.comet.com/site?from=llm\&utm_source=opik\&utm_medium=colab\&utm_content=n8n\&utm_campaign=opik) provides a hosted version of the Opik platform. [Simply create an account](https://www.comet.com/signup?from=llm\&utm_source=opik\&utm_medium=colab\&utm_content=n8n\&utm_campaign=opik) and grab your API Key.

> You can also run the Opik platform locally, see the [installation guide](https://www.comet.com/docs/opik/self-host/overview/?from=llm\&utm_source=opik\&utm_medium=colab\&utm_content=n8n\&utm_campaign=opik) for more information.

## Quick Start with Docker

The fastest way to get started is with Docker Compose:

```bash
# Clone and navigate to the example
git clone https://github.com/comet-ml/n8n-observability.git
cd n8n-observability/examples/docker-compose

# Set your Opik API key (get one free at https://www.comet.com/signup)
export OPIK_API_KEY=your_api_key_here

# Build and run
docker-compose up --build
```

Open [http://localhost:5678](http://localhost:5678), create a workflow, and see traces in your [Opik dashboard](https://www.comet.com)!

## Setup Options

### Docker (Recommended)

Create a custom Dockerfile that installs the `n8n-observability` package globally:

```dockerfile
FROM n8nio/n8n:latest

USER root
RUN npm install -g n8n-observability

ENV EXTERNAL_HOOK_FILES=/usr/local/lib/node_modules/n8n-observability/dist/hooks.cjs

USER node
```

Then configure your docker-compose.yml with OTLP settings:

#### Opik Cloud

```yaml
services:
  n8n:
    build: .
    environment:
      OTEL_EXPORTER_OTLP_ENDPOINT: "https://www.comet.com/opik/api/v1/private/otel"
      OTEL_EXPORTER_OTLP_HEADERS: "Authorization=${OPIK_API_KEY},Comet-Workspace=default"
      N8N_OTEL_SERVICE_NAME: "my-n8n"
    volumes:
      - n8n_data:/home/node/.n8n
    ports:
      - "5678:5678"

volumes:
  n8n_data:
```

> **Tip**
>
> To log the traces to a specific project, you can add the
> `projectName` parameter to the `OTEL_EXPORTER_OTLP_HEADERS`
> environment variable:
>
> ```yaml
> OTEL_EXPORTER_OTLP_HEADERS: "Authorization=${OPIK_API_KEY},Comet-Workspace=default,projectName=my-n8n-project"
> ```

#### Enterprise deployment

```yaml
services:
  n8n:
    build: .
    environment:
      OTEL_EXPORTER_OTLP_ENDPOINT: "https://<comet-deployment-url>/opik/api/v1/private/otel"
      OTEL_EXPORTER_OTLP_HEADERS: "Authorization=${OPIK_API_KEY},Comet-Workspace=default"
      N8N_OTEL_SERVICE_NAME: "my-n8n"
    volumes:
      - n8n_data:/home/node/.n8n
    ports:
      - "5678:5678"

volumes:
  n8n_data:
```

#### Self-hosted instance

```yaml
services:
  n8n:
    build: .
    environment:
      OTEL_EXPORTER_OTLP_ENDPOINT: "http://localhost:5173/api/v1/private/otel"
      OTEL_EXPORTER_OTLP_HEADERS: "projectName=my-n8n-project"
      N8N_OTEL_SERVICE_NAME: "my-n8n"
    volumes:
      - n8n_data:/home/node/.n8n
    ports:
      - "5678:5678"

volumes:
  n8n_data:
```

### Bare Metal / npm

If you're running n8n directly on your machine:

```bash
# Install globally
npm install -g n8n-observability
```

Then set the required environment variables:

#### Opik Cloud

```bash wordWrap
export OTEL_EXPORTER_OTLP_ENDPOINT=https://www.comet.com/opik/api/v1/private/otel
export OTEL_EXPORTER_OTLP_HEADERS='Authorization=<your-api-key>,Comet-Workspace=default'
export N8N_OTEL_SERVICE_NAME=my-n8n
export EXTERNAL_HOOK_FILES=$(npm root -g)/n8n-observability/dist/hooks.cjs

# Start n8n
n8n start
```

#### Enterprise deployment

```bash wordWrap
export OTEL_EXPORTER_OTLP_ENDPOINT=https://<comet-deployment-url>/opik/api/v1/private/otel
export OTEL_EXPORTER_OTLP_HEADERS='Authorization=<your-api-key>,Comet-Workspace=default'
export N8N_OTEL_SERVICE_NAME=my-n8n
export EXTERNAL_HOOK_FILES=$(npm root -g)/n8n-observability/dist/hooks.cjs

# Start n8n
n8n start
```

#### Self-hosted instance

```bash
export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:5173/api/v1/private/otel
export OTEL_EXPORTER_OTLP_HEADERS='projectName=my-n8n-project'
export N8N_OTEL_SERVICE_NAME=my-n8n
export EXTERNAL_HOOK_FILES=$(npm root -g)/n8n-observability/dist/hooks.cjs

# Start n8n
n8n start
```

## Configuration

The following environment variables can be used to configure the integration:

| Variable                      | Purpose                                   | Default |
| ----------------------------- | ----------------------------------------- | ------- |
| `OTEL_EXPORTER_OTLP_ENDPOINT` | OTLP exporter endpoint                    | —       |
| `OTEL_EXPORTER_OTLP_HEADERS`  | OTLP headers (e.g., auth tokens)          | —       |
| `N8N_OTEL_SERVICE_NAME`       | Service name for telemetry                | `n8n`   |
| `N8N_OTEL_NODE_INCLUDE`       | Only trace listed nodes (comma-separated) | —       |
| `N8N_OTEL_NODE_EXCLUDE`       | Exclude listed nodes (comma-separated)    | —       |
| `N8N_OTEL_CAPTURE_INPUT`      | Capture node input data                   | `true`  |
| `N8N_OTEL_CAPTURE_OUTPUT`     | Capture node output data                  | `true`  |
| `N8N_OTEL_AUTO_INSTRUMENT`    | Enable HTTP/Express instrumentation       | `false` |
| `N8N_OTEL_METRICS`            | Enable metrics collection                 | `false` |
| `N8N_OTEL_DEBUG`              | Enable debug logging                      | `false` |
| `EXTERNAL_HOOK_FILES`         | Path to hooks.cjs (set automatically)     | —       |

### Node Filtering

You can filter which nodes are traced using environment variables:

```bash
# Only trace specific nodes
export N8N_OTEL_NODE_INCLUDE="OpenAI,HTTP Request"

# Exclude noisy nodes
export N8N_OTEL_NODE_EXCLUDE="Wait,Set"

# Disable I/O capture for privacy
export N8N_OTEL_CAPTURE_INPUT=false
export N8N_OTEL_CAPTURE_OUTPUT=false
```

## What Gets Tracked

### Workflow Spans

Each workflow execution creates a span with the following attributes:

* `n8n.workflow.id` - Workflow ID
* `n8n.workflow.name` - Workflow name
* `n8n.span.type` - `"workflow"`

### Node Spans

Each node operation creates a span with:

* `n8n.node.type` - Node type (e.g., `n8n-nodes-base.httpRequest`)
* `n8n.node.name` - Node name
* `n8n.span.type` - `"llm"`, `"prompt"`, `"evaluation"`, or undefined
* `n8n.node.input` - JSON input (if capture enabled)
* `n8n.node.output` - JSON output (if capture enabled)
* `gen_ai.system` - AI provider (e.g., `openai`, `anthropic`)
* `gen_ai.request.model` - Model name (e.g., `gpt-4`)

## Verify Installation

Check that the package is installed correctly:

```bash
node -e "console.log(require.resolve('n8n-observability/hooks'))"
```

On startup, you should see logs similar to:

```
[otel-setup] OpenTelemetry initialized: my-n8n (OTLP export enabled, n8n spans only)
[n8n-observability] observability ready and patches applied
```

## Further Improvements

If you would like to see us improve this integration, please open a new feature
request on [GitHub](https://github.com/comet-ml/opik/issues).

For issues specific to the n8n-observability package, visit the [n8n-observability repository](https://github.com/comet-ml/n8n-observability).