Skip to main content

​
Gitlab Receiver

Status Available in: contrib Maintainers: @adrielp, @atoulme, @niwoerner Source: opentelemetry-collector-contrib

​
Supported Telemetry

Traces

​
Overview

​
Traces - Getting Started

Workflow tracing support is actively being added to the GitLab receiver. This is accomplished through the processing of GitLab webhook events for pipelines. The pipeline event payloads are then constructed into trace telemetry. Each GitLab pipeline, along with its jobs, is converted into trace spans, allowing the observation of workflow execution times, success, and failure rates.

​
Configuration

IMPORTANT: Ensure your WebHook endpoint is secured with a secret and a Web Application Firewall (WAF) or other security measure. The WebHook configuration exposes the following settings:
  • endpoint: (default = localhost:8080) - The address and port to bind the WebHook to.
  • path: (default = /events) - The path for Action events to be sent to.
  • health_path: (default = /health) - The path for health checks.
  • secret: (optional) - The secret used to validate the payload.
  • required_headers: (optional) - One or more key-value pairs representing required headers for incoming requests. These headers must not conflict with the fixed default GitLab headers. See the customizable and fixed GitLab headers in config.go.
  • include_user_attributes: (default = false) - When enabled, includes user information such as commit author details (name, email), commit messages, and pipeline actor information (username, name) in the span attributes.
The WebHook configuration block also accepts all the confighttp settings. An example configuration is as follows: 
receivers:
    gitlab:
        webhook:
            endpoint: localhost:19418
            path: /events
            health_path: /health
            secret: ${env:SECRET_STRING_VAR}
            required_headers:
                WAF-Header: "value"
            include_user_attributes: false
For tracing, all configuration is set under the webhook key. The full set of exposed configuration values can be found in config.go.

​
Tracing Limitations

​
Deterministic Trace/Span IDs and Manual Instrumentation

The GitLab receiver creates deterministic trace/span IDs for pipelines by using an unique pipeline/job ID and the pipeline’s finished_at timestamp. This approach ensures that the same pipeline execution always generates the same ID. Limitation: Manual instrumentation within GitLab pipeline jobs is currently not possible. Since the trace ID generation requires the finished_at timestamp, which is only available once the pipeline has completed, it’s not possible to generate the same traceID within running jobs to correlate manually instrumented spans with the automatically created pipeline spans. More details can be found here. This means:
  • The receiver can automatically create traces/spans for GitLab pipelines
  • You cannot manually instrument code within your pipeline jobs and have those spans appear in the same trace as the pipeline spans

​
Child and Multi-Project Pipelines

Limitation: Child and multi-project pipelines are not supported yet. The hierarchy between parent/trigger pipelines wouldn’t be reflected correctly, and instead two independent traces would be created for each pipeline. This means that the parent-child relationship between pipelines is not preserved in the generated traces.

​
Configuration

​
Example Configuration

receivers:
  gitlab:
    webhook:
      endpoint: localhost:8080
      read_timeout: "500ms"
      write_timeout: "500ms"
      path: "some/path"
      health_path: "health/path"
      required_headers:
        key1-present: "value1-present"

  gitlab/customname:
    webhook:
      endpoint: localhost:8080
      read_timeout: "500ms"
      write_timeout: "500ms"
      path: "some/path"
      health_path: "health/path"
      required_headers:
        key1-present: "value1-present"
        key2-present: "value2-present" 
        User-Agent: "GitLab/1.2.3-custom-version"        
        X-Gitlab-Instance: "https://gitlab.self-hosted.xyz"
        
processors:
  nop:

exporters:
  nop:

service:
  pipelines:
    traces:
      receivers: [gitlab, gitlab/customname]
      processors: [nop]
      exporters: [nop]
Last generated: 2026-04-13