Show CI/CD pipeline telemetry for Observability

When enabled, GitLab Observability automatically instruments your CI/CD pipelines, providing visibility into pipeline performance, job durations, and execution flow without any code changes.

• Visibility into which jobs are slowing down your pipelines.
• How pipeline performance changes over time.
• Bottlenecks in your deployment process.

Enable pipeline instrumentation

To enable automatic pipeline instrumentation, add the GITLAB_OBSERVABILITY_EXPORT CI/CD variable to your project or group:

1. In the top bar, select Search or go to and find your project or group.
2. In the left sidebar, select Settings > CI/CD.
3. Expand Variables.
4. Select Add variable.
5. Configure the variable:
   • Key: GITLAB_OBSERVABILITY_EXPORT
   • Value: One or more of traces, metrics, logs (comma-separated for multiple values)
   • Type: Variable
   • Environment scope: All (or specific environments)
6. Select Add variable.

Authenticate exported data (optional)

If your GitLab Observability instance requires bearer-token authorization on its OTLP endpoint, provide the token through the GITLAB_OBSERVABILITY_TOKEN CI/CD variable. When set, GitLab sends it as an Authorization: Bearer <token> header with the exported telemetry. When the variable is not set, GitLab exports the data without an Authorization header, exactly as before.

1. In the top bar, select Search or go to and find your project or group.
2. In the left sidebar, select Settings > CI/CD.
3. Expand Variables.
4. Select Add variable.
5. Configure the variable:
   • Key: GITLAB_OBSERVABILITY_TOKEN
   • Value: The token generated in your GitLab Observability instance.
   • Type: Variable
   • Flags: Select Mask variable so the token is not exposed in job logs.
6. Select Add variable.

Instrumentation types

The GITLAB_OBSERVABILITY_EXPORT variable accepts the following values:

• traces: Exports distributed traces showing pipeline execution flow, job dependencies, and timing
• metrics: Exports metrics about pipeline duration, job success rates, and resource usage
• logs: Exports structured logs from pipeline execution

You can enable multiple types by separating them with commas:

traces,metrics,logs

Exported data

GitLab exports each signal type as OpenTelemetry Protocol (OTLP) data. Every attribute is emitted under both a legacy GitLab namespace (pipeline.*, job.*, gitlab.*) and, where one exists, the equivalent OpenTelemetry CI/CD semantic convention namespace (cicd.*, vcs.*).

Traces

Each pipeline is exported as a single resource span containing one pipeline span and one job span for each job or bridge in the pipeline.

The resource carries the following attributes:

The pipeline span carries the following attributes:

The job span carries the following attributes for each job or bridge:

For child pipelines triggered by a bridge job, GitLab links the child pipeline’s trace to the triggering job’s span. The parent and child pipelines then appear as a single connected trace.

Metrics

GitLab exports the following metrics for each pipeline:

Metric data points carry attributes such as pipeline.status, pipeline.ref, cicd.pipeline.name, cicd.pipeline.result, gitlab.cicd.pipeline.trigger.type, and vcs.ref.head.type. The job.duration_seconds and cicd.pipeline.task.duration histograms carry a job.stage attribute for each data point. The resource for metric data also carries a gitlab.cicd.pipeline.trace_id attribute so metrics can be correlated with the pipeline’s trace. The cicd.pipeline.run.errors data point carries an error.type attribute.

Logs

GitLab exports one log record for the pipeline and one log record for each job. Each log record has the following fields:

Attribute value mapping

GitLab maps its internal status values to the enum values defined by the OpenTelemetry CI/CD semantic conventions.

Pipeline and job result (cicd.pipeline.result, cicd.pipeline.task.run.result):

Pipeline and job run state (cicd.pipeline.run.state, cicd.pipeline.task.run.state):

Runner state (cicd.worker.state):

How it works

Once the variable is set, GitLab automatically:

1. Captures pipeline execution data after each pipeline completes
2. Converts the data to OpenTelemetry format based on your configuration
3. Exports the telemetry data to your GitLab Observability instance
4. Makes the data available in your observability dashboards

No changes to your .gitlab-ci.yml file are required. The instrumentation happens automatically in the background.

View pipeline telemetry

After running pipelines with instrumentation enabled:

1. In the top bar, select Search or go to and find your group or project.
2. In the left sidebar, select Observe > Services.
3. Select your gitlab-ci service to view traces, metrics, and logs from your pipeline executions.

The CI/CD dashboard template from GitLab Observability Templates provides pre-built visualizations for pipeline performance analysis.

Related topics

• Troubleshooting Observability