docs: add tracing configuration guide and config examples

  Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: ci-operator

config/305-config-observability.yaml

@@ -21,8 +21,6 @@ metadata:
     app.kubernetes.io/version: "devel"
     app.kubernetes.io/part-of: pipelines-as-code
 data:
-  metrics-protocol: prometheus
-  metrics-endpoint: ":9090"
   _example: |
     ################################
     #                              #
@@ -50,4 +48,18 @@ data:
 
     # metrics-export-interval specifies how often metrics are exported.
     # Only applicable for grpc and http/protobuf protocols.
-    # metrics-export-interval: "30s"
+    # metrics-export-interval: "30s"
+
+    # tracing-protocol specifies the trace export protocol.
+    # Supported values: "grpc", "http/protobuf", "none".
+    # Default is "none" (tracing disabled).
+    # tracing-protocol: "none"
+
+    # tracing-endpoint specifies the OTLP collector endpoint.
+    # Required when tracing-protocol is "grpc" or "http/protobuf".
+    # The OTEL_EXPORTER_OTLP_ENDPOINT env var takes precedence if set.
+    # tracing-endpoint: "http://otel-collector.observability.svc.cluster.local:4317"
+
+    # tracing-sampling-rate controls the fraction of traces sampled.
+    # 0.0 = none, 1.0 = all. Default is 0 (none).
+    # tracing-sampling-rate: "1.0"

docs/content/docs/operations/tracing.md

@@ -0,0 +1,42 @@
+---
+title: Distributed Tracing
+weight: 5
+---
+
+This page describes how to enable OpenTelemetry distributed tracing for Pipelines-as-Code. When enabled, PaC emits trace spans for webhook event processing and PipelineRun lifecycle timing.
+
+## Enabling tracing
+
+The ConfigMap `pipelines-as-code-config-observability` controls tracing configuration. See [config/305-config-observability.yaml](https://github.com/tektoncd/pipelines-as-code/blob/main/config/305-config-observability.yaml) for the full example.
+
+It contains the following tracing fields:
+
+* `tracing-protocol`: Export protocol. Supported values: `grpc`, `http/protobuf`, `none`. Default is `none` (tracing disabled).
+* `tracing-endpoint`: OTLP collector endpoint. Required when protocol is not `none`. The `OTEL_EXPORTER_OTLP_ENDPOINT` environment variable takes precedence if set.
+* `tracing-sampling-rate`: Fraction of traces to sample. `0.0` = none, `1.0` = all. Default is `0`.
+
+### Example
+
+```yaml
+apiVersion: v1
+kind: ConfigMap
+metadata:
+  name: pipelines-as-code-config-observability
+  namespace: pipelines-as-code
+data:
+  tracing-protocol: grpc
+  tracing-endpoint: "http://otel-collector.observability.svc.cluster.local:4317"
+  tracing-sampling-rate: "1.0"
+```
+
+Changes to the ConfigMap are picked up automatically without restarting the controller. Set `tracing-protocol` to `none` or remove the tracing keys to disable tracing.
+
+## Emitted spans
+
+The controller emits a `PipelinesAsCode:ProcessEvent` span covering the full lifecycle of each webhook event, from receipt through PipelineRun creation. The watcher emits `waitDuration` and `executeDuration` spans for completed PipelineRuns, using the PipelineRun's actual timestamps for accurate wall-clock timing.
+
+## Trace context propagation
+
+When Pipelines-as-Code creates a PipelineRun, it sets the `tekton.dev/pipelinerunSpanContext` annotation with a JSON-encoded OTel TextMapCarrier containing the W3C `traceparent`. PaC tracing works independently — you get PaC spans regardless of whether Tekton Pipelines has tracing enabled.
+
+If Tekton Pipelines is also configured with tracing pointing at the same collector, its reconciler spans appear as children of the PaC span, providing a single end-to-end trace from webhook receipt through task execution. See the [Tekton Pipelines tracing documentation](https://github.com/tektoncd/pipeline/blob/main/docs/developers/tracing.md) for Tekton's independent tracing setup.

pkg/kubeinteraction/labels.go

@@ -70,7 +70,7 @@ func AddLabelsAndAnnotations(ctx context.Context, event *info.Event, pipelineRun
 
 	// Add span context for distributed tracing if available
 	if len(carrier) > 0 {
-		if jsonBytes, err := json.Marshal(map[string]string(carrier)); err == nil {
+		if jsonBytes, err := json.Marshal(carrier); err == nil {
 			if existing := pipelineRun.GetAnnotations()[keys.SpanContextAnnotation]; existing != "" {
 				logging.FromContext(ctx).Warnf("overwriting pre-existing %s annotation on PipelineRun template; honoring initiating event trace context", keys.SpanContextAnnotation)
 			}

pkg/reconciler/emit_traces.go

@@ -34,8 +34,7 @@ func extractSpanContext(pr *tektonv1.PipelineRun) (context.Context, bool) {
 		return nil, false
 	}
 	carrier := propagation.MapCarrier(carrierMap)
-	prop := propagation.TraceContext{}
-	ctx := prop.Extract(context.Background(), carrier)
+	ctx := otel.GetTextMapPropagator().Extract(context.Background(), carrier)
 	sc := trace.SpanContextFromContext(ctx)
 	if !sc.IsValid() {
 		return nil, false
@@ -50,7 +49,7 @@ func emitTimingSpans(pr *tektonv1.PipelineRun) {
 		return
 	}
 
-	tracer := otel.GetTracerProvider().Tracer(tracing.TracerName)
+	tracer := otel.Tracer(tracing.TracerName)
 	commonAttrs := buildCommonAttributes(pr)
 
 	// Emit waitDuration: creationTimestamp -> status.startTime
@@ -64,7 +63,7 @@ func emitTimingSpans(pr *tektonv1.PipelineRun) {
 
 	// Emit executeDuration: status.startTime -> status.completionTime
 	if pr.Status.StartTime != nil && pr.Status.CompletionTime != nil {
-		execAttrs := append(commonAttrs, buildExecuteAttributes(pr)...)
+		execAttrs := append(append([]attribute.KeyValue{}, commonAttrs...), buildExecuteAttributes(pr)...)
 		_, execSpan := tracer.Start(parentCtx, "executeDuration",
 			trace.WithTimestamp(pr.Status.StartTime.Time),
 			trace.WithAttributes(execAttrs...),
@@ -91,13 +90,11 @@ func buildCommonAttributes(pr *tektonv1.PipelineRun) []attribute.KeyValue {
 // buildExecuteAttributes returns span attributes specific to execute_duration.
 func buildExecuteAttributes(pr *tektonv1.PipelineRun) []attribute.KeyValue {
 	cond := pr.Status.GetCondition(apis.ConditionSucceeded)
-	success := true
+	success := false
 	reason := ""
 	if cond != nil {
 		reason = cond.Reason
-		if cond.Status == corev1.ConditionFalse {
-			success = false
-		}
+		success = cond.Status == corev1.ConditionTrue
 	}
 	return []attribute.KeyValue{
 		tracing.DeliverySuccessKey.Bool(success),