feat(metrics): Migration from OpenCensus to OpenTelemetry

cmd/eventlistenersink/main.go

@@ -80,5 +80,9 @@ func main() {
 		CEClient:        ceClient,
 	}
 
+	// The event-listener sink runs its own HTTP server on port 8080, so
+	// disable the adapter framework's built-in health probe server which
+	// would otherwise conflict on the same port.
+	ctx = evadapter.WithHealthProbesDisabled(ctx)
 	evadapter.MainWithContext(ctx, EventListenerLogKey, adapter.NewEnvConfig, adapter.New(sinkArgs, sinkClients, recorder))
 }

config/config-observability.yaml

@@ -21,6 +21,7 @@ metadata:
     app.kubernetes.io/instance: default
     app.kubernetes.io/part-of: tekton-triggers
 data:
+  metrics-protocol: prometheus
   _example: |
     ################################
     #                              #
@@ -37,19 +38,41 @@ data:
     # this example block and unindented to be in the data block
     # to actually change the configuration.
 
-    # metrics.backend-destination field specifies the system metrics destination.
-    # It supports either prometheus (the default) or stackdriver.
-    # Note: Using stackdriver will incur additional charges
-    metrics.backend-destination: prometheus
-
-    # metrics.stackdriver-project-id field specifies the stackdriver project ID. This
-    # field is optional. When running on GCE, application default credentials will be
-    # used if this field is not provided.
-    metrics.stackdriver-project-id: "<your stackdriver project id>"
-
-    # metrics.allow-stackdriver-custom-metrics indicates whether it is allowed to send metrics to
-    # Stackdriver using "global" resource type and custom metric type if the
-    # metrics are not supported by "knative_revision" resource type. Setting this
-    # flag to "true" could cause extra Stackdriver charge.
-    # If metrics.backend-destination is not Stackdriver, this is ignored.
-    metrics.allow-stackdriver-custom-metrics: "false"
+    # OpenTelemetry Metrics Configuration
+    # Protocol for metrics export (prometheus, grpc, http/protobuf, none)
+    # Default if not specified: "none"
+    metrics-protocol: prometheus
+
+    # Metrics endpoint (for grpc/http protocols)
+    # Default: empty (uses default OTLP endpoint)
+    metrics-endpoint: ""
+
+    # Metrics export interval (e.g., "30s", "1m")
+    # Default: empty (uses default interval)
+    metrics-export-interval: ""
+
+    # OpenTelemetry Tracing Configuration
+    # Protocol for tracing export (grpc, http/protobuf, none, stdout)
+    # Default: none
+    tracing-protocol: none
+
+    # Tracing endpoint (for grpc/http protocols)
+    # Default: empty
+    tracing-endpoint: ""
+
+    # Tracing sampling rate (0.0 to 1.0)
+    # Default: 0.0 (no sampling)
+    tracing-sampling-rate: "0.0"
+
+    # Runtime Configuration
+    # Enable profiling (enabled, disabled)
+    # Default: disabled
+    runtime-profiling: disabled
+
+    # Runtime export interval (e.g., "15s")
+    # Default: 15s
+    runtime-export-interval: "15s"
+
+    # Note: Legacy OpenCensus configuration (metrics.backend-destination, etc.)
+    # has been removed. OpenCensus is no longer supported. Please use the
+    # OpenTelemetry configuration options above.

docs/metrics.md

@@ -4,17 +4,89 @@ linkTitle: "Triggers Metrics"
 weight: 1200
 ---
 -->
-# Tekton Triggers Controller Metrics
+# Tekton Triggers Metrics
 
-The following tekton triggers metrics are available at `controller-service` on port `9000`.
+## Controller Metrics
 
-We expose several kinds of exporters, including Prometheus, Google Stackdriver, and many others. You can set them up using [observability configuration](../config/config-observability.yaml).
+The following metrics are exported by the triggers controller on port `9000`.
 
-|  Name | Type | Description |
-| ---------- | ----------- | ----------- |
-| `controller_clusterinterceptor_count` | Gauge | Number of clusterinteceptor |
-| `controller_eventlistener_count` | Gauge | Number of eventlistener |
-| `controller_clustertriggerbinding_count` | Gauge | Number of clustertriggerbinding |
-| `controller_triggerbinding_count` | Gauge | Number of triggerbinding |
-| `controller_triggertemplate_count` | Gauge | Number of triggertemplate |
+| Name | Type | Labels/Tags | Description |
+|---|---|---|---|
+| `controller_eventlistener_count` | Gauge | | Number of EventListeners |
+| `controller_triggerbinding_count` | Gauge | | Number of TriggerBindings |
+| `controller_triggertemplate_count` | Gauge | | Number of TriggerTemplates |
+| `controller_clustertriggerbinding_count` | Gauge | | Number of ClusterTriggerBindings |
+| `controller_clusterinterceptor_count` | Gauge | | Number of ClusterInterceptors |
 
+## EventListener Sink Metrics
+
+The following metrics are exported by each EventListener sink pod on port
+`9000`.
+
+| Name | Type | Labels/Tags | Description |
+|---|---|---|---|
+| `eventlistener_event_received_total` | Counter | `status`=`succeeded`\|`failed` | Number of events received by the sink |
+| `eventlistener_triggered_resources_total` | Counter | `kind`=<resource kind> | Number of resources created by triggers |
+| `eventlistener_http_duration_seconds` | Histogram | | HTTP request duration in seconds |
+
+> **Note:** Counter metrics include a `_total` suffix when exported via
+> Prometheus. This is an OpenTelemetry/Prometheus convention.
+
+## Configuring Metrics
+
+Metrics are configured via the `config-observability-triggers` ConfigMap
+in the `tekton-pipelines` namespace. By default, Prometheus export is
+enabled on port `9000`.
+
+See [config-observability.yaml](../config/config-observability.yaml) for
+the full list of configuration options.
+
+### Metrics protocol
+
+The `metrics-protocol` key controls how metrics are exported:
+
+| Value | Description |
+|---|---|
+| `prometheus` | Starts an HTTP server on port 9000 serving `/metrics` (default) |
+| `grpc` | Exports via OTLP gRPC to the configured `metrics-endpoint` |
+| `http/protobuf` | Exports via OTLP HTTP to the configured `metrics-endpoint` |
+| `none` | Disables metrics export |
+
+### Tracing protocol
+
+The `tracing-protocol` key controls distributed tracing:
+
+| Value | Description |
+|---|---|
+| `none` | Disables tracing (default) |
+| `grpc` | Exports traces via OTLP gRPC to `tracing-endpoint` |
+| `http/protobuf` | Exports traces via OTLP HTTP to `tracing-endpoint` |
+| `stdout` | Prints traces to stdout (for debugging) |
+
+### Example: Prometheus with OTLP tracing
+
+```yaml
+apiVersion: v1
+kind: ConfigMap
+metadata:
+  name: config-observability-triggers
+  namespace: tekton-pipelines
+data:
+  metrics-protocol: prometheus
+  tracing-protocol: grpc
+  tracing-endpoint: otel-collector.observability.svc.cluster.local:4317
+  tracing-sampling-rate: "0.1"
+```
+
+### Verifying metrics
+
+```bash
+kubectl -n tekton-pipelines port-forward svc/tekton-triggers-controller 9000:9000
+curl -s http://localhost:9000/metrics | grep -E "controller_eventlistener_count|controller_clusterinterceptor_count"
+```
+
+> **Note:** The previous OpenCensus-based configuration keys
+> (`metrics.backend-destination`, `metrics.stackdriver-project-id`, etc.)
+> are no longer supported. See the
+> [migration guide](migration-guide-opencensus-to-opentelemetry.md) for
+> details on upgrading from OpenCensus.

docs/migration-guide-opencensus-to-opentelemetry.md

@@ -0,0 +1,132 @@
+<!--
+---
+linkTitle: "OpenTelemetry Migration"
+weight: 1201
+---
+-->
+# Migration Guide: OpenCensus to OpenTelemetry
+
+This guide covers changes for cluster operators upgrading Tekton Triggers
+to a version that uses OpenTelemetry for metrics and tracing. The Triggers
+API (EventListener, TriggerTemplate, TriggerBinding, etc.) is unchanged.
+
+This migration aligns Triggers with
+[Tekton Pipeline PR #9043](https://github.com/tektoncd/pipeline/pull/9043)
+and Knative's migration from `knative.dev/pkg/metrics` (OpenCensus) to
+`knative.dev/pkg/observability` (OpenTelemetry).
+
+---
+
+## What changed
+
+| Area | Before | After |
+|---|---|---|
+| Metrics library | OpenCensus (`go.opencensus.io`) | OpenTelemetry (`go.opentelemetry.io/otel`) |
+| ConfigMap key for metrics | `metrics.backend-destination` | `metrics-protocol` |
+| ConfigMap key for tracing | Separate `config-tracing` / `K_TRACING_CONFIG` | Unified in `config-observability-triggers` (`tracing-protocol`) |
+| Stackdriver support | Built-in | Use OTLP with a GCP exporter |
+| Sink counter names | `eventlistener_event_received_count` | `eventlistener_event_received_total` |
+| Sink counter names | `eventlistener_triggered_resources` | `eventlistener_triggered_resources_total` |
+| All other metric names | unchanged | unchanged |
+| Default metrics export | Prometheus on port 9000 | Prometheus on port 9000 (unchanged) |
+| Metrics port | 9000 | 9000 (unchanged) |
+
+---
+
+## Step 1: Observability ConfigMap
+
+The `config-observability-triggers` ConfigMap ships with
+`metrics-protocol: prometheus` as active data, so Prometheus metrics
+remain enabled by default.
+
+The `_example` block now documents the new OpenTelemetry configuration
+keys. The old OpenCensus keys (`metrics.backend-destination`,
+`metrics.stackdriver-project-id`, `metrics.allow-stackdriver-custom-metrics`)
+are no longer recognized.
+
+**If you had no custom observability configuration**, no action is needed.
+
+**If you had custom values**, translate them:
+
+| Old key | New key |
+|---|---|
+| `metrics.backend-destination: prometheus` | `metrics-protocol: prometheus` |
+| `metrics.backend-destination: opencensus` | `metrics-protocol: grpc` + `metrics-endpoint: <host:port>` |
+| `metrics.backend-destination: none` | `metrics-protocol: none` |
+| `metrics.opencensus-address` | `metrics-endpoint` |
+| `metrics.reporting-period-seconds: 60` | `metrics-export-interval: 60s` |
+
+After changing the ConfigMap, restart the controller:
+
+```bash
+kubectl -n tekton-pipelines rollout restart deployment tekton-triggers-controller
+```
+
+---
+
+## Step 2: Update Prometheus queries
+
+Only the two sink counter metrics were renamed. Update any queries or alerts
+that reference them:
+
+```promql
+# Before
+eventlistener_event_received_count{status="succeeded"}
+eventlistener_triggered_resources{kind="PipelineRun"}
+
+# After
+eventlistener_event_received_total{status="succeeded"}
+eventlistener_triggered_resources_total{kind="PipelineRun"}
+```
+
+All other metric names are unchanged:
+
+```promql
+# These work as before
+controller_eventlistener_count
+controller_clusterinterceptor_count
+eventlistener_http_duration_seconds_bucket{le="1.0"}
+```
+
+---
+
+## Step 3: Account for new OTel scope labels
+
+All metrics now include OpenTelemetry instrumentation scope labels:
+
+- `otel_scope_name` (e.g. `github.com/tektoncd/triggers/pkg/sink`
+  for sink metrics, `github.com/tektoncd/triggers/pkg/reconciler/metrics`
+  for controller gauge metrics)
+- `otel_scope_schema_url` (emitted but empty)
+- `otel_scope_version` (emitted but empty)
+
+Only `otel_scope_name` carries a meaningful value. These labels are
+informational and transparent to most PromQL queries. If you use strict
+label matching in recording rules or alerts, account for the new
+`otel_scope_name` label.
+
+---
+
+## Step 4: Verify
+
+```bash
+kubectl -n tekton-pipelines port-forward svc/tekton-triggers-controller 9000:9000
+curl -s http://localhost:9000/metrics | grep -E "controller_eventlistener_count|eventlistener_event_received_total"
+```
+
+---
+
+## No action required
+
+- **Triggers API**: All CRDs are unchanged.
+- **Metrics port**: Still 9000, controlled by `METRICS_PROMETHEUS_PORT`.
+- **Metric semantics**: All metrics measure the same things with the same
+  labels (`status`, `kind`).
+- **EventListener behavior**: Events are processed identically.
+
+---
+
+## Rollback
+
+Redeploy the previous Triggers release. The old OpenCensus keys will work
+again. No data migration is needed.