Name telemetry with the OpenTelemetry conventions

How to do it

Dashboards, alerts and queries break when one service writes status and another writes http.status_code. The conventions give each common field one name, such as http.request.method and http.response.status_code. The HTTP conventions are stable. Some instrumentation still writes the older names by default, so set OTEL_SEMCONV_STABILITY_OPT_IN=http to switch it. Give your own attributes a prefix of your own, such as shop.. Keep values with many variants, such as order IDs, on spans and out of metrics, as Keep metric labels few and bounded says. The tracing setup itself is in Trace requests across services.

Examples

JavaScript example

import { NodeSDK } from '@opentelemetry/sdk-node';
import { resourceFromAttributes } from '@opentelemetry/resources';

new NodeSDK({
  resource: resourceFromAttributes({
    'service.name': 'checkout',
    'service.version': process.env.APP_VERSION,
    'deployment.environment.name': 'production',
  }),
}).start();

Python example

import os
from opentelemetry.sdk.resources import Resource
from opentelemetry.sdk.trace import TracerProvider

resource = Resource.create({
    "service.name": "checkout",
    "service.version": os.environ["APP_VERSION"],
    "deployment.environment.name": "production",
})
provider = TracerProvider(resource=resource)

How to check

A CI test sends one request and reads the exported spans. Every attribute name is in the semantic conventions registry or starts with your own prefix. The resource has all three service attributes.

Sources

• OpenTelemetry semantic conventions for HTTP spans
• OpenTelemetry deployment resource conventions

Related rules

• OPS-13 Keep metric labels few and bounded in Operations and observability
• OPS-15 Trace requests across services in Operations and observability