# Span Metrics
#### Description
This connector automatically generates Request, Error, and Duration (R.E.D) metrics from incoming trace spans.
#### Use
Use this connector to:
* Monitor request rates, error rates, and latency across services without manual metric instrumentation
* Build R.E.D dashboards and alerts directly from existing trace data
* Add custom span attributes as metric dimensions for more granular analysis
* Correlate metrics back to traces using exemplars
#### Supported Types
| Input | Output |
| ------ | ------- |
| Traces | Metrics |
#### Generated Metrics
The connector produces the following metrics (prefixed by the namespace, default `traces.span.metrics`):
| Metric | Type | Description |
| ---------- | --------- | ------------------------------------------------------------------------- |
| `calls` | Sum | Count of spans. Error counts are derived via the `status.code` attribute. |
| `duration` | Histogram | Distribution of span durations |
| `events` | Sum | Count of span events (optional, disabled by default) |
Every metric includes these default attributes:
| Attribute | Description |
| -------------- | ------------------------------------------------------------ |
| `service.name` | The service that produced the span |
| `span.name` | The operation name |
| `span.kind` | The span kind (client, server, internal, producer, consumer) |
| `status.code` | The span status code (Ok, Error, Unset) |
#### Configuration
| Field | Description | Default |
| ----------------------- | --------------------------------------------------------------------------------------- | ------------ |
| Metric Namespace | Prefix for generated metric names. Leave empty for the default (`traces.span.metrics`). | *(empty)* |
| Aggregation Temporality | How metrics are aggregated over time: `Cumulative` or `Delta`. | `Cumulative` |
| Metrics Flush Interval | How often generated metrics are flushed. Examples: `15s`, `1m`, `60s`. | `60s` |
**Attributes**
Control which span and resource attributes appear as dimensions on the generated metrics.
| Field | Description | Default |
| -------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- |
| Additional Attributes | Span or resource attributes to include as metric dimensions on **all** generated metrics. Map attribute name to a default value (leave value empty if the attribute should be omitted when missing). | *(none)* |
| Exclude Default Attributes | Remove specific default attributes (`service.name`, `span.name`, `span.kind`, `status.code`) from metrics. | *(none)* |
| Calls Metric Attributes | Additional attributes for the **calls** metric only, on top of the common attributes above. | *(none)* |
**Duration Histogram**
Configure how span duration is measured and bucketed.
| Field | Description | Default |
| ----------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------- |
| Enable Duration Histogram | Generate a duration histogram metric. When disabled, only call count metrics are produced. | `true` |
| Histogram Type | `Explicit` uses fixed bucket boundaries. `Exponential` uses dynamic boundaries based on scale. | `Explicit` |
| Duration Unit | Unit for duration measurements: `ms` (milliseconds) or `s` (seconds). | `ms` |
| Bucket Boundaries | Custom histogram bucket boundaries. Leave empty for defaults: `2ms, 4ms, 6ms, 8ms, 10ms, 50ms, 100ms, 200ms, 400ms, 800ms, 1s, 1400ms, 2s, 5s, 10s, 15s`. | *(default buckets)* |
| Exponential Max Size | Maximum number of buckets per positive or negative range (exponential histograms only). | `160` |
| Duration Histogram Attributes | Additional attributes for the **duration histogram** metric only, on top of the common attributes above. | *(none)* |
#### Advanced Configuration
The following settings are available under the advanced configuration toggle.
**Exemplars**
Exemplars attach references from metric data points back to the original trace spans that produced them. This enables drill-down from a metric chart directly to the relevant trace.
| Field | Description | Default |
| ---------------------------- | --------------------------------------------------------------- | ------- |
| Enable Exemplars | Attach trace exemplars to histogram metrics. | `false` |
| Max Exemplars Per Data Point | Maximum number of exemplars to attach per histogram data point. | `5` |
**Events**
Generate a counter metric for span events. This is useful for tracking exception counts or custom application events.
| Field | Description | Default |
| -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- |
| Enable Events Metric | Generate a metric counting span events. | `false` |
| Event Attributes | Span event attributes to include as dimensions on the events metric. **At least one is required** when events are enabled. Map attribute name to a default value (leave value empty if the attribute should be omitted when missing). | *(none)* |
**Tuning**
These settings control performance and caching behavior. For most deployments the defaults are appropriate.
| Field | Description | Default |
| ------------------------------- | ------------------------------------------------------------------------------------------------------------------------ | ------- |
| Metrics Expiration | Time after which metrics stop being exported if no new spans arrive. `0` means never expire. | `0` |
| Resource Metrics Cache Size | Size of the internal cache holding metrics per resource. | `1000` |
| Metric Timestamp Cache Size | Cache size for tracking metric timestamps (used with delta temporality). | `1000` |
| Aggregation Cardinality Limit | Maximum unique dimension combinations. `0` means unlimited. | `0` |
| Include Instrumentation Scope | Only process spans from these instrumentation scope names. If empty, all scopes are included. | *(all)* |
| Resource Metrics Key Attributes | Resource attributes used to determine resource identity for metric grouping. If empty, all resource attributes are used. | *(all)* |
For more information on configuration options, see the [OpenTelemetry documentation](https://github.com/open-telemetry/opentelemetry-collector-contrib/blob/main/connector/spanmetricsconnector/README.md#configurations).
#### Example Configurations
**Basic R.E.D Metrics**
Generate request, error, and duration metrics with default settings. No additional configuration is needed — just add the connector between a traces source and a metrics destination.
* Aggregation Temporality: `Cumulative`
* Metrics Flush Interval: `60s`
* Enable Duration Histogram: `true`
**HTTP Latency with Custom Buckets**
Track HTTP request latency with custom histogram buckets and the HTTP method as a dimension.
* Additional Attributes: `http.request.method` (no default value)
* Enable Duration Histogram: `true`
* Histogram Type: `Explicit`
* Duration Unit: `ms`
* Bucket Boundaries: `5ms`, `10ms`, `25ms`, `50ms`, `100ms`, `250ms`, `500ms`, `1s`, `2s`, `5s`
**Error Tracking with Exemplars**
Enable exemplars to correlate error metrics back to the original traces.
* Additional Attributes: `http.response.status_code` (no default value)
* Enable Duration Histogram: `true`
* Enable Exemplars: `true` *(advanced)*
* Max Exemplars Per Data Point: `5` *(advanced)*
With exemplars enabled, clicking on a metric data point in a compatible backend (e.g. Grafana with Tempo) will link directly to the trace that produced it.
**Exception Counting with Events**
Count span events by exception type across services.
* Enable Events Metric: `true` *(advanced)*
* Event Attributes: `exception.type` (no default value) *(advanced)*
This produces a `traces.span.metrics.events` counter with `exception.type` as a dimension, letting you track exception rates by type.
#### Technical Notes
**Flush interval**: Metrics are emitted on a timer (default 60 seconds). After adding the connector, wait at least one flush interval before expecting metrics to appear.
**Single writer principle**: When multiple collectors generate the *same* cumulative time series, most backends will treat that as a single writer violation. Enable `collector.instance.id` on the generated metrics to ensure each collector writes uniquely identified series. This requires the feature gate `connector.spanmetrics.includeCollectorInstanceID`. It is enabled by default in BDOT.
**High cardinality warning**: The `span.name` attribute is included by default. Non-normalized span names (e.g. `GET /user/12345` instead of `GET /user/{id}`) can cause metric cardinality to explode. Use a Transform processor upstream to normalize span names, or set an `Aggregation Cardinality Limit` as a safety net.
#### Related Resources
* [OTel spanmetrics connector docs](https://github.com/open-telemetry/opentelemetry-collector-contrib/blob/main/connector/spanmetricsconnector/README.md)
---
# Agent Instructions: Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter:
```
GET https://docs.bindplane.com/integrations/connectors/span-metrics.md?ask=
```
The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.