Skip to main content

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.

​
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:

UI

Browse, install, and manage templates visually

CLI

Manage templates from your terminal

Terraform

Declare templates in your Terraform configurations
Pulumi Icon Streamline Icon: https://streamlinehq.com

Pulumi

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: 
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://<otel-collector-workload-name>.<gvc-name>.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: 
# 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.
ComponentDescription
receivers.otlpAccepts traces from your application over gRPC on port 4317
processors.resourceCopies service.name into a workload attribute for easier filtering
processors.transformNormalizes dynamic URL segments in span attributes
connectors.spanmetricsDerives duration histograms and request metrics from trace spans
exporters.otlpForwards traces to the Control Plane tracing backend
exporters.prometheusExposes span-derived metrics for scraping on port 8889
exporters.debugLogs spans to the workload’s stdout — useful during development

​
External References

OTel Collector Documentation

Official OpenTelemetry Collector documentation

OTel SDK Setup

Language-specific SDK guides for instrumenting your application

Spanmetrics Connector

Reference for the spanmetrics connector configuration

OTel Collector Template

View the source files, default values, and chart definition