Getting Started with Span Metrics

Overview

Span Metrics provides an automated way to convert trace data into metrics. It ensures complete APM metric coverage regardless of the sampling strategy you use. Whether you apply head sampling, tail sampling, or a combination of both, Span Metrics gives you full visibility without requiring ingestion of every raw span. This approach helps reduce cost by retaining only the spans that matter most.

Span Metrics uses the OpenTelemetry Span Metrics Connector to collect and process span-derived metrics in a consistent way.

The compact span metric can be configured alongside your existing Span Metrics, providing a low-cardinality variant of the standard metric. It is designed for heavy-scale environments with thousands of services and many dimensions, ensuring the Service and Database Catalog pages remain fast and responsive, even with large data volumes and long time-range queries.

Span Metrics concepts

Concept	Description
SpanMetrics connector	Derives RED metrics (Rate, Errors, Duration) from spans and exports them as count and histogram metrics. When placed before any trace-sampling processors in the collector pipeline, it ensures complete visibility even if traces are later sampled or dropped in the collector.
`aggregation_cardinality_limit`	A configuration option exposed via the Coralogix Helm chart for the Span Metrics connector. It caps the number of unique metric series produced by label combinations, preventing unbounded cardinality and routing any additional series into a dedicated overflow bucket.
`metricsExpiration`	Defines how long unused metric series remain in memory. After the expiration window ends, inactive series are removed to reduce resource usage. Find out more here.
`aggregation_temporality`	Controls whether Span Metrics export values as cumulative (totals since start) or delta (changes since last interval).
Exemplars	Adds trace IDs to metric points for metric-to-trace correlation, helping with debugging and investigation.
`resource_metrics_key_attributes`	Defines which resource attributes are used to group metric series together, ensuring consistent aggregation across services, namespaces, or environments.

Before you begin

Review the following requirements and recommendations before enabling Span Metrics.

Cardinality awareness

Span Metrics can generate many unique time series if span names or attributes include highly variable values such as user IDs, UUIDs, session IDs, or raw SQL statements. These values can create hundreds of thousands of unique metric combinations and affect performance. If your environment uses dynamic span names, normalize them before enabling Span Metrics. For guidance on reducing or normalizing high-cardinality data, see the Span Metrics Cardinality Limiting.

Multiple OpenTelemetry Collector agents

When using multiple OpenTelemetry (OTel) collector agents, each performs span metrics aggregation separately. Without a unique label value, Coralogix receives the metrics individually and cannot effectively aggregate them. For example, Kubernetes users who implement a collector on each node may experience metrics from the same service on different nodes overwriting each other. Adding k8s.pod.name as a label resolves this issue by providing a unique identifier, which differentiates the metrics and enables accurate querying and aggregation.

Next steps

Use our Quick Start guide to install Span Metrics.

Resources

This guide provides a comprehensive walkthrough of Span Metrics.

Here is what you will find:

Previous APM Onboarding

Next Quick Start