Copy as Markdown[Open in ChatGPT](https://chatgpt.com/?q=Read%20https%3A%2F%2Fdocs-docusaurus.kinsta.page%2Fuser-guides%2Fapm%2Fgetting-started%2Faligning-coralogix-and-otel-naming-conventions.md%20and%20help%20me%20with%20my%20question%20about%20this%20Coralogix%20documentation%20page.)[Open in Claude](https://claude.ai/new?q=Read%20https%3A%2F%2Fdocs-docusaurus.kinsta.page%2Fuser-guides%2Fapm%2Fgetting-started%2Faligning-coralogix-and-otel-naming-conventions.md%20and%20help%20me%20with%20my%20question%20about%20this%20Coralogix%20documentation%20page.)

# 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[​](#usage-guidelines "Direct link to Usage guidelines")

Coralogix APM and the OpenTelemetry Collector currently support the label conventions outlined in the [APM label conventions supported by Coralogix](#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[​](#align-span-attributes-with-coralogix-supported-metric-label-conventions "Direct link to 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](https://docs-docusaurus.kinsta.page/user-guides/apm/getting-started/span-metrics/.md) and [Events2Metrics](https://docs-docusaurus.kinsta.page/user-guides/monitoring-and-insights/events2metrics/.md) 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[​](#span-metrics "Direct link to 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[​](#events2metrics "Direct link to 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[​](#apm-label-conventions-supported-by-coralogix "Direct link to 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[​](#span-metrics-1 "Direct link to 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[​](#events2metrics-1 "Direct link to 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` |

## Next steps[​](#next-steps "Direct link to Next steps")

With your data flowing in, head to the [Service Catalog](https://docs-docusaurus.kinsta.page/user-guides/apm/features/service-catalog/.md) to start exploring services, dependencies, and health.

## Additional resources[​](#additional-resources "Direct link to Additional resources")

* [More examples in Coralogix public GitHub repository](https://github.com/coralogix/telemetry-shippers/tree/master/otel-integration/k8s-helm#note-on-semantic-conventions-for-old-otel-sdks)
* [values.yaml template](https://github.com/coralogix/telemetry-shippers/blob/master/otel-integration/k8s-helm/values.yaml)