[receiver/gitlab] add tracing functionality (open-telemetry#39123)

#### Description
This PR adds tracing functonality for the gitlabreceiver. It's only
possible to create deterministic Trace/SpanIDs once a pipeline is
finished. Correlation with manual instrumented jobs during pipeline
runtime is not possible because of limitations in Gitlab. More details
can be found
[here](open-telemetry/semantic-conventions#1749 (comment))

(I would like to become an OpenTelemetry member to be a codeowner of the
gitlabreceiver - would someone be willing to sponsor the membership for
me? - Thank you! :) )

#### Link to tracking issue
 open-telemetry#35207

#### Testing
Added unit tests and performed manual testing

#### Documentation
Updated README how to use the receiver

Author: niwoerner

.chloggen/gitlabreceiver-tracing-functonality.yaml

@@ -0,0 +1,27 @@
+# Use this changelog template to create an entry for release notes.
+
+# One of 'breaking', 'deprecation', 'new_component', 'enhancement', 'bug_fix'
+change_type: enhancement
+
+# The name of the component, or a single word describing the area of concern, (e.g. filelogreceiver)
+component: gitlabreceiver
+
+# A brief description of the change.  Surround your text with quotes ("") if it needs to start with a backtick (`).
+note: add GitLab pipeline tracing functionality
+
+# Mandatory: One or more tracking issues related to the change. You can use the PR number here if no issue exists.
+issues: [35207]
+
+# (Optional) One or more lines of additional information to render under the primary note.
+# These lines will be padded with 2 spaces and then inserted directly into the document.
+# Use pipe (|) for multiline entries.
+subtext:
+
+# If your change doesn't affect end users or the exported elements of any package,
+# you should instead start your pull request title with [chore] or use the "Skip Changelog" label.
+# Optional: The change log or logs in which this entry should be included.
+# e.g. '[user]' or '[user, api]'
+# Include 'user' if the change is relevant to end users.
+# Include 'api' if there is a change to a library API.
+# Default: '[user]'
+change_logs: []

receiver/gitlabreceiver/README.md

@@ -25,7 +25,8 @@ success, and failure rates.
 
 ### Configuration
 
-**IMPORTANT: At this time the tracing portion of this receiver only serves a health check endpoint.**
+**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:
 
@@ -54,3 +55,19 @@ receivers:
 
 For tracing, all configuration is set under the `webhook` key. The full set
 of exposed configuration values can be found in [`config.go`](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](https://github.com/open-telemetry/semantic-conventions/issues/1749#issuecomment-2772544215).
+
+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.

receiver/gitlabreceiver/config.go

@@ -25,11 +25,13 @@ const (
 
 	// GitLab default headers: https://docs.gitlab.com/ee/user/project/integrations/webhooks.html#delivery-headers
 	defaultUserAgentHeader         = "User-Agent"
-	defaultGitlabInstanceHeader    = "X-Gitlab-Instance"
-	defaultGitlabWebhookUUIDHeader = "X-Gitlab-Webhook-UUID"
-	defaultGitlabEventHeader       = "X-Gitlab-Event"
-	defaultGitlabEventUUIDHeader   = "X-Gitlab-Event-UUID"
+	defaultGitLabInstanceHeader    = "X-Gitlab-Instance"
+	defaultGitLabWebhookUUIDHeader = "X-Gitlab-Webhook-UUID"
+	defaultGitLabEventHeader       = "X-Gitlab-Event"
+	defaultGitLabEventUUIDHeader   = "X-Gitlab-Event-UUID"
 	defaultIdempotencyKeyHeader    = "Idempotency-Key"
+	// #nosec G101 - Not an actual secret, just the name of a header: https://docs.gitlab.com/user/project/integrations/webhooks/#create-a-webhook
+	defaultGitLabSecretTokenHeader = "X-Gitlab-Token"
 )
 
 var (
@@ -73,12 +75,12 @@ func createDefaultConfig() component.Config {
 			GitlabHeaders: GitlabHeaders{
 				Customizable: map[string]string{
 					defaultUserAgentHeader:      "",
-					defaultGitlabInstanceHeader: "https://gitlab.com",
+					defaultGitLabInstanceHeader: "https://gitlab.com",
 				},
 				Fixed: map[string]string{
-					defaultGitlabWebhookUUIDHeader: "",
-					defaultGitlabEventHeader:       "Pipeline Hook",
-					defaultGitlabEventUUIDHeader:   "",
+					defaultGitLabWebhookUUIDHeader: "",
+					defaultGitLabEventHeader:       "Pipeline Hook",
+					defaultGitLabEventUUIDHeader:   "",
 					defaultIdempotencyKeyHeader:    "",
 				},
 			},

receiver/gitlabreceiver/config_test.go

@@ -35,12 +35,12 @@ func TestCreateDefaultConfig(t *testing.T) {
 			GitlabHeaders: GitlabHeaders{
 				Customizable: map[string]string{
 					defaultUserAgentHeader:      "",
-					defaultGitlabInstanceHeader: "https://gitlab.com",
+					defaultGitLabInstanceHeader: "https://gitlab.com",
 				},
 				Fixed: map[string]string{
-					defaultGitlabWebhookUUIDHeader: "",
-					defaultGitlabEventHeader:       "Pipeline Hook",
-					defaultGitlabEventUUIDHeader:   "",
+					defaultGitLabWebhookUUIDHeader: "",
+					defaultGitLabEventHeader:       "Pipeline Hook",
+					defaultGitLabEventUUIDHeader:   "",
 					defaultIdempotencyKeyHeader:    "",
 				},
 			},
@@ -80,12 +80,12 @@ func TestLoadConfig(t *testing.T) {
 			GitlabHeaders: GitlabHeaders{
 				Customizable: map[string]string{
 					defaultUserAgentHeader:      "",
-					defaultGitlabInstanceHeader: "https://gitlab.com",
+					defaultGitLabInstanceHeader: "https://gitlab.com",
 				},
 				Fixed: map[string]string{
-					defaultGitlabWebhookUUIDHeader: "",
-					defaultGitlabEventHeader:       "Pipeline Hook",
-					defaultGitlabEventUUIDHeader:   "",
+					defaultGitLabWebhookUUIDHeader: "",
+					defaultGitLabEventHeader:       "Pipeline Hook",
+					defaultGitLabEventUUIDHeader:   "",
 					defaultIdempotencyKeyHeader:    "",
 				},
 			},
@@ -107,12 +107,12 @@ func TestLoadConfig(t *testing.T) {
 	expectedConfig.WebHook.GitlabHeaders = GitlabHeaders{
 		Customizable: map[string]string{
 			defaultUserAgentHeader:      "GitLab/1.2.3-custom-version",
-			defaultGitlabInstanceHeader: "https://gitlab.self-hosted.xyz",
+			defaultGitLabInstanceHeader: "https://gitlab.self-hosted.xyz",
 		},
 		Fixed: map[string]string{
-			defaultGitlabWebhookUUIDHeader: "",
-			defaultGitlabEventHeader:       "Pipeline Hook",
-			defaultGitlabEventUUIDHeader:   "",
+			defaultGitLabWebhookUUIDHeader: "",
+			defaultGitLabEventHeader:       "Pipeline Hook",
+			defaultGitLabEventUUIDHeader:   "",
 			defaultIdempotencyKeyHeader:    "",
 		},
 	}

receiver/gitlabreceiver/go.mod

@@ -24,10 +24,14 @@ require (
 	github.com/foxboron/go-tpm-keyfiles v0.0.0-20250323135004-b31fac66206e // indirect
 	github.com/go-ole/go-ole v1.2.6 // indirect
 	github.com/gobwas/glob v0.2.3 // indirect
+	github.com/google/go-querystring v1.1.0 // indirect
 	github.com/google/go-tpm v0.9.5 // indirect
 	github.com/grpc-ecosystem/grpc-gateway/v2 v2.26.1 // indirect
+	github.com/hashicorp/go-cleanhttp v0.5.2 // indirect
+	github.com/hashicorp/go-retryablehttp v0.7.7 // indirect
 	github.com/hashicorp/go-version v1.7.0 // indirect
 	github.com/inconshreveable/mousetrap v1.1.0 // indirect
+	github.com/json-iterator/go v1.1.12 // indirect
 	github.com/lufia/plan9stats v0.0.0-20211012122336-39d0f177ccd0 // indirect
 	github.com/munnerz/goautoneg v0.0.0-20191010083416-a7dc8b61c822 // indirect
 	github.com/power-devops/perfstat v0.0.0-20210106213030-5aafc221ea8c // indirect
@@ -90,6 +94,8 @@ require (
 	go.opentelemetry.io/proto/otlp v1.5.0 // indirect
 	golang.org/x/crypto v0.38.0 // indirect
 	golang.org/x/exp v0.0.0-20240506185415-9bf2ced13842 // indirect
+	golang.org/x/oauth2 v0.26.0 // indirect
+	golang.org/x/time v0.10.0 // indirect
 	gonum.org/v1/gonum v0.16.0 // indirect
 	google.golang.org/genproto/googleapis/api v0.0.0-20250218202821-56aae31c358a // indirect
 	sigs.k8s.io/yaml v1.4.0 // indirect
@@ -106,7 +112,6 @@ require (
 	github.com/golang/snappy v1.0.0 // indirect
 	github.com/google/uuid v1.6.0 // indirect
 	github.com/gorilla/mux v1.8.1
-	github.com/json-iterator/go v1.1.12 // indirect
 	github.com/klauspost/compress v1.18.0 // indirect
 	github.com/knadh/koanf/maps v0.1.2 // indirect
 	github.com/knadh/koanf/providers/confmap v1.0.0 // indirect
@@ -118,6 +123,7 @@ require (
 	github.com/pierrec/lz4/v4 v4.1.22 // indirect
 	github.com/pmezard/go-difflib v1.0.0 // indirect
 	github.com/rs/cors v1.11.1 // indirect
+	gitlab.com/gitlab-org/api/client-go v0.126.0
 	go.opentelemetry.io/collector/client v1.32.1-0.20250515040533-97a6accbc082 // indirect
 	go.opentelemetry.io/collector/component/componentstatus v0.126.1-0.20250515040533-97a6accbc082
 	go.opentelemetry.io/collector/config/configauth v0.126.1-0.20250515040533-97a6accbc082 // indirect
@@ -128,11 +134,11 @@ require (
 	go.opentelemetry.io/collector/consumer/consumererror v0.126.1-0.20250515040533-97a6accbc082 // indirect
 	go.opentelemetry.io/collector/extension v1.32.1-0.20250515040533-97a6accbc082 // indirect
 	go.opentelemetry.io/collector/otelcol/otelcoltest v0.126.1-0.20250515040533-97a6accbc082
-	go.opentelemetry.io/collector/pdata v1.32.1-0.20250515040533-97a6accbc082 // indirect
+	go.opentelemetry.io/collector/pdata v1.32.1-0.20250515040533-97a6accbc082
 	go.opentelemetry.io/collector/pdata/pprofile v0.126.1-0.20250515040533-97a6accbc082 // indirect
 	go.opentelemetry.io/collector/pipeline v0.126.1-0.20250515040533-97a6accbc082 // indirect
 	go.opentelemetry.io/contrib/instrumentation/net/http/otelhttp v0.60.0 // indirect
-	go.opentelemetry.io/otel v1.35.0 // indirect
+	go.opentelemetry.io/otel v1.35.0
 	go.opentelemetry.io/otel/metric v1.35.0 // indirect
 	go.opentelemetry.io/otel/sdk v1.35.0 // indirect
 	go.opentelemetry.io/otel/sdk/metric v1.35.0 // indirect