Aligning Coralogix and OTel Naming Conventions

OpenTelemetry sometimes introduces breaking changes that, if left unaddressed, can disrupt the experience for customers upgrading to newer versions. To prevent this, enable a transform statement to ensure that span attributes and metric labels conform to Coralogix-supported label conventions.

Usage guidelines

Coralogix APM and the OpenTelemetry Collector currently support the label conventions outlined in the APM label conventions supported by Coralogix section below. If you use labels that do not adhere to Coralogix conventions, utilize a transform processor in the OpenTelemetry Collector to extract the values from your custom labels and map them to the conventions supported by Coralogix.

Align span attributes with Coralogix-supported metric label conventions

Span Metrics rely on metrics directly gathered from the collector. Events2Metrics, on the other hand, are derived from spans that are sent to Coralogix, which are then converted into metrics using the Events2Metrics method. For more detailed information, refer to the Span Metrics and Events2Metrics documentation.

Use the transform/spanmetrics or transform/event2metric processor to align span attributes with Coralogix-supported metric label conventions when collecting metrics through Span Metrics or Events2Metrics. In the next sections, we will explore how to use the transform statement in each of these methods.

Span Metrics

Updating the transform/spanmetrics processor

Add the required transformation as part of the transform/spanmetrics processor. The following example illustrates how to transform attributes into a supported convention.

transform/spanmetrics:
        error_mode: silent
        trace_statements:
        - context: span
          statements:
          - set(attributes["db.namespace"], attributes["db.name"]) where attributes["db.namespace"]
            == nil
          - set(attributes["db.namespace"], attributes["server.address"]) where attributes["db.namespace"]
            == nil
          - set(attributes["db.namespace"], attributes["network.peer.name"]) where attributes["db.namespace"]
            == nil
          - set(attributes["db.namespace"], attributes["net.peer.name"]) where attributes["db.namespace"]
            == nil
          - set(attributes["db.namespace"], attributes["db.system"]) where attributes["db.namespace"]
            == nil
          - set(attributes["db.operation.name"], attributes["db.operation"]) where attributes["db.operation.name"]
            == nil
          - set(attributes["db.collection.name"], attributes["db.sql.table"]) where attributes["db.collection.name"]
            == nil
          - set(attributes["db.collection.name"], attributes["db.cassandra.table"]) where
            attributes["db.collection.name"] == nil
          - set(attributes["db.collection.name"], attributes["db.mongodb.collection"])
            where attributes["db.collection.name"] == nil
          - set(attributes["db.collection.name"], attributes["db.redis.database_index"])
            where attributes["db.collection.name"] == nil
          - set(attributes["db.collection.name"], attributes["db.elasticsearch.path_parts.index"])
            where attributes["db.collection.name"] == nil
          - set(attributes["db.collection.name"], attributes["db.cosmosdb.container"])
            where attributes["db.collection.name"] == nil
          - set(attributes["db.collection.name"], attributes["aws_dynamodb.table_names"])
            where attributes["db.collection.name"] == nil

Adding the transform/spanmetrics to the pipeline

Place the transform/spanmetrics processor above the batch processor in the traces pipeline.

        traces:
          exporters:
          - debug
          - spanmetrics
          - forward/db
          processors:
          - memory_limiter
          - resource/metadata
          - k8sattributes
          - transform/k8s_attributes
          - transform/spanmetrics
          - batch

Events2Metrics

Updating the transform/spanmetrics processor

Add the required transformation as part of the transform/spanmetrics processor. For example, Coralogix uses http.method, whereas another convention uses http.request.method. In this case, map http.request.method to http.method.

transform/event2metric:
    error_mode: silent
    trace_statements:
      - context: span
        statements:
          - set(attributes["http.method"], attributes["http.request.method"]) where attributes["http.method"] == nil

Adding the transform/spanmetrics processor to the pipeline

Add the transform processor above the batch processor within the trace pipeline.

        traces:
          exporters:
          - debug
          - forward/db
          processors:
          - memory_limiter
          - resource/metadata
          - k8sattributes
          - transform/k8s_attributes
          - transform/event2metric
          - batch

APM label conventions supported by Coralogix

Coralogix fully supports OpenTelemetry, including its semantic conventions. However, as the OpenTelemetry specification evolves, new attributes or updates may be introduced that are not yet fully supported. To ensure consistent processing and accurate visualization within Coralogix, we recommend transforming span attributes and metric labels to align with the supported conventions outlined below.

Span Metrics

Service Catalog

Metric	Label
duration_ms_sum	span_name, service_name, span_kind, status_code, http_method
duration_ms_bucket	span_name, service_name, span_kind, status_code, http_method, le
calls_total	span_name, service_name, span_kind, status_code, http_method
duration_ms_count	span_name, service_name, span_kind, status_code, http_method

Database Catalog

Metric	Label
db_calls_total	status_code, db_system, db_namespace, span_name, db_operation_name, db_collection_name, service_name
db_duration_ms_sum	status_code, db_system, db_namespace, span_name, db_operation_name, db_collection_name, service_name
db_duration_ms_count	status_code, db_system, db_namespace, span_name, db_operation_name, db_collection_name, service_name
db_duration_ms_bucket	status_code, db_system, db_namespace, span_name, db_operation_name, db_collection_name, service_name, le

Events2Metrics

Service Catalog

Coralogix/process tag	OpenTelemetry attribute
servicename	service.name
operationname	span.name
tags.error	error
tags.http.method	http.method
tags.span.kind	span.kind
tags.peer.service	peer.service
tags.cgx.transaction	cgx.transaction
tags.cgx.transaction.root	cgx.transaction.root
tags.http.status_code	http.status_code
tags.rpc.grpc.status_code	rpc.grpc.status_code
process.tags.service.version	service.version

Database Catalog

Coralogix/process tag	OpenTelemetry attribute
servicename	service.name
tags.error	error
tags.db.system	db.system
tags.db.name	db.name
tags.db.namespace	db.namespace
tags.net.peer.name	net.peer.name
tags.network.peer.name	net.peer.name
tags.db.sql.table	db.sql.table
tags.aws.dynamodb.table_names	db.dynamodb.table_names
tags.db.cosmosdb.container	db.cosmosdb.container
tags.db.elasticsearch.path_parts.index	db.elasticsearch.index
tags.db.redis.database_index	db.redis.database_index
tags.db.mongodb.collection	db.mongodb.collection
tags.db.cassandra.table	db.cassandra.table
tags.db.collection.name	db.collection.name
operationname	span.name
tags.db.operation	db.operation
tags.db.operation.name	db.operation.name
tags.db.statement.blueprint.id	db.statement.blueprint.id

Additional resources

• More examples in Coralogix public GitHub repository
• values.yaml template