gitlabreceiver

README

GitLab Receiver

Status
Stability	alpha: traces
Distributions	contrib
Issues
Code coverage
Code Owners	@adrielp, @atoulme

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.

Documentation

Index

• Constants
• func NewFactory() receiver.Factory
• type Config
  • func (cfg *Config) Unmarshal(componentParser *confmap.Conf) error
  • func (cfg *Config) Validate() error
• type GitlabEvent
• type GitlabHeaders
• type WebHook

Constants

const (
	// The following attributes are not part of semconv yet, but potential candidates for future inclusion
	// They are highly experimental and subject to change
	AttributeVCSRepositoryVisibility = "vcs.repository.visibility"
	AttributeVCSRepositoryRefDefault = "vcs.repository.ref.default"

	AttributeVCSRefHeadRevisionMessage     = "vcs.ref.head.revision.message"
	AttributeVCSRefHeadRevisionTimestamp   = "vcs.ref.head.revision.timestamp"
	AttributeVCSRefHeadRevisionAuthorName  = "vcs.ref.head.revision.author.name"
	AttributeVCSRefHeadRevisionAuthorEmail = "vcs.ref.head.revision.author.email"

	AttributeCICDPipelineRunActorID   = "cicd.pipeline.run.actor.id"
	AttributeCICDPipelineRunActorName = "cicd.pipeline.run.actor.name"

	AttributeCICDTaskEnvironmentName = "cicd.pipeline.task.run.environment.name"

	AttributeCICDWorkerType   = "cicd.worker.type"
	AttributeCICDWorkerTags   = "cicd.worker.tags"
	AttributeCICDWorkerShared = "cicd.worker.shared"

	// The following attributes are EXCLUSIVE to GitLab but not listed under Vendor Extensions within Semantic Conventions yet
	// They are highly experimental and subject to change
	AttributeGitLabProjectNamespace = "gitlab.project.namespace"

	AttributeGitLabPipelineRunActorUsername = "gitlab.pipeline.run.actor.username"

	AttributeGitLabPipelineSource              = "gitlab.pipeline.source" // Source of the pipeline: https://docs.gitlab.com/ci/jobs/job_rules/#ci_pipeline_source-predefined-variable
	AttributeGitLabPipelineSourcePipelineID    = "gitlab.pipeline.source.pipeline.id"
	AttributeGitLabPipelineSourcePipelineJobID = "gitlab.pipeline.source.pipeline.job.id"

	AttributeGitLabPipelineSourcePipelineProjectID        = "gitlab.pipeline.source.pipeline.project.id"
	AttributeGitLabPipelineSourcePipelineProjectNamespace = "gitlab.pipeline.source.pipeline.project.namespace"
	AttributeGitLabPipelineSourcePipelineProjectURL       = "gitlab.pipeline.source.pipeline.project.url"

	AttributeGitLabJobQueuedDuration = "gitlab.job.queued_duration"
	AttributeGitLabJobFailureReason  = "gitlab.job.failure_reason"
	AttributeGitLabJobAllowFailure   = "gitlab.job.allow_failure"

	AttributeGitLabEnvironmentAction         = "gitlab.environment.action"
	AttributeGitLabEnvironmentDeploymentTier = "gitlab.environment.deployment_tier"
)

Functions

func NewFactory

func NewFactory() receiver.Factory

Types

type Config

type Config struct {
	WebHook WebHook `mapstructure:"webhook"`
	// contains filtered or unexported fields
}

Config that is exposed to this gitlab receiver through the OTEL config.yaml

func (*Config) Unmarshal

func (cfg *Config) Unmarshal(componentParser *confmap.Conf) error

func (*Config) Validate

func (cfg *Config) Validate() error

type GitlabEvent

type GitlabEvent interface {
	// contains filtered or unexported methods
}

GitlabEvent abstracts span setup for different GitLab event types (pipeline, stage, job) It enables unified span creation logic while allowing type-specific customization It must be implemented by all GitLab event types (pipeline, stage, job) to create spans

type GitlabHeaders

type GitlabHeaders struct {
	Customizable map[string]string `mapstructure:","` // can be overwritten via required_headers
	Fixed        map[string]string `mapstructure:","` // are not allowed to be overwritten
	// contains filtered or unexported fields
}

type WebHook

type WebHook struct {
	confighttp.ServerConfig `mapstructure:",squash"` // squash ensures fields are correctly decoded in embedded struct

	Path       string `mapstructure:"path"`        // path for data collection. default is /events
	HealthPath string `mapstructure:"health_path"` // path for health check api. default is /health_check

	RequiredHeaders map[string]configopaque.String `mapstructure:"required_headers"` // optional setting to set one or more required headers for all requests to have (except the health check)
	GitlabHeaders   GitlabHeaders                  `mapstructure:",squash"`          // GitLab headers set by default

	Secret string `mapstructure:"secret"` // secret for webhook

	// IncludeUserAttributes controls whether user information (commit author, pipeline actor) is included
	// Default: false (user information is excluded by default for privacy)
	IncludeUserAttributes bool `mapstructure:"include_user_attributes"`
}