PF-9591-traceset added end-to-end W3C tracestate propagation to the agent

Author: SorchaAbel

agent/job_runner.go

@@ -480,6 +480,7 @@ BUILDKITE_TRACE_CONTEXT_ENCODING
 BUILDKITE_TRACING_BACKEND
 BUILDKITE_TRACING_SERVICE_NAME
 BUILDKITE_TRACING_TRACEPARENT
+BUILDKITE_TRACING_TRACESTATE
 BUILDKITE_TRACING_PROPAGATE_TRACEPARENT
 BUILDKITE_AGENT_AWS_KMS_KEY
 BUILDKITE_AGENT_GCP_KMS_KEY
@@ -695,6 +696,13 @@ BUILDKITE_AGENT_JWKS_KEY_ID`
 		if r.conf.Job.TraceParent != "" {
 			setEnv("BUILDKITE_TRACING_TRACEPARENT", r.conf.Job.TraceParent)
 		}
+		// Buildkite backend may also provide a tracestate property on the job,
+		// which carries vendor-specific trace context alongside the traceparent.
+		//
+		// https://www.w3.org/TR/trace-context/#tracestate-header
+		if r.conf.Job.TraceState != "" {
+			setEnv("BUILDKITE_TRACING_TRACESTATE", r.conf.Job.TraceState)
+		}
 		if r.conf.AgentConfiguration.TracingPropagateTraceparent {
 			setEnv("BUILDKITE_TRACING_PROPAGATE_TRACEPARENT", "true")
 		}

api/jobs.go

@@ -27,6 +27,7 @@ type Job struct {
 	RunnableAt            string                     `json:"runnable_at"`
 	ChunksFailedCount     int                        `json:"chunks_failed_count"`
 	TraceParent           string                     `json:"traceparent"`
+	TraceState            string                     `json:"tracestate"`
 	Priority              int                        `json:"priority"`
 }
 

clicommand/bootstrap.go

@@ -109,6 +109,7 @@ type BootstrapConfig struct {
 	TracingBackend               string   `cli:"tracing-backend"`
 	TracingServiceName           string   `cli:"tracing-service-name"`
 	TracingTraceParent           string   `cli:"tracing-traceparent"`
+	TracingTraceState            string   `cli:"tracing-tracestate"`
 	TracingPropagateTraceparent  bool     `cli:"tracing-propagate-traceparent"`
 	TraceContextEncoding         string   `cli:"trace-context-encoding"`
 	NoJobAPI                     bool     `cli:"no-job-api"`
@@ -339,6 +340,12 @@ var BootstrapCommand = cli.Command{
 			EnvVar: "BUILDKITE_TRACING_TRACEPARENT",
 			Value:  "",
 		},
+		cli.StringFlag{
+			Name:   "tracing-tracestate",
+			Usage:  "W3C Trace State for tracing",
+			EnvVar: "BUILDKITE_TRACING_TRACESTATE",
+			Value:  "",
+		},
 		cli.BoolFlag{
 			Name:   "tracing-propagate-traceparent",
 			Usage:  "Accept traceparent from Buildkite control plane (default: false)",
@@ -478,6 +485,7 @@ var BootstrapCommand = cli.Command{
 			TracingServiceName:           cfg.TracingServiceName,
 			TraceContextCodec:            traceContextCodec,
 			TracingTraceParent:           cfg.TracingTraceParent,
+			TracingTraceState:            cfg.TracingTraceState,
 			TracingPropagateTraceparent:  cfg.TracingPropagateTraceparent,
 			JobAPI:                       !cfg.NoJobAPI,
 			DisabledWarnings:             cfg.DisableWarningsFor,

internal/job/config.go

@@ -192,6 +192,10 @@ type ExecutorConfig struct {
 	// Traceing context information
 	TracingTraceParent string
 
+	// W3C tracestate accompanying TracingTraceParent. Only propagated when
+	// TracingPropagateTraceparent is enabled.
+	TracingTraceState string
+
 	// Accept traceparent context from Buildkite control plane
 	TracingPropagateTraceparent bool
 

internal/job/tracing.go

@@ -211,9 +211,16 @@ func (e *Executor) contextWithTraceparentIfEnabled(ctx context.Context) context.
 		return ctx
 	}
 
-	return otel.GetTextMapPropagator().Extract(ctx, propagation.MapCarrier{
+	carrier := propagation.MapCarrier{
 		"traceparent": e.TracingTraceParent,
-	})
+	}
+	// W3C tracestate is optional; include it only when the server provides one
+	// so the propagator doesn't try to parse an empty header.
+	if e.TracingTraceState != "" {
+		carrier["tracestate"] = e.TracingTraceState
+	}
+
+	return otel.GetTextMapPropagator().Extract(ctx, carrier)
 }
 
 func GenericTracingExtras(e *Executor, env *env.Environment) map[string]any {