Migration from Event2Metrics to Span Metrics

This guide explains how to transition from Events2Metrics (E2M) to Span Metrics. Span Metrics offers complete APM metric coverage, improved performance, lower cardinality risk, and tighter integration with OpenTelemetry—all without relying on custom E2M rules.

Migrating does not require changes to your application code. Both pipelines can run in parallel during the migration period, allowing you to validate data, update dashboards, and adjust SLO or Apdex calculations before fully switching over. This document walks you through recommended migration steps, configuration updates, validation procedures, and rollback options to ensure a smooth and controlled transition.

Migration considerations

Review the following points if you are transitioning from Events2Metrics (E2M) to Span Metrics.

Transitioning from Events2Metrics

If you currently use Events2Metrics, you can run Span Metrics and E2M at the same time. This allows you to compare both pipelines and keep E2M as a fallback.

Running both pipelines increases cost because each pipeline generates its own metrics. You can switch to using only Span Metrics at any time.

Data visibility in the UI

You cannot view Span Metrics and E2M data at the same time in the APM UI.

If both data types are available, use the API commands in this documentation to switch the UI source between E2M and Span Metrics.

After switching from Event2Metrics to Span Metrics, both metrics will be collected (with data ingestion charges applied accordingly), but the UI will display data based on Span Metrics. Historical Events2Metrics metric data can still be accessed via Custom Dashboards and Grafana, subject to its retention period.

Choosing metric dimensions

Span Metrics supports additional dimensions from the OpenTelemetry Collector. Every dimension increases the number of metric combinations. To avoid performance issues, include only the dimensions that you need and keep the total number of label permutations below the fair usage limit.

Buckets configuration

Coralogix Event2Metric (E2M)–based APM uses a fixed, default set of latency buckets. When you migrate to Span Metrics, bucket definition moves to the collector configuration, giving you full control over bucket boundaries. Because of this change, any feature or query that relied on the old default buckets is not migrated automatically when switching from E2M to Span Metrics.

For example:

• le-based queries in alerts and custom dashboards
• Legacy APM SLOs (not the SLO Center SLOs)
• Legacy Apdex calculations based on E2M buckets

During the Span Metrics setup, define the buckets that represent your latency thresholds. Then recreate the relevant queries, SLOs, and Apdex configurations everywhere the E2M-based metrics and buckets were previously used.

Post-setup actions

Switch UI data source

This section outlines how to configure your APM settings in Coralogix to switch between using Events2Metrics and Span Metrics as the data source for the Service Catalog and Database Catalog.

Switching from Event2Metrics to Span Metrics

Switch from Events2Metrics (E2M) to Span Metrics via the API using the following command. Ensure you use the correct gRPC endpoint (<env url>):

 grpcurl -H "Authorization: <cx_api_key>" -d @ ng-api-grpc.<coralogix_url>:443 com.coralogixapis.service_catalog.v1.ApmSettingsService/ReplaceApmSettings <<EOF
{
    "apmSettings": {
        "catalogSettings": [
            {
                "source": "APM_SOURCE_SPAN_METRICS",
                "catalog": "SERVICE_CATALOG"
            },
            {
                "source": "APM_SOURCE_SPAN_METRICS",
                "catalog": "DATABASE_CATALOG"
            }
        ]
    }
}
EOF

Reverting to Events2Metrics collection

If needed, you can switch back to E2M, as detailed below:

grpcurl -H "Authorization: <cx_api_key>" -d @ ng-api-grpc.<coralogix_url>:443 com.coralogixapis.service_catalog.v1.ApmSettingsService/ReplaceApmSettings <<EOF
{
    "apmSettings": {
        "catalogSettings": [
            {
                "source": "APM_SOURCE_E2M",
                "catalog": "SERVICE_CATALOG"
            },
            {
                "source": "APM_SOURCE_E2M",
                "catalog": "DATABASE_CATALOG"
            }
        ]
    }
}
EO

Disabling Events2Metrics

To stop collecting data from Events2Metrics pipeline and rely solely on Span Metrics (or vice versa), run the following command. This command also specifies the date when you want Events2Metrics to stop metrics generation.

grpcurl -H "Authorization: <cx_api_key>" -d @ ng-api-grpc.<coralogix_url>:443 com.coralogixapis.service_catalog.v1.ApmSettingsService/ReplaceApmSettings <<EOF
{
    "apmSettings": {
        "catalogSettings": [
            {
                "source": "APM_SOURCE_SPAN_METRICS",
                "catalog": "DATABASE_CATALOG",
                "migrationPeriodEndDate": "2025-03-05T13:40:00Z"
            },
            {
                "source": "APM_SOURCE_SPAN_METRICS",
                "catalog": "SERVICE_CATALOG",
                "migrationPeriodEndDate": "2025-03-05T13:40:00Z"
            }
        ]
    }
}
EOF

• Use ISO 8601 format for migrationPeriodEndDate (for example, "2025-03-05T13:40:00Z").
• You can convert epoch timestamps to ISO strings via this tool.
• The migration_period_end_date also allows you to define a specific period during which both Events2Metrics and Span Metrics data are generated and retained. After this period, only Span Metrics remain. Events2Metrics-based metrics will continue to be generated as long as spans are sent to Coralogix during the defined period, enabling you to revert if needed. Once the retention period ends, Events2Metrics-based metrics will no longer be created.

Validating your data source

Validate data source using the following command:

grpcurl -H "Authorization: <cx_api_key>" -d @ ng-api-grpc.<coralogix_url>:443 com.coralogixapis.service_catalog.v1.ApmSettingsService/GetApmSettings <<EOF
{
"catalog": "SERVICE_CATALOG"
}
EOF

Reducing data volume

To lower metric ingestion and storage costs while simplifying system configurations, consider reducing data volume. Remove the Events2Metrics rules and stop generating Events2Metrics metrics when they have fully transitioned to Span Metrics and no longer require dual-pipeline data collection. This step is suitable for reducing metric ingestion and storage costs, as well as simplifying system configurations. However, it is important to note that any data generated during the period when Events2Metrics rules are removed will not be accessible if the user decides to revert to Events2Metrics later. This action helps decrease the overall data volume but does not directly address or affect cardinality issues.

Update dashboards and alerts

Update Grafana, Coralogix dashboards, and alerting rules to use Span Metrics metric names.

Confirm that SLO and Apdex panels reference your new configuration.

Permissions

To migrate from E2M to Span Metrics, in your Coralogix application, go to Settings, then Roles, then Compare Roles, then APM - Manage Service Catalog Services and verify that the following permissions exist.

Permission Group	Resource	Action	Permission Name
APM	Manage Service Catalog Services	UpdateConfig	SERVICE-CATALOG:UPDATE