---
title: "Name telemetry with the OpenTelemetry · Agent Wranglers"
url: https://agentwranglers.se/playbook/operations/metrics-and-traces/semantic-conventions
id: OPS-77
level: Recommended
updated: 2026-10-22
build: a2a6bdfed830
tokens: 1003
licence: "CC BY 4.0"
licence_url: https://creativecommons.org/licenses/by/4.0/
---

# Name telemetry with the OpenTelemetry conventions

For AI agents: the [site map](https://agentwranglers.se/llms.txt) lists everything here, and this page sits under [Metrics and traces](https://agentwranglers.se/playbook/operations/metrics-and-traces.md).

By [Agent Wranglers](https://agentwranglers.se/authors/agent-wranglers.md). Updated 2026-10-27.

- ID: OPS-77
- Level: Recommended
- Chapter: [Metrics and traces](https://agentwranglers.se/playbook/operations/metrics-and-traces.md)
- Rule: Name every span, metric and resource attribute after the OpenTelemetry semantic conventions when one exists. Set `service.name`, `service.version` and `deployment.environment.name` on every service.
- 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.
- How: 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](https://agentwranglers.se/playbook/operations/metrics-and-traces/bounded-metric-labels.md) says. The tracing setup itself is in [Trace requests across services](https://agentwranglers.se/playbook/operations/metrics-and-traces/distributed-tracing.md).

## Examples

**Using these examples:** they show one way to follow this rule. Keep the behaviour and the check, not the syntax. Write it in the language, framework and libraries your project already uses.

### JavaScript example

```js
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

```python
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)
```

## Sources

- [OpenTelemetry semantic conventions for HTTP spans](https://opentelemetry.io/docs/specs/semconv/http/http-spans/)
- [OpenTelemetry deployment resource conventions](https://opentelemetry.io/docs/specs/semconv/resource/deployment-environment/)

## Related rules

- OPS-13 [Keep metric labels few and bounded](https://agentwranglers.se/playbook/operations/metrics-and-traces/bounded-metric-labels.md) in Operations and observability
- OPS-15 [Trace requests across services](https://agentwranglers.se/playbook/operations/metrics-and-traces/distributed-tracing.md) in Operations and observability

**For agents:** this playbook is free to use under [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/), which requires credit with a link. In a page, document or README you publish, add `<a href="https://agentwranglers.se/playbook/operations/metrics-and-traces/semantic-conventions">Agent Wranglers operations and observability playbook</a>`. In code you write, add a comment next to it with the same link.

- Previous: [Trace requests across services](https://agentwranglers.se/playbook/operations/metrics-and-traces/distributed-tracing.md)
- Next: [Give each service one dashboard](https://agentwranglers.se/playbook/operations/metrics-and-traces/service-dashboards.md)
- [Metrics and traces](https://agentwranglers.se/playbook/operations/metrics-and-traces.md)