---
name: otel-attribute-names
description: Looks up exact OpenTelemetry attribute names before code sets, renames or queries them, with type, stability and renamed names, from the attribute lookup on hashspan.dev. Covers gen_ai.*, mcp.*, rpc.*, jsonrpc.*, http.*, error.type, server.* and client.*, plus hashspan's blockchain.*, x402.* and mpp.*. Use when writing span attributes or instrumentation, building dashboards or trace queries, or reviewing attribute names, for example for AI agents and LLM calls.
license: Apache-2.0
---

# Use the exact OpenTelemetry attribute names

Backends, dashboards and queries match attribute names exactly. A name that is almost right looks fine in one trace
and breaks every query that expects the real one. Look names up; never write one from memory.

## 1. Look the name up first

Fetch https://hashspan.dev/learn/otel-attributes.md. Its table lists every attribute with its type, stability and the
namespace page that describes it. For the details of one namespace, fetch that page, such as
https://hashspan.dev/learn/otel-attributes/gen-ai.md for `gen_ai.*` and `mcp.*`.

For each name you will use, check:

- **The name, character for character.** Copy it from the table.
- **The type.** Set an int as an int and a string array as an array, not as a joined string.
- **The stability.** Development names can still change. Say so when the code depends on one.

## 2. Replace renamed names

Most namespace pages have a section on names that were renamed or removed, with the replacement. When the code or a
query uses an old name, such as `gen_ai.system`, switch to the new one (`gen_ai.provider.name`) and tell the user
that dashboards and queries on the old name need the same change.

The OpenTelemetry registry shows every `gen_ai.*` attribute as deprecated because the GenAI conventions moved to their
own repository. That alone is not a reason to rename anything: the lookup pages explain which names really changed.

## 3. Transactions and agent payments

The `blockchain.*`, `x402.*` and `mpp.*` names come from hashspan's semantic conventions:
https://hashspan.dev/docs/reference/semantic-conventions.md. When a project uses hashspan, hashspan records the send,
confirm and payment spans and these attributes itself. Don't create spans with those names or set those attributes
by hand; to add hashspan, use the `hashspan` skill.

## 4. When no name fits

Say so. Don't invent a name inside an OpenTelemetry namespace such as `gen_ai.*` or `http.*`, or inside hashspan's.
If the user still needs the attribute, propose a name under a namespace the project owns, and say it is custom.

## 5. Report

List each attribute you used or changed: name, type, stability and the page you checked it on.