Skip to content

Commit d483a25

Browse files
infernus01infernus01
committed
Update observability docs and config for OpenTelemetry migration
Signed-off-by: Shubham Bhardwaj <shubbhar@redhat.com>
1 parent deb0ae9 commit d483a25

2 files changed

Lines changed: 212 additions & 10 deletions

File tree

‎docs/metrics.md‎

Lines changed: 82 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -4,17 +4,89 @@ linkTitle: "Triggers Metrics"
44
weight: 1200
55
---
66
-->
7-
# Tekton Triggers Controller Metrics
7+
# Tekton Triggers Metrics
88

9-
The following tekton triggers metrics are available at `controller-service` on port `9000`.
9+
## Controller Metrics
1010

11-
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).
11+
The following metrics are exported by the triggers controller on port `9000`.
1212

13-
| Name | Type | Description |
14-
| ---------- | ----------- | ----------- |
15-
| `controller_clusterinterceptor_count` | Gauge | Number of clusterinteceptor |
16-
| `controller_eventlistener_count` | Gauge | Number of eventlistener |
17-
| `controller_clustertriggerbinding_count` | Gauge | Number of clustertriggerbinding |
18-
| `controller_triggerbinding_count` | Gauge | Number of triggerbinding |
19-
| `controller_triggertemplate_count` | Gauge | Number of triggertemplate |
13+
| Name | Type | Labels/Tags | Description |
14+
|---|---|---|---|
15+
| `eventlistener_count` | Gauge | | Number of EventListeners |
16+
| `triggerbinding_count` | Gauge | | Number of TriggerBindings |
17+
| `triggertemplate_count` | Gauge | | Number of TriggerTemplates |
18+
| `clustertriggerbinding_count` | Gauge | | Number of ClusterTriggerBindings |
19+
| `clusterinterceptor_count` | Gauge | | Number of ClusterInterceptors |
2020

21+
## EventListener Sink Metrics
22+
23+
The following metrics are exported by each EventListener sink pod on port
24+
`9000`.
25+
26+
| Name | Type | Labels/Tags | Description |
27+
|---|---|---|---|
28+
| `event_received_count_total` | Counter | `status`=`succeeded`\|`failed` | Number of events received by the sink |
29+
| `triggered_resources_total` | Counter | `kind`=&lt;resource kind&gt; | Number of resources created by triggers |
30+
| `http_duration_seconds` | Histogram | | HTTP request duration in seconds |
31+
32+
> **Note:** Counter metrics include a `_total` suffix when exported via
33+
> Prometheus. This is an OpenTelemetry/Prometheus convention.
34+
35+
## Configuring Metrics
36+
37+
Metrics are configured via the `config-observability-triggers` ConfigMap
38+
in the `tekton-pipelines` namespace. By default, Prometheus export is
39+
enabled on port `9000`.
40+
41+
See [config-observability.yaml](../config/config-observability.yaml) for
42+
the full list of configuration options.
43+
44+
### Metrics protocol
45+
46+
The `metrics-protocol` key controls how metrics are exported:
47+
48+
| Value | Description |
49+
|---|---|
50+
| `prometheus` | Starts an HTTP server on port 9000 serving `/metrics` (default) |
51+
| `grpc` | Exports via OTLP gRPC to the configured `metrics-endpoint` |
52+
| `http/protobuf` | Exports via OTLP HTTP to the configured `metrics-endpoint` |
53+
| `none` | Disables metrics export |
54+
55+
### Tracing protocol
56+
57+
The `tracing-protocol` key controls distributed tracing:
58+
59+
| Value | Description |
60+
|---|---|
61+
| `none` | Disables tracing (default) |
62+
| `grpc` | Exports traces via OTLP gRPC to `tracing-endpoint` |
63+
| `http/protobuf` | Exports traces via OTLP HTTP to `tracing-endpoint` |
64+
| `stdout` | Prints traces to stdout (for debugging) |
65+
66+
### Example: Prometheus with OTLP tracing
67+
68+
```yaml
69+
apiVersion: v1
70+
kind: ConfigMap
71+
metadata:
72+
name: config-observability-triggers
73+
namespace: tekton-pipelines
74+
data:
75+
metrics-protocol: prometheus
76+
tracing-protocol: grpc
77+
tracing-endpoint: otel-collector.observability.svc.cluster.local:4317
78+
tracing-sampling-rate: "0.1"
79+
```
80+
81+
### Verifying metrics
82+
83+
```bash
84+
kubectl -n tekton-pipelines port-forward svc/tekton-triggers-controller 9000:9000
85+
curl -s http://localhost:9000/metrics | grep -E "eventlistener_count|clusterinterceptor_count"
86+
```
87+
88+
> **Note:** The previous OpenCensus-based configuration keys
89+
> (`metrics.backend-destination`, `metrics.stackdriver-project-id`, etc.)
90+
> are no longer supported. See the
91+
> [migration guide](migration-guide-opencensus-to-opentelemetry.md) for
92+
> details on upgrading from OpenCensus.

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

Lines changed: 130 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,130 @@
1+
<!--
2+
---
3+
linkTitle: "OpenTelemetry Migration"
4+
weight: 1201
5+
---
6+
-->
7+
# Migration Guide: OpenCensus to OpenTelemetry
8+
9+
This guide covers changes for cluster operators upgrading Tekton Triggers
10+
to a version that uses OpenTelemetry for metrics and tracing. The Triggers
11+
API (EventListener, TriggerTemplate, TriggerBinding, etc.) is unchanged.
12+
13+
This migration aligns Triggers with
14+
[Tekton Pipeline PR #9043](https://github.com/tektoncd/pipeline/pull/9043)
15+
and Knative's migration from `knative.dev/pkg/metrics` (OpenCensus) to
16+
`knative.dev/pkg/observability` (OpenTelemetry).
17+
18+
---
19+
20+
## What changed
21+
22+
| Area | Before | After |
23+
|---|---|---|
24+
| Metrics library | OpenCensus (`go.opencensus.io`) | OpenTelemetry (`go.opentelemetry.io/otel`) |
25+
| ConfigMap key for metrics | `metrics.backend-destination` | `metrics-protocol` |
26+
| ConfigMap key for tracing | Separate `config-tracing` / `K_TRACING_CONFIG` | Unified in `config-observability-triggers` (`tracing-protocol`) |
27+
| Stackdriver support | Built-in | Use OTLP with a GCP exporter |
28+
| Counter metric names | `event_received_count` | `event_received_count_total` |
29+
| Counter metric names | `triggered_resources` | `triggered_resources_total` |
30+
| Default metrics export | Prometheus on port 9000 | Prometheus on port 9000 (unchanged) |
31+
| Metrics port | 9000 | 9000 (unchanged) |
32+
33+
---
34+
35+
## Step 1: Observability ConfigMap
36+
37+
The `config-observability-triggers` ConfigMap ships with
38+
`metrics-protocol: prometheus` as active data, so Prometheus metrics
39+
remain enabled by default.
40+
41+
The `_example` block now documents the new OpenTelemetry configuration
42+
keys. The old OpenCensus keys (`metrics.backend-destination`,
43+
`metrics.stackdriver-project-id`, `metrics.allow-stackdriver-custom-metrics`)
44+
are no longer recognized.
45+
46+
**If you had no custom observability configuration**, no action is needed.
47+
48+
**If you had custom values**, translate them:
49+
50+
| Old key | New key |
51+
|---|---|
52+
| `metrics.backend-destination: prometheus` | `metrics-protocol: prometheus` |
53+
| `metrics.backend-destination: opencensus` | `metrics-protocol: grpc` + `metrics-endpoint: <host:port>` |
54+
| `metrics.backend-destination: none` | `metrics-protocol: none` |
55+
| `metrics.opencensus-address` | `metrics-endpoint` |
56+
| `metrics.reporting-period-seconds: 60` | `metrics-export-interval: 60s` |
57+
58+
After changing the ConfigMap, restart the controller:
59+
60+
```bash
61+
kubectl -n tekton-pipelines rollout restart deployment tekton-triggers-controller
62+
```
63+
64+
---
65+
66+
## Step 2: Update Prometheus queries
67+
68+
Counter metrics now have a `_total` suffix per Prometheus naming conventions:
69+
70+
```promql
71+
# Before
72+
event_received_count{status="succeeded"}
73+
triggered_resources{kind="PipelineRun"}
74+
75+
# After
76+
event_received_count_total{status="succeeded"}
77+
triggered_resources_total{kind="PipelineRun"}
78+
```
79+
80+
Gauge and histogram queries are unchanged:
81+
82+
```promql
83+
# These work as before
84+
eventlistener_count
85+
clusterinterceptor_count
86+
http_duration_seconds_bucket{le="5.0"}
87+
```
88+
89+
---
90+
91+
## Step 3: Account for new OTel scope labels
92+
93+
All metrics now include OpenTelemetry instrumentation scope labels:
94+
95+
- `otel_scope_name` (e.g. `github.com/tektoncd/triggers/pkg/sink`
96+
for sink metrics, `github.com/tektoncd/triggers/pkg/reconciler/metrics`
97+
for controller gauge metrics)
98+
- `otel_scope_schema_url` (emitted but empty)
99+
- `otel_scope_version` (emitted but empty)
100+
101+
Only `otel_scope_name` carries a meaningful value. These labels are
102+
informational and transparent to most PromQL queries. If you use strict
103+
label matching in recording rules or alerts, account for the new
104+
`otel_scope_name` label.
105+
106+
---
107+
108+
## Step 4: Verify
109+
110+
```bash
111+
kubectl -n tekton-pipelines port-forward svc/tekton-triggers-controller 9000:9000
112+
curl -s http://localhost:9000/metrics | grep -E "eventlistener_count|event_received_count_total"
113+
```
114+
115+
---
116+
117+
## No action required
118+
119+
- **Triggers API**: All CRDs are unchanged.
120+
- **Metrics port**: Still 9000, controlled by `METRICS_PROMETHEUS_PORT`.
121+
- **Metric semantics**: All metrics measure the same things with the same
122+
labels (`status`, `kind`).
123+
- **EventListener behavior**: Events are processed identically.
124+
125+
---
126+
127+
## Rollback
128+
129+
Redeploy the previous Triggers release. The old OpenCensus keys will work
130+
again. No data migration is needed.

0 commit comments

Comments
 (0)