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

Then set the required environment variables:

<Tabs>
  <Tab value="Opik Cloud" title="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
    ```
  </Tab>

  <Tab value="Enterprise deployment" title="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
    ```
  </Tab>

  <Tab value="Self-hosted instance" title="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
    ```
  </Tab>
</Tabs>

## 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