> For the complete documentation index, see [llms.txt](https://docs.ionos.com/cloud/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.ionos.com/cloud/tutorials/observability/tracing-service/trace-n8n-workflows-with-tracing-service.md).
# Trace n8n Workflow Executions with the Tracing Service
## Overview
This tutorial demonstrates how to export execution traces from [n8n](https://n8n.io/) into the space.vars.ionos\_cloud Tracing Service (powered by Grafana Tempo). Using n8n's built-in OpenTelemetry support, you will send workflow and node execution spans to a tracing pipeline through the standard OpenTelemetry Protocol (OTLP), without changing any workflow logic or writing code. You will then explore the traces in Grafana to see how long each node takes and where a workflow spends its time.
{% hint style="info" %}
This tutorial covers n8n workflow and node execution tracing. n8n also offers a separate AI agent tracing feature; to trace AI agents and LLM calls with `gen_ai.*` span attributes, see [Trace an AI Agent That Uses AI Model Hub with the Tracing Service](/cloud/tutorials/observability/tracing-service/trace-ai-agent-using-ai-model-hub-with-tracing-service.md).
{% endhint %}
## Target audience
This tutorial benefits DevOps engineers, platform teams, and automation developers who run n8n and want centralized visibility into workflow performance and failures. Readers benefit from basic familiarity with:
* Running containers with Docker
* Environment-variable configuration
* The space.vars.ionos\_cloud Console and API authentication
* Grafana and trace exploration concepts
## What you will learn
* How to create a space.vars.ionos\_cloud tracing pipeline and retrieve its ingestion endpoint and key.
* How to activate n8n's built-in OpenTelemetry export using the settings UI or environment variables.
* How to point n8n at your tracing pipeline over OTLP/HTTP.
* How to run a workflow and view its trace in Grafana.
* How to query traces with TraceQL and troubleshoot common ingestion problems.
## Before you begin
Ensure you have:
* An active space.vars.ionos\_cloud account with the **Access and manage Tracing** privilege.
* An space.vars.ionos\_cloud API token to create the pipeline. To generate a token, see [Token Manager](https://docs.ionos.com/cloud/set-up-ionos-cloud/management/identity-access-management/token-manager).
* Docker installed on a host with outbound `HTTPS` access on port `443`.
* Basic familiarity with the [Tracing Service documentation](https://docs.ionos.com/cloud/observability/tracing-service).
## Cost considerations
This tutorial creates a billable space.vars.ionos\_cloud tracing pipeline. Charges are based on the volume of trace data ingested and stored. There is no base fee and no minimum commitment.
Delete the pipeline after you finish to avoid ongoing charges. For current rates, see the [IONOS CLOUD price list (EUR)](https://docs.ionos.com/cloud/support/general-information/price-list/ionos-cloud-eur-en).
## Architecture
The diagram below shows the data flow from n8n to Grafana:
n8n's OpenTelemetry module creates a span for each workflow execution and a child span for each node. It exports them over OTLP/HTTP to your tracing pipeline, where they are stored in Tempo and become searchable in Grafana.
## Procedure
{% stepper %}
{% step %}
**Create a tracing pipeline.**
Create a pipeline configured for the `otlp-http` protocol. Send a `POST` request to the regional Tracing Service API endpoint, replacing the region host as needed:
```bash
curl --location \
--request POST 'https://tracing.de-txl.ionos.com/pipelines' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer ' \
--data '{
"metadata": {},
"properties": {
"name": "n8n-tracing",
"protocol": "otlp-http"
}
}'
```
The create response returns the pipeline **`id`** and the **ingestion key** (`key`). Save the key immediately: it is returned only once, on creation.
{% hint style="warning" %}
**Warning:** Save the key immediately. The Tracing Service returns the ingestion key only once. Store it securely, such as in a password manager. If you lose it, rotate the pipeline key through the [Tracing Service API](https://api.ionos.com/docs/tracing/v1/) to generate a new one.
{% endhint %}
The create response does not include the ingestion endpoint. Retrieve the **ingestion endpoint** and the **`grafanaEndpoint`** with a follow-up `GET` request, using the pipeline `id` from the previous response:
```bash
curl --location \
--request GET 'https://tracing.de-txl.ionos.com/pipelines/' \
--header 'Authorization: Bearer '
```
From this response, save:
* The **ingestion endpoint** (the `otlp-http` traces endpoint, of the form `https:///v1/traces`).
* The **`grafanaEndpoint`**, the Grafana instance address for exploring traces.
For more information on pipelines, endpoints, and regions, see [Tracing Pipelines](https://docs.ionos.com/cloud/observability/tracing-service/overview/tracing-pipelines).
{% endstep %}
{% step %}
**Activate OpenTelemetry export in n8n.**
You can point n8n at your tracing pipeline in two ways. Use **Option A** if you configure n8n through its settings UI, or **Option B** for headless and containerized deployments. Both send the same workflow and node spans.
**Option A: Configure in the n8n UI**
In n8n, open the **OpenTelemetry** settings and configure the collector connection, then set **Status** to **Enabled**:
Set the fields as follows:
* **OTLP endpoint**: the base host of your pipeline, `https://`. Do not include `/v1/traces` here; that is set separately in **Trace path**.
* **Custom headers**: add a header with key `apikey` and the pipeline ingestion key as its value.
* **Trace path**: `/v1/traces` (the OTLP default).
* **Include node spans**: activate this to get one span per node in addition to the workflow-level span.
* **Track published workflows only**: leave this off while testing so manual (editor) executions are also traced. Activate it to trace only production executions.
Use **Send test trace** to confirm n8n can reach your pipeline before running a workflow.
**Option B: Configure with environment variables**
Start n8n with the OpenTelemetry environment variables set. Replace `` and `` with the ingestion endpoint host and key from the previous step.
```bash
docker run -it --rm \
--name n8n \
-p 5678:5678 \
-v ~/.n8n:/home/node/.n8n \
-e N8N_OTEL_ENABLED=true \
-e N8N_OTEL_TRACES_PRODUCTION_ONLY=false \
-e N8N_OTEL_EXPORTER_OTLP_ENDPOINT="https://" \
-e N8N_OTEL_EXPORTER_OTLP_TRACING_PATH="/v1/traces" \
-e N8N_OTEL_EXPORTER_OTLP_HEADERS="apikey=" \
n8nio/n8n
```
The variables do the following:
* `N8N_OTEL_ENABLED=true`: turns on n8n's OpenTelemetry module.
* `N8N_OTEL_TRACES_PRODUCTION_ONLY=false`: also traces manual (editor) executions, so you can test without activating the workflow. Set to `true` to trace only production executions.
* `N8N_OTEL_EXPORTER_OTLP_ENDPOINT`: the base host of your tracing pipeline, without the `/v1/traces` path.
* `N8N_OTEL_EXPORTER_OTLP_TRACING_PATH`: the traces path appended to the endpoint (`/v1/traces`).
* `N8N_OTEL_EXPORTER_OTLP_HEADERS`: passes the pipeline key as the `apikey` header for authentication.
{% hint style="info" %}
**Note:** Set the endpoint and path separately. In both the UI and the environment variables, the endpoint is the base host (`https://`) and `/v1/traces` is set separately (the UI **Trace path** field, or `N8N_OTEL_EXPORTER_OTLP_TRACING_PATH`). Do not append `/v1/traces` to the endpoint, or n8n appends it twice.
{% endhint %}
{% hint style="info" %}
**Note:** Environment variables must be passed to `docker run`. A shell `export` on the host is not inherited by `docker run`; you must forward each value with `-e`. Verify the values are set with `docker exec n8n env | grep N8N_OTEL`.
{% endhint %}
{% endstep %}
{% step %}
**Build and run a workflow.**
Open the n8n editor at `http://localhost:5678` and create a workflow, for example a **Manual Trigger** node connected to an **HTTP Request** node (or any two nodes). Run it with the **Test workflow** button (manual execution), or activate the workflow and trigger it through its production URL.
The workflow completes without errors. n8n emits one span for the workflow execution and one child span for each node that ran.
{% endstep %}
{% step %}
**View traces in Grafana.**
Open Grafana using the `grafanaEndpoint` you retrieved. For more information, see [Access Traces from the Platform](https://docs.ionos.com/cloud/observability/tracing-service/quick-start/access-traces-from-platform). Open **Explore** and select the Tracing (Tempo) data source, which is provisioned automatically for your contract and region.
Search for your traces using the search builder, or run a TraceQL query. n8n names the workflow span `workflow.execute` and each node span `node.execute`, so you can query the workflow span directly:
```
{ name = "workflow.execute" }
```
To list every span from this n8n instance regardless of type, filter by the service name you configured (the default is `n8n`):
```
{ resource.service.name = "n8n" }
```
Open a `workflow.execute` trace to see its `node.execute` child spans nested underneath, each showing its duration. Click a node span to inspect its attributes, such as `n8n.node.name`, `n8n.node.type`, and `n8n.node.items.input`/`n8n.node.items.output`.
{% hint style="info" %}
**Info:** Node names and types reflect your workflow. The `n8n.node.name` and `n8n.node.type` values in the trace come from the nodes in your own workflow, so your spans will differ from this example.
{% endhint %}
**Result:** Your n8n workflow executions now appear as traces in Grafana, with each `node.execute` span nested under its `workflow.execute` trace, showing per-node durations and attributes.
{% endstep %}
{% endstepper %}
## Troubleshooting
1. **No traces appear:** Confirm the pipeline is in `AVAILABLE` state and that `N8N_OTEL_EXPORTER_OTLP_ENDPOINT` and `N8N_OTEL_EXPORTER_OTLP_HEADERS` are set in the running n8n instance (`docker exec n8n env`).
2. **Authentication errors (`401`):** Verify the `apikey` value matches the current pipeline key. Rotate the key through the API if unsure.
3. **Connection errors:** Verify outbound `HTTPS` access on port `443` from the n8n host.
4. **Only production traces appear:** Set `N8N_OTEL_TRACES_PRODUCTION_ONLY=false` to include manual (editor) executions, and restart n8n. Environment changes require a restart.
5. **Endpoint path:** Set `N8N_OTEL_EXPORTER_OTLP_ENDPOINT` to the base host only and put `/v1/traces` in `N8N_OTEL_EXPORTER_OTLP_TRACING_PATH` (or the UI **Trace path**). Including `/v1/traces` in the endpoint makes n8n append it twice.
## Decommission resources
Delete the tracing pipeline through the API to stop billing, using the pipeline `id` from the creation response:
```bash
curl --location \
--request DELETE 'https://tracing.de-txl.ionos.com/pipelines/' \
--header 'Authorization: Bearer '
```
Then stop n8n (`docker stop n8n`).
## Next steps
* [Trace an AI Agent That Uses AI Model Hub with the Tracing Service](/cloud/tutorials/observability/tracing-service/trace-ai-agent-using-ai-model-hub-with-tracing-service.md)
* [Tracing Service documentation](https://docs.ionos.com/cloud/observability/tracing-service)
* [n8n OpenTelemetry documentation](https://docs.n8n.io/deploy/host-n8n/configure-n8n/basic-configuration/use-environment-variables/opentelemetry)
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:
```
GET https://docs.ionos.com/cloud/tutorials/observability/tracing-service/trace-n8n-workflows-with-tracing-service.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.