> ## Documentation Index
> Fetch the complete documentation index at: https://docs.controlplane.com/llms.txt
> Use this file to discover all available pages before exploring further.
# OpenTelemetry Collector
## Overview
OpenTelemetry Collector is an observability service that receives, processes, and exports metrics, logs, and traces to the Control Plane tracing backend. This template deploys an OTel Collector workload with pre-configured receiver and processor configuration.
### What Gets Created
* **Standard Workload** — An OTel Collector workload that supports both a simple and an advanced mode allowing you to run a minimal setup for quick deployment or a fully customized configuration.
* **Secret** — An opaque secret for configuring the collector.
* **Identity & Policy** — An identity and policy bound to the OTel Collector workload with `reveal` access to the secret.
This template does not create a GVC. You will need to deploy it to an existing GVC and enable tracing at the GVC level after installing, specifying the target workload and port. This will trigger a restart of all workloads in the GVC.
## Installation
To install, follow the instructions for your preferred method:
Browse, install, and manage templates visually
Manage templates from your terminal
}>
Declare templates in your Terraform configurations
Pulumi Icon Streamline Icon: https://streamlinehq.com
}
>
Declare templates in your Pulumi programs
## Configuration
Step 1 is completed while deploying the template. After deploying the template, complete the following steps to finish configuration:
**1. Normalize URL patterns (recommended)**
If your application has dynamic URL segments, use the `transform` processor to normalize them into fixed patterns. This keeps span cardinality manageable and makes your traces queryable. In either Simple or Advanced config, replace each occurrence of `PLACEHOLDER` with each path segment you want to collapse:
```yaml theme={null}
transform:
trace_statements:
- context: span
statements:
# Static path
- replace_pattern(span.attributes["http.url"], "^.*(/user/profile).*$", "/user/profile")
# Wildcard path
- replace_pattern(span.attributes["http.url"], "^.*(/user/settings/.*).*$", "/user/settings/.*")
```
Add one statement per pattern you want to normalize.
**2. Install the OpenTelemetry SDK in your application**
Your application must emit traces using the OpenTelemetry SDK. Install the SDK and configure it to export via OTLP/gRPC to:
```
http://..cpln.local:4317
```
**3. Enable tracing at the GVC level**
Navigate to the GVC where the OpenTelemetry Collector is installed and enable tracing. Set the target workload on port `4317`. This triggers a restart of all workloads in the GVC so they begin emitting traces to the collector.
**4. Query span metrics in Grafana**
Span metrics are exposed via Prometheus on port `8889` of the collector workload which is configured and exposed by the workload.
Use the `spanmetrics` connector to build dashboards and alerts. The metric name suffix automatically changes based on the unit defined in your configuration to ensure data consistency.
```
traces_span_metrics_duration_milliseconds_bucket{http_url="/your-endpoint"}
```
If you changed the unit to `s` in the histogram, the metric name changes to:
```
traces_span_metrics_duration_seconds_bucket{http_url="/your-endpoint"}
```
The default `values.yaml` for this template:
```yaml theme={null}
# IMPORTANT:
# After installing the collector, you must enable tracing at the GVC level which will trigger a restart on all workloads.
otelCollector:
image: otel/opentelemetry-collector-contrib:0.148.0
mode: advanced # controls which config is used:
# - simple: minimal setup for quick deployment.
# - advanced: fully customizable configuration.
resources:
cpu: 200m
memory: 256Mi
# Simple Mode
simple:
processors:
transform:
traceStatements: # Simplifies spans by replacing dynamic data with a fixed value. Substitute PLACEHOLDER with the URL segment you want to normalize, e.g. 'user/profile'
- replace_pattern(span.attributes["http.url"], "^.*(PLACEHOLDER).*$", "/PLACEHOLDER")
spanmetrics:
histogram: # Histogram bucket boundaries in ms for span duration distribution — tune to match your SLO thresholds
buckets: [1, 5, 10, 25, 50, 100, 250, 500, 1000, 2500, 5000]
unit: ms # Bucket values are interpreted in milliseconds (choose: ms or s)
# Advanced Mode
advanced:
config: |
extensions:
health_check:
pprof:
endpoint: 0.0.0.0:8180
receivers:
otlp:
protocols:
grpc:
endpoint: 0.0.0.0:4317
processors:
batch:
resource:
attributes:
- key: workload
from_attribute: service.name
action: insert
transform:
trace_statements:
- context: span
statements:
- replace_pattern(span.attributes["http.url"], "^.*(PLACEHOLDER).*$", "/PLACEHOLDER")
connectors:
spanmetrics:
dimensions:
- name: http.url
- name: http.method
- name: http.status_code
histogram:
explicit:
buckets: [1, 5, 10, 25, 50, 100, 250, 500, 1000, 2500, 5000]
unit: ms
exporters:
debug:
verbosity: detailed
otlp:
endpoint: http://tracing.controlplane:80
tls:
insecure: true
prometheus:
endpoint: 0.0.0.0:8889
service:
pipelines:
traces:
receivers: [otlp]
processors: [resource, transform, batch]
exporters: [otlp, debug, spanmetrics]
metrics:
receivers: [spanmetrics]
processors: [batch]
exporters: [prometheus]
extensions: [pprof, health_check]
telemetry:
logs:
level: INFO
```
### Mode
* `otelCollector.mode` — Set to `simple` for a minimal setup for quick deployment, or `advanced` to provide a fully customized configuration. In `advanced` mode, the entire `otelCollector.advanced.config` is passed directly to the collector.
### Simple Mode
* `simple.processors.transform.traceStatements` — A list of `replace_pattern` statements that normalize dynamic URL segments in `http.url` span attributes. Replace `PLACEHOLDER` with the path segment you want to collapse, e.g. `user/profile`.
* `simple.spanmetrics.histogram.buckets` — Histogram bucket boundaries in milliseconds for span duration distribution. Tune these to align with your SLO thresholds.
* `simple.spanmetrics.histogram.unit` — Unit for histogram bucket values. Choose `ms` (milliseconds) or `s` (seconds).
### Advanced Mode
The `advanced.config` block accepts a full [OpenTelemetry Collector configuration](https://opentelemetry.io/docs/collector/configuration/).
| Component | Description |
| ------------------------ | ---------------------------------------------------------------------- |
| `receivers.otlp` | Accepts traces from your application over gRPC on port `4317` |
| `processors.resource` | Copies `service.name` into a `workload` attribute for easier filtering |
| `processors.transform` | Normalizes dynamic URL segments in span attributes |
| `connectors.spanmetrics` | Derives duration histograms and request metrics from trace spans |
| `exporters.otlp` | Forwards traces to the Control Plane tracing backend |
| `exporters.prometheus` | Exposes span-derived metrics for scraping on port `8889` |
| `exporters.debug` | Logs spans to the workload's stdout — useful during development |
## External References
Official OpenTelemetry Collector documentation
Language-specific SDK guides for instrumenting your application
Reference for the spanmetrics connector configuration
View the source files, default values, and chart definition