Compatibility between OpenTelemetry and gRPC semantic conventions

The gRPC project defines conventions for OpenTelemetry Metrics and experimental conventions for OpenTelemetry Tracing.

These conventions differ from the OpenTelemetry gRPC conventions hosted in this repository.

This document provides mappings (where applicable) between the OpenTelemetry conventions hosted in this repository and the native gRPC conventions.

Metrics

See the gRPC conventions and the OpenTelemetry conventions for details.

Metric mapping

gRPC metric	OpenTelemetry metric	Conversion comments
`grpc.client.call.duration`	`rpc.client.call.duration`	See the attribute mapping below; metrics are equivalent otherwise
`grpc.server.call.duration`	`rpc.server.call.duration`	See the attribute mapping below; metrics are equivalent otherwise
`grpc.client.attempt.started`	no equivalent
`grpc.client.attempt.duration`	no equivalent
`grpc.client.attempt.sent_total_compressed_message_size`	no equivalent
`grpc.client.attempt.rcvd_total_compressed_message_size`	no equivalent
`grpc.server.call.started`	no equivalent
`grpc.server.call.sent_total_compressed_message_size`	no equivalent
`grpc.server.call.rcvd_total_compressed_message_size`	no equivalent

Attribute mapping

gRPC attribute	OpenTelemetry attribute(s)	Conversion comments
`grpc.method`	`rpc.method`	gRPC -> OTel: When the value is `other`, replace it with `_OTHER` OTel -> gRPC: When the value is `_OTHER`, replace it with `other`
`grpc.status`	`rpc.response.status_code`
`grpc.target`		gRPC -> OTel: Drop OTel -> gRPC: Set `grpc.target` to `{server.address}[:{server.port}]`
	`server.address` and `server.port`	gRPC -> OTel: Parse the address and port from `grpc.target` OTel -> gRPC: Drop
	`rpc.system.name`	gRPC -> OTel: Set to `grpc` OTel -> gRPC: Drop
	`error.type`	gRPC -> OTel: Set to `rpc.response.status_code` when it indicates an error (see gRPC OpenTelemetry conventions) OTel -> gRPC: Drop

Spans

See the gRPC conventions and the OpenTelemetry conventions for details.

The gRPC conventions define two types of client spans: call and attempt. The gRPC call span maps to the OpenTelemetry RPC client span. Both span types cover the end-to-end duration of the client call. OpenTelemetry does not define a per-attempt span.

In the case of server spans, both the gRPC and OpenTelemetry conventions define one per-call server span.

Mapping

Property	gRPC	OpenTelemetry	Conversion comments
Span name	`Sent.{method name}` (client) `Recv.{method name}` (server) Note: The gRPC span name may be of high cardinality in edge cases.	`{rpc.method}`	gRPC -> OTel: Remove the `Sent.` or `Recv.` prefix OTel -> gRPC: Add the prefix based on the span kind
Span status code	`ERROR` when the response status code is not `OK`	`ERROR` for specific error status codes (see the gRPC OpenTelemetry conventions)	gRPC -> OTel: Parse `rpc.response.status_code` from the status description and set the span status code accordingly OTel -> gRPC: Set based on `rpc.response.status_code`
Span status description	Code and description (e.g., `UNAVAILABLE, unable to resolve host`)	Description only (the error code is recorded separately)
Attributes		`rpc.system.name`	gRPC -> OTel: set to `grpc` OTel -> gRPC: drop
		`rpc.method`	gRPC -> OTel: parse from the span name OTel -> gRPC: drop
		`rpc.response.status_code`	gRPC -> OTel: parse from the status description OTel -> gRPC: drop

Additional attributes

OpenTelemetry defines a few other (non-required) gRPC span attributes listed below. When converting from gRPC spans to OpenTelemetry spans, these attributes should not be set. When converting from OpenTelemetry to gRPC, they should be preserved.

network.peer.address
network.peer.port
server.address
server.port
rpc.request.metadata.<key> and rpc.response.metadata.<key>
rpc.method_original
(server spans only) client.address and client.port

Events

gRPC spans may contain additional events that should be recorded as-is when converting to OpenTelemetry.

Feedback

Was this page helpful?

Thank you. Your feedback is appreciated!

Please let us know how we can improve this page. Your feedback is appreciated!