> ## Documentation Index
> Fetch the complete documentation index at: https://notes.kodekloud.com/llms.txt
> Use this file to discover all available pages before exploring further.
# OTel Col Connectors
> Explains OpenTelemetry Collector connectors, their placement, use cases, and configuration examples for deriving, routing, aggregating, and forwarding telemetry without changing application code
Connectors in the OpenTelemetry Collector enable cross-pipeline telemetry flows and lightweight transformations without changing application SDKs. This article explains what connectors are, where they sit in Collector pipelines, why they’re useful, and how to configure common connectors: count, spanmetrics, servicegraph, routing, forward, sum, and exceptions. Each example uses YAML for the Collector configuration and includes typical use cases and wiring patterns.
What is a connector?
* A connector acts as an exporter on a source pipeline and as a receiver on a target pipeline.
* This lets the Collector derive new telemetry (for example, metrics from traces) or route/fan out data without changing application or SDK code.
* Connectors are useful for SRE metrics (RED/SLIs), topology graphs, routing, aggregation, and error extraction.
Connectors bridge pipelines by appearing as an exporter on the source pipeline and as a receiver on the target pipeline. This allows the Collector to derive new telemetry (for example, metrics from spans) without changing application or SDK code.
Connector placement and flow
* A connector receives telemetry already processed by a pipeline, optionally performs computation (derive metrics, count, sum, build graphs), and emits data into another pipeline for further processing/export.
* Typical flow: receiver → processors → connector (acts as exporter) → metrics/other pipeline (connector acts as receiver) → exporters.
Common use cases
* Fan-out / reuse telemetry across multiple pipelines.
* Derive metrics from traces (RED metrics, SLIs, latency histograms).
* Build service dependency graphs and detect unexpected edges.
* Conditionally route telemetry based on attributes.
* Aggregate counts or sums into time-series for KPIs.
Common connectors
* spanmetrics — derive latency, error, and rate metrics from spans.
* servicegraph — build service dependency/topology metrics.
* routing — OTTL rules to route telemetry to pipelines.
* count — convert span events/logs into simple counts.
* sum — aggregate numeric attributes into time-series.
* forward — merge/split pipelines without transforming telemetry.
* exceptions — extract exception data for logging/alerting.
Connector comparison (quick reference)
| Connector | Primary purpose | Typical source signal | Example outcome |
| ------------ | ----------------------------------------: | ------------------------------ | ----------------------------------- |
| spanmetrics | Derive RED metrics, histograms, exemplars | Traces | Latency histograms, error rates |
| servicegraph | Build service dependency graph | Traces | Service-to-service edge metrics |
| routing | Route/fan-out based on OTTL rules | Any (resource/span/log/metric) | Environment-based pipelines |
| count | Count matched events | Spans / Logs | Time-series pulse metrics |
| sum | Aggregate numeric attributes | Spans | KPI time-series (order totals) |
| forward | Merge/split pipelines | Any | Combined or branched pipelines |
| exceptions | Extract exception data | Traces (exceptions) | Correlated logs with trace/span IDs |
***
## Count connector (example)
The Count connector converts span events or logs into simple time-series counts based on matching conditions. It operates as an exporter on the traces/logs pipeline and as a receiver on the metrics pipeline.
Example: count span events named "prodevent" coming from environment "prod" and emit metrics to the metrics pipeline, which exports to `debug`:
```yaml theme={null}
receivers:
otlp:
protocols:
grpc: {}
http: {}
exporters:
debug: {}
connectors:
count:
spanevents:
my.prod.event.count:
description: "The number of span events from prod"
conditions:
- 'attributes["env"] == "prod"'
- 'name == "prodevent"'
service:
pipelines:
traces:
receivers: [otlp]
exporters: [count]
metrics:
receivers: [count]
exporters: [debug]
```
How it works:
* Traces arrive via OTLP → processed → exported to `count`.
* The connector checks each span event against the `conditions`.
* Matches generate a metric `my.prod.event.count` emitted into the metrics pipeline and exported by `debug`.
***
## SpanMetrics connector
SpanMetrics derives SRE-style metrics (rate, errors, latency histograms) and exemplars from spans. It is commonly used to produce RED metrics and latency histograms for Prometheus.
Example: receive traces via OTLP, apply spanmetrics with explicit histogram buckets, dimensions, and exemplars, and export to Prometheus:
```yaml theme={null}
receivers:
otlp:
protocols:
grpc: {}
http: {}
exporters:
prometheus:
endpoint: 0.0.0.0:8889
connectors:
spanmetrics:
histogram:
explicit:
buckets: [2ms, 8ms, 50ms, 100ms, 200ms, 500ms, 1s, 5s, 10s]
dimensions:
- name: http.method
- name: http.status_code
exemplars:
enabled: true
service:
pipelines:
traces:
receivers: [otlp]
exporters: [spanmetrics, otlp]
metrics:
receivers: [spanmetrics]
exporters: [prometheus]
```
Use cases:
* SLIs and RED metrics (requests, error rates, durations).
* Latency histograms with exemplars for trace-level correlation.
* Error trend analysis by dimensions (status code, method).
***
## ServiceGraph connector
ServiceGraph computes a service dependency graph from trace spans, identifying client→service and service→service edges and generating related metrics to highlight hotspots or unexpected dependencies.
Configuration example: route traces through `servicegraph` and expose dependency metrics to Prometheus:
```yaml theme={null}
receivers:
otlp:
protocols:
grpc: {}
http: {}
exporters:
prometheus:
endpoint: 0.0.0.0:8889
connectors:
servicegraph: {}
service:
pipelines:
traces:
receivers: [otlp]
exporters: [servicegraph]
metrics:
receivers: [servicegraph]
exporters: [prometheus]
```
What it produces:
* Metrics showing edges and counts between services.
* Can highlight hotspots and unexpected edges for dependency analysis.
***
## Routing connector (OTTL-based routing)
The Routing connector evaluates OTTL (OpenTelemetry Transformation Language) expressions to dispatch telemetry to different pipelines. Use cases include environment isolation, tenant routing, error pipelines, and fan-out.
Key options:
* `default_pipelines` — where to send unmatched items.
* `match_once` — stop after first match (reduce duplication).
* `error_mode` — how to handle OTTL evaluation errors.
Example: route traces to `traces/prod` if resource has `env=prod`, route error spans (status >= 400) to `traces/errors`, and use a default pipeline for others:
```yaml theme={null}
connectors:
routing:
default_pipelines: [traces/default]
error_mode: ignore
match_once: true
table:
- context: resource
statement: 'route() where resource.attributes["env"] == "prod"'
pipelines: [traces/prod]
- context: span
statement: 'route() where attributes["http.status_code"] >= 400'
pipelines: [traces/errors]
service:
pipelines:
traces/in:
receivers: [otlp]
exporters: [routing]
traces/prod:
receivers: [routing]
exporters: [otlp/prod]
traces/errors:
receivers: [routing]
exporters: [otlp/errors]
traces/default:
receivers: [routing]
exporters: [otlp/default]
```
Example: routing logs from a single `filelog` receiver that contains multiple environments:
```yaml theme={null}
receivers:
filelog:
include: ["/var/log/app/*.log"]
exporters:
otlp/prod:
endpoint: prod-obsv:4317
otlp/dev:
endpoint: dev-obsv:4317
connectors:
routing/env:
default_pipelines: [logs/default]
table:
- statement: 'attributes["deployment.environment"] == "production"'
pipelines: [logs/prod]
- statement: 'attributes["deployment.environment"] == "staging"'
pipelines: [logs/dev]
service:
pipelines:
logs:
receivers: [filelog]
exporters: [routing/env]
logs/prod:
receivers: [routing/env]
exporters: [otlp/prod]
logs/dev:
receivers: [routing/env]
exporters: [otlp/dev]
logs/default:
receivers: [routing/env]
exporters: [otlp/dev] # fallback exporter example
```
Routing tips:
* Use `match_once` to avoid duplicates when you only want one destination.
* Use `default_pipelines` to ensure unmatched telemetry still gets processed.
* Test rules with a small dataset to avoid misrouting production telemetry.
***
## Forward connector
The Forward connector is a lightweight bridge that forwards telemetry between pipelines without transformation. It’s useful for merging sources, splitting for multiple downstream destinations, or creating parallel processing branches.
Example: merge logs from two receivers into a single merged logs pipeline, and branch traces into sampled vs all:
```yaml theme={null}
connectors:
forward: {}
service:
pipelines:
logs/blue:
receivers: [foo/blue]
processors: [attributes/blue]
exporters: [forward]
logs/green:
receivers: [foo/green]
processors: [attributes/green]
exporters: [forward]
logs/merged:
receivers: [forward]
processors: [batch]
exporters: [otlp]
traces:
receivers: [otlp]
processors: [resourcedetection]
exporters: [forward]
traces/sampled:
receivers: [forward]
processors: [tail_sampling]
exporters: [otlp/hot]
traces/all:
receivers: [forward]
exporters: [otlp/cold]
```
When to use forward:
* When you need to combine multiple inputs into one pipeline.
* When you need to create parallel downstream processing (fan-out).
***
## Sum connector
The Sum connector aggregates numeric attributes from spans into time-series sums, optionally grouping by attributes (labels). Useful for business KPIs like revenue, order totals, or counters derived from attributes.
Example: sum order totals and discounts from span attributes, grouped by `promo.code`:
```yaml theme={null}
connectors:
sum/totals:
spans:
purchase.order.total:
source_attribute: order.total
conditions:
- 'attributes["order.total"] != null'
attributes:
- key: promo.code
default_value: none
sum/discounts:
spans:
purchase.discount.total:
source_attribute: discount.total
conditions:
- 'attributes["discount.total"] != null'
attributes:
- key: promo.code
default_value: none
```
Result:
* Time-series `purchase.order.total` and `purchase.discount.total` containing sums of numeric attributes.
* Labels from `promo.code` let you split KPIs by campaign or promotion.
***
## Exceptions connector
The Exceptions connector extracts exception information found in spans and converts that data into logs or log-like telemetry including trace/span IDs for correlation. This is valuable for building error-focused pipelines and alerting.
Example: send traces through `exceptions` to produce logs consumed by a logs pipeline:
```yaml theme={null}
connectors:
exceptions: {}
service:
pipelines:
traces:
receivers: [otlp]
processors: [batch]
exporters: [exceptions, otlp]
logs:
receivers: [exceptions]
processors: [batch]
exporters: [otlp]
```
What to expect:
* The connector emits structured logs for exceptions that include trace and span IDs.
* Use these logs for alerting, storage in a log backend, or further enrichment.
***
Wrap-up
Connectors let you transform, route, and enrich telemetry inside the Collector without touching application code. They help you:
* Produce SRE metrics and SLIs from traces (spanmetrics, count, sum).
* Build dependency/topology metrics (servicegraph).
* Route and isolate telemetry (routing, forward).
* Extract errors and exceptions for dedicated pipelines (exceptions).
Start small, validate outputs in a staging environment, and monitor for duplicate telemetry or overload when enabling multiple connectors that might fan out signals.
Be careful with fan-out and overlapping rules. Multiple connectors or routing rules can cause duplicated metrics/logs if match conditions overlap. Test configurations and use `match_once` when appropriate.
Links and references
* OpenTelemetry Collector: [https://opentelemetry.io/docs/collector/](https://opentelemetry.io/docs/collector/)
* OTTL (OpenTelemetry Transformation Language): [https://opentelemetry.io/docs/collector/transformations/](https://opentelemetry.io/docs/collector/transformations/) (refer to your Collector distribution docs for exact syntax)
* Collector Connectors (see your Collector distribution / contrib docs for supported connector names and options)