OpenTelemetry Semantic Conventions are standardised attribute names and values for common operations. Using them ensures your telemetry is compatible with community-built dashboards, alerts, and auto-instrumentation libraries, and that data from different services and languages remains consistent.
Semantic conventions are versioned and published at opentelemetry.io/docs/specs/semconv. The tables below reflect the stable conventions as of OTel specification v1.26.
HTTP
Apply these attributes on spans created by HTTP clients and servers. They are the most commonly queried attributes for golden-signal dashboards (request rate, error rate, latency).
| Attribute | Type | Required | Example | Notes |
http.request.method | string | Yes | GET | Uppercase HTTP verb |
http.request.method_original | string | If different from http.request.method | get | Original casing when normalised |
http.response.status_code | int | Yes | 200 | Set on completion of the request |
url.full | string | Client spans | https://api.example.com/v1/orders | Full URL including query string |
url.path | string | Server spans | /v1/orders | Path component only |
url.query | string | No | page=2&limit=50 | Query string without ? |
url.scheme | string | Yes | https | Protocol scheme |
server.address | string | Yes | api.example.com | Host header value or target hostname |
server.port | int | If non-default | 8443 | Omit for standard ports (80, 443) |
network.protocol.name | string | No | http | Always lowercase |
network.protocol.version | string | No | 1.1 | HTTP version negotiated |
user_agent.original | string | Server spans | Mozilla/5.0 ... | Raw User-Agent header |
Set http.response.status_code only after the response is received. Do not set it on spans that represent outbound requests still in-flight.
Database
Apply these attributes on spans wrapping calls to SQL, NoSQL, caching, and search systems. The db.statement attribute is the single most valuable field for query performance analysis.
| Attribute | Type | Required | Example | Notes |
db.system | string | Yes | postgresql | See db.system values |
db.name | string | If applicable | orders_db | Database or keyspace name |
db.statement | string | Recommended | SELECT * FROM orders WHERE id = ? | Sanitise sensitive values |
db.operation | string | Recommended | SELECT | Uppercase SQL verb or operation name |
db.sql.table | string | If deterministic | orders | Primary table affected |
db.user | string | No | app_user | Database user |
server.address | string | Yes | db.internal | Database host |
server.port | int | If non-default | 5432 | Database port |
db.connection_string | string | No | postgresql://db.internal/orders | Exclude passwords |
db.system values
| Value | System |
postgresql | PostgreSQL |
mysql | MySQL / MariaDB |
mssql | Microsoft SQL Server |
oracle | Oracle Database |
mongodb | MongoDB |
redis | Redis |
elasticsearch | Elasticsearch |
cassandra | Apache Cassandra |
dynamodb | Amazon DynamoDB |
Always sanitise db.statement replace literal parameter values with placeholders (? or $1) before recording to avoid capturing PII or credentials in your trace backend.
Messaging
Apply these attributes on producer and consumer spans for message queues and event streams. They enable end-to-end tracing from producer publish to consumer process.
| Attribute | Type | Required | Example | Notes |
messaging.system | string | Yes | kafka | See messaging.system values |
messaging.destination.name | string | Yes | order-events | Topic, queue, or exchange name |
messaging.destination.kind | string | No | topic | topic, queue, or exchange |
messaging.operation | string | Yes | publish | publish, receive, or process |
messaging.message.id | string | Recommended | msg-abc123 | Unique message identifier |
messaging.message.body.size | int | No | 512 | Uncompressed body size in bytes |
messaging.batch.message_count | int | Batch ops | 100 | Number of messages in a batch |
messaging.kafka.message.key | string | No | order-42 | Kafka partition key |
messaging.kafka.partition | int | No | 3 | Kafka partition number |
messaging.kafka.consumer.group | string | Consumer spans | order-processor | Kafka consumer group ID |
messaging.rabbitmq.destination.routing_key | string | No | orders.created | RabbitMQ routing key |
messaging.system values
| Value | System |
kafka | Apache Kafka |
rabbitmq | RabbitMQ |
aws_sqs | Amazon SQS |
aws_sns | Amazon SNS |
azure_service_bus | Azure Service Bus |
gcp_pubsub | Google Cloud Pub/Sub |
activemq | Apache ActiveMQ |
RPC
Apply these attributes on spans wrapping remote procedure calls. The combination of rpc.system, rpc.service, and rpc.method identifies exactly which operation was invoked.
| Attribute | Type | Required | Example | Notes |
rpc.system | string | Yes | grpc | See rpc.system values |
rpc.service | string | Recommended | OrderService | Fully qualified service name |
rpc.method | string | Recommended | CreateOrder | Method name |
rpc.grpc.status_code | int | gRPC spans | 0 | gRPC status code (0 = OK) |
rpc.jsonrpc.version | string | JSON-RPC spans | 2.0 | JSON-RPC protocol version |
rpc.jsonrpc.method | string | JSON-RPC spans | subtract | JSON-RPC method name |
server.address | string | Yes | grpc.internal | Server hostname |
server.port | int | If non-default | 50051 | Server port |
network.transport | string | No | tcp | Transport protocol |
rpc.system values
| Value | System |
grpc | gRPC |
java_rmi | Java RMI |
dotnet_wcf | .NET WCF |
apache_dubbo | Apache Dubbo |
connect_rpc | Connect RPC |
Resource attributes
Resource attributes describe the entity producing telemetry the service, the host, the container. They are set once at SDK initialisation and attached to all signals, not to individual spans.
Service
| Attribute | Example | Notes |
service.name | order-api | Required. Used as the primary service identifier in all backends |
service.version | 2.4.1 | Semantic version of the deployed artifact |
service.namespace | e-commerce | Logical grouping of related services |
service.instance.id | pod-abc123 | Unique ID of this running instance (pod name, container ID) |
Host
| Attribute | Example | Notes |
host.name | ip-10-0-1-42.ec2.internal | Hostname of the machine |
host.id | i-0a1b2c3d4e5f | Unique host identifier (EC2 instance ID, etc.) |
host.arch | amd64 | CPU architecture |
host.type | t3.medium | Machine type or instance type |
Container
| Attribute | Example | Notes |
container.name | order-api | Container name |
container.id | a1b2c3d4e5f6 | Container runtime ID |
container.image.name | myrepo/order-api | Image name without tag |
container.image.tag | 2.4.1 | Image tag |
container.runtime | docker | Container runtime (docker, containerd, cri-o) |
Cloud
| Attribute | Example | Notes |
cloud.provider | aws | aws, gcp, azure |
cloud.account.id | 123456789012 | Cloud account or project ID |
cloud.region | eu-west-1 | Cloud region |
cloud.availability_zone | eu-west-1a | Availability zone |
cloud.platform | aws_eks | Specific cloud service platform |
Kubernetes
| Attribute | Example | Notes |
k8s.cluster.name | prod-cluster | Kubernetes cluster name |
k8s.namespace.name | payments | Pod namespace |
k8s.pod.name | order-api-6d4f9b-xk2lp | Pod name |
k8s.pod.uid | abc-123 | Pod UID |
k8s.container.name | order-api | Container name within the pod |
k8s.deployment.name | order-api | Deployment name |
k8s.node.name | ip-10-0-1-42 | Node name |
General span attributes
These attributes apply to any span type and cover errors, exceptions, and events.
Errors
| Attribute | Type | Example | Notes |
error.type | string | java.io.IOException | Exception class name or error code. Set when span.status is ERROR |
Exceptions
Record exceptions as span events (not span attributes) using span.recordException(). The event name is always exception.
| Attribute | Type | Example | Notes |
exception.type | string | java.io.IOException | Fully qualified exception class |
exception.message | string | Connection refused | Exception message |
exception.stacktrace | string | at com.example... | Full stack trace string |
exception.escaped | bool | false | Whether the exception escaped the instrumented scope |
Events
| Attribute | Type | Example | Notes |
event.name | string | order.placed | Identifies the event type on a span event |
Attribute naming conventions
When adding custom attributes that are not covered by a semantic convention, follow these rules to keep them discoverable and consistent.
| Rule | Good | Bad |
| Use dot-separated namespaces | order.id, payment.method | orderId, payment_method |
| Use lowercase only | order.status | Order.Status |
| Use singular nouns | db.table, http.header | db.tables, http.headers |
| Prefix with your org for truly custom attributes | acme.order.priority | priority |
| Do not shadow reserved prefixes | | http.my_field, db.custom |
Reserved top-level namespaces that must not be used for custom attributes: http, db, messaging, rpc, faas, net, peer, exception, thread, code, k8s, host, container, process, service, telemetry, otel.
