Compact Span Metrics

Overview

Compact Span Metrics is an optimized metric type designed to improve the performance of the Services and Databases catalog pages, especially in large-scale environments. Traditional Span Metrics can carry very high cardinality, leading to slow load times and limited scalability. Compact Span Metrics addresses this by keeping only the most essential dimensions, reducing metric cardinality while delivering the core insights needed for monitoring and troubleshooting.

Note

Compact Span Metrics is enabled by default only for Span Metrics users.
This setup is additive: compact metrics are sent alongside the existing Span Metrics, not as a replacement. This is relevant for both the Services and Databases catalogs.
When you enable Compact Span Metrics, data in the main catalog pages will appear only from the moment you start sending it.

Key benefits

Uses essential labels only:
- Services catalog: service_name, status_code, k8s_cluster_name, span_kind, host.name
- Databases catalog: service_name, status_code, k8s_cluster_name, db_namespace, db_system, host.name
Optional histogram control: the le histogram can be disabled to further reduce load.
Reduction in cardinality: lowers metric permutations.
Low-latency performance: enables much faster load times in large environments.
Backward compatibility: compact metrics are sent in addition to existing Span Metrics, ensuring no breakage in drilldowns.

Enabling Compact Span Metrics

With Coralogix OTel integration

Using the Coralogix latest integration is strongly recommended, as it’s continuously updated and aligned with the latest OpenTelemetry releases. To benefit from Compact Span Metrics, make sure to upgrade your otel-integration to version v0.0.230 or higher.

The following metrics are enabled by default:

Services catalog:
- compact_calls_total
- compact_duration_ms_count
- compact_duration_ms_sum
- compact_duration_ms_bucket
Databases catalog:
- db_compact_calls_total
- db_compact_duration_ms_count
- db_compact_duration_ms_sum
- db_compact_duration_ms_bucket

Without Coralogix OTel integration

When compact database metrics are missing

Compact database metrics are not part of the check that enables the new APM, so an account that sends compact service metrics but not compact database metrics still gets the new APM for its services. In that case:

The Databases scope in the sidebar is unavailable. Hover over it to see why, with links to open the databases in legacy APM and to the setup documentation.
Selecting a database anywhere in the new APM (a map node, a table row, or an overview) opens its drilldown in legacy APM, carrying over your current time range.
The welcome dialog reports the service metrics as sending and the database metrics as not sending.

Disabling Compact Span Metrics

You can disable the Services catalog compact metrics (compact_*), the Databases catalog compact metrics (db_compact_*), or both.

With the Coralogix OTel integration

Update to the latest otel-integration: v0.0.230 or higher.
In your Helm chart configuration, set compactMetrics.enabled: false under spanMetrics (Services catalog) and/or dbMetrics (Databases catalog):

otel-integration:
  opentelemetry-agent:
    presets:
      spanMetrics:
        enabled: true
        # Services catalog compact metrics (compact_*)
        compactMetrics:
          enabled: false
          dropHistogram: true
        # Databases catalog compact metrics (db_compact_*)
        dbMetrics:
          enabled: true
          compactMetrics:
            enabled: false
            dropHistogram: true

Running your own collector

Remove the compact metrics you no longer need from your collector configuration, then restart the Collector:

Services catalog: the spanmetrics/compact connector and its traces/compact and metrics/compact pipelines.
Databases catalog: the spanmetrics/db_compact connector and its traces/db_compact and metrics/db_compact pipelines.

Also remove the matching forward/compact or forward/db_compact connector from the traces pipeline exporters.

Next steps

Already running Events2Metrics? See Migration from Events2Metrics to Span Metrics for the recommended switchover path.

For per-service visibility into APM volume and cardinality after compact metrics are enabled, use Service Governance in the Metrics Usage Analyzer.

Last updated on October 13, 2026

receivers: otlp: protocols: grpc: endpoint: 0.0.0.0:4317 http: endpoint: 0.0.0.0:4318 connectors: forward/compact: {} forward/db: {} forward/db_compact: {} spanmetrics: add_resource_attributes: true aggregation_cardinality_limit: 100000 dimensions: - name: http.method - name: cgx.transaction - name: cgx.transaction.root - name: status_code - name: db.namespace - name: db.operation.name - name: db.collection.name - name: db.system - name: graphql.operation.type - name: http.response.status_code - name: rpc.grpc.status_code - name: service.version exclude_dimensions: [collector.instance.id] histogram: explicit: buckets: [1ms, 4ms, 10ms, 20ms, 50ms, 100ms, 200ms, 500ms, 1s, 2s, 5s] unit: ms metrics_expiration: 5m metrics_flush_interval: 30s series_expiration: 5m spanmetrics/compact: add_resource_attributes: true aggregation_cardinality_limit: 100000 exclude_dimensions: [collector.instance.id, span.name] histogram: explicit: buckets: [1ms, 4ms, 10ms, 20ms, 50ms, 100ms, 200ms, 500ms, 1s, 2s, 5s] unit: ms metrics_expiration: 5m metrics_flush_interval: 30s namespace: compact series_expiration: 5m spanmetrics/db: add_resource_attributes: true aggregation_cardinality_limit: 100000 dimensions: - name: db.namespace - name: db.operation.name - name: db.collection.name - name: db.system - name: service.version exclude_dimensions: [collector.instance.id] histogram: explicit: buckets: [1ms, 4ms, 10ms, 20ms, 50ms, 100ms, 200ms, 500ms, 1s, 2s, 5s] unit: ms metrics_expiration: 5m metrics_flush_interval: 30s namespace: db series_expiration: 5m spanmetrics/db_compact: add_resource_attributes: true aggregation_cardinality_limit: 100000 dimensions: - name: db.namespace - name: db.system exclude_dimensions: [collector.instance.id, span.name, span.kind] histogram: explicit: buckets: [1ms, 4ms, 10ms, 20ms, 50ms, 100ms, 200ms, 500ms, 1s, 2s, 5s] unit: ms metrics_expiration: 5m metrics_flush_interval: 30s namespace: db_compact series_expiration: 5m processors: batch: send_batch_max_size: 2048 send_batch_size: 1024 timeout: 1s memory_limiter: check_interval: 5s limit_mib: 512 resourcedetection/env: detectors: [system, env] override: false timeout: 2s resource/metadata: attributes: - action: upsert key: cx.otel_integration.name value: coralogix-standalone coralogix: transactions: enabled: true groupbytrace/transactions: wait_duration: 30s redaction/spanname: allow_all_keys: true url_sanitizer: enabled: true transform/semconv: error_mode: ignore trace_statements: - context: span statements: - set(span.attributes["http.method"], span.attributes["http.request.method"]) where span.attributes["http.request.method"] != nil - set(span.attributes["http.response.status_code"], span.attributes["http.status_code"]) where span.attributes["http.response.status_code"] == nil and span.attributes["http.status_code"] != nil transform/spanmetrics: error_mode: silent metric_statements: - context: datapoint statements: - set(datapoint.attributes["status.code"], "STATUS_CODE_ERROR") where datapoint.attributes["status.code"] == nil and instrumentation_scope.name == "spanmetricsconnector" and datapoint.attributes["otel.status_code"] == "ERROR" - set(datapoint.attributes["status.code"], "STATUS_CODE_OK") where datapoint.attributes["status.code"] == nil and instrumentation_scope.name == "spanmetricsconnector" and datapoint.attributes["otel.status_code"] == "OK" - set(datapoint.attributes["status.code"], "STATUS_CODE_UNSET") where datapoint.attributes["status.code"] == nil and instrumentation_scope.name == "spanmetricsconnector" and (datapoint.attributes["otel.status_code"] == "UNSET" or datapoint.attributes["otel.status_code"] == nil) transform/compact: trace_statements: - context: resource statements: - keep_keys(resource.attributes, ["service.name", "k8s.cluster.name", "host.name", "deployment.environment.name"]) transform/db: error_mode: silent trace_statements: - context: span statements: - set(attributes["db.system"], attributes["db.system.name"]) where attributes["db.system.name"] != nil and attributes["db.system"] == nil transform/db_compact: trace_statements: - context: resource statements: - keep_keys(resource.attributes, ["service.name", "k8s.cluster.name", "host.name", "deployment.environment.name"]) - context: span statements: - set(attributes["db.system"], attributes["db.system.name"]) where attributes["db.system.name"] != nil and attributes["db.system"] == nil - keep_keys(span.attributes, ["db.namespace", "db.system"]) filter/db_spanmetrics: traces: span: - span.attributes["db.system"] == nil and span.attributes["db.system.name"] == nil filter/db_compact_spanmetrics: traces: span: - span.kind != SPAN_KIND_CLIENT or span.attributes["db.namespace"] == nil or (span.attributes["db.system"] == nil and span.attributes["db.system.name"] == nil) exporters: coralogix: domain: <YOUR-CORALOGIX-DOMAIN> private_key: ${env:CORALOGIX_PRIVATE_KEY} application_name: otel subsystem_name: apm application_name_attributes: [cx.application.name, service.namespace] subsystem_name_attributes: [cx.subsystem.name, service.name] timeout: 30s service: pipelines: traces: receivers: [otlp] processors: [memory_limiter, resourcedetection/env, resource/metadata, redaction/spanname, transform/semconv, groupbytrace/transactions, coralogix, batch] exporters: [spanmetrics, forward/db, forward/compact, forward/db_compact, coralogix] traces/compact: receivers: [forward/compact] processors: [transform/compact, batch] exporters: [spanmetrics/compact] traces/db: receivers: [forward/db] processors: [filter/db_spanmetrics, transform/db, batch] exporters: [spanmetrics/db] traces/db_compact: receivers: [forward/db_compact] processors: [filter/db_compact_spanmetrics, transform/db_compact, batch] exporters: [spanmetrics/db_compact] metrics: receivers: [spanmetrics, spanmetrics/db, otlp] processors: [memory_limiter, resourcedetection/env, resource/metadata, transform/spanmetrics, batch] exporters: [coralogix] metrics/compact: receivers: [spanmetrics/compact] processors: [memory_limiter, transform/spanmetrics, batch] exporters: [coralogix] metrics/db_compact: receivers: [spanmetrics/db_compact] processors: [memory_limiter, transform/spanmetrics, batch] exporters: [coralogix]

Overview​

Key benefits​

Enabling Compact Span Metrics​

With Coralogix OTel integration​

Without Coralogix OTel integration​

When compact database metrics are missing​

Disabling Compact Span Metrics​

Next steps​