diff --git a/docs/non-normative/compatibility/grpc.md b/docs/non-normative/compatibility/grpc.md new file mode 100644 index 0000000000..9d3746f2d3 --- /dev/null +++ b/docs/non-normative/compatibility/grpc.md @@ -0,0 +1,100 @@ + + + + + +# Compatibility between OpenTelemetry and gRPC semantic conventions + + + +- [Metrics](#metrics) + - [Metric mapping](#metric-mapping) + - [Attribute mapping](#attribute-mapping) +- [Spans](#spans) + - [Mapping](#mapping) + - [Additional attributes](#additional-attributes) + - [Events](#events) + + + +The gRPC project defines conventions for [OpenTelemetry Metrics](https://github.com/grpc/proposal/blob/master/A66-otel-stats.md) +and experimental conventions for [OpenTelemetry Tracing](https://github.com/grpc/proposal/blob/master/A72-open-telemetry-tracing.md). + +These conventions differ from the [OpenTelemetry gRPC](/docs/rpc/grpc.md) 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](https://github.com/grpc/proposal/blob/master/A66-otel-stats.md) +and the [OpenTelemetry conventions](/docs/rpc/rpc-metrics.md) 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](/docs/rpc/grpc.md))
OTel -> gRPC: Drop | + +## Spans + +See the [gRPC conventions](https://github.com/grpc/proposal/blob/master/A72-open-telemetry-tracing.md) +and the [OpenTelemetry conventions](/docs/rpc/rpc-spans.md) 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](/docs/rpc/grpc.md)) | 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.` and `rpc.response.metadata.` +- `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. diff --git a/docs/rpc/README.md b/docs/rpc/README.md index 15056b2d81..36631d9136 100644 --- a/docs/rpc/README.md +++ b/docs/rpc/README.md @@ -45,10 +45,6 @@ Technology specific semantic conventions are defined for the following RPC syste * [gRPC](grpc.md): Semantic Conventions for *gRPC*. * [JSON-RPC](json-rpc.md): Semantic Conventions for *JSON-RPC*. -Specifications defined by maintainers of RPC systems: - -* [gRPC](https://github.com/grpc/proposal/blob/master/A66-otel-stats.md): Semantic Conventions for *gRPC*. - For help migrating from non-stable to stable conventions, see [the migration guide](../non-normative/rpc-migration.md). [DocumentStatus]: https://opentelemetry.io/docs/specs/otel/document-status diff --git a/docs/rpc/grpc.md b/docs/rpc/grpc.md index 45315421b8..d5135dc2bd 100644 --- a/docs/rpc/grpc.md +++ b/docs/rpc/grpc.md @@ -19,6 +19,14 @@ The Semantic Conventions for [gRPC](https://grpc.io/) extend and override the [R that describe common RPC operations attributes in addition to the Semantic Conventions described on this page. +> [!NOTE] +> The gRPC project defines its own conventions for [metrics](https://github.com/grpc/proposal/blob/master/A66-otel-stats.md) +> and [spans](https://github.com/grpc/proposal/blob/master/A72-open-telemetry-tracing.md). +> +> Details on how OpenTelemetry spans and metrics defined in this repository +> relate to the native gRPC conventions are documented in the +> [gRPC compatibility](/docs/non-normative/compatibility/grpc.md) document. + ## Spans ### Client