From f5a269fd3de948656c085c25d83342c78c8dc99c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Robert=20Paj=C4=85k?= Date: Mon, 3 Apr 2023 19:27:56 +0200 Subject: [PATCH] BREAKING: Change span statuses for gRPC server spans (#3333) Fixes https://github.com/open-telemetry/opentelemetry-specification/issues/3110 ## Changes The idea behind the PR is to make the spam statuses gRPC convention similar to HTTP semantic conventions. The gRPC statuses -> HTTP status codes mapping is not anywhere strictly defined. However, there is are some approximations which can be found: - https://github.com/grpc/grpc/commit/bb04e070b3177d7bd8e69c4086dc420f662b8f28#diff-c94ff143c8f378e6925a985fa18528a8254a6d7fc34bc855e1de13f1e7f3e464 - https://github.com/googleapis/googleapis/blob/master/google/rpc/code.proto I got confused if we should treat `INTERNAL` as `Error` for `SpanKind.SERVER` because of: - https://github.com/grpc/grpc/blob/master/doc/http-grpc-status-mapping.md - https://github.com/grpc/grpc-go/blob/a02aae6168aa683a1f106e285ec10eb6bc1f6ded/internal/transport/handler_server.go#L90C8-L92 - https://github.com/grpc/grpc-go/blob/a02aae6168aa683a1f106e285ec10eb6bc1f6ded/internal/transport/http_util.go#L73 On the other hand, [the description](https://github.com/grpc/grpc/blob/master/doc/statuscodes.md) of `INTERNAL` says: > Internal errors. This means that some invariants expected by the underlying system have been broken. This error code is reserved for serious errors. Therefore, I decided to leave it as `Error`. Also because this is backwards compatible (at least for this gRPC status). --------- Co-authored-by: Tyler Yahn --- CHANGELOG.md | 2 ++ .../trace/semantic_conventions/rpc.md | 26 ++++++++++++++++++- 2 files changed, 27 insertions(+), 1 deletion(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index f4a63defd60..09c20979e87 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -56,6 +56,8 @@ release. ([#3097](https://github.com/open-telemetry/opentelemetry-specification/pull/3097)) - Clarify stability requirements of semantic conventions ([#3225](https://github.com/open-telemetry/opentelemetry-specification/pull/3225)) +- BREAKING: Change span statuses for gRPC server spans. + ([#3333](https://github.com/open-telemetry/opentelemetry-specification/pull/3333)) ### Compatibility diff --git a/specification/trace/semantic_conventions/rpc.md b/specification/trace/semantic_conventions/rpc.md index f5d6e823457..b70a97fa77b 100644 --- a/specification/trace/semantic_conventions/rpc.md +++ b/specification/trace/semantic_conventions/rpc.md @@ -206,7 +206,31 @@ For remote procedure calls via [gRPC][], additional conventions are described in ### gRPC Status -The [Span Status](../api.md#set-status) MUST be left unset for an `OK` gRPC status code, and set to `Error` for all others. +The table below describes when +the [Span Status](../api.md#set-status) MUST be set +to `Error` or remain unset +depending on the [gRPC status code](https://github.com/grpc/grpc/blob/v1.33.2/doc/statuscodes.md) +and [Span Kind](../api.md#spankind). + +| gRPC Status Code | `SpanKind.SERVER` Span Status | `SpanKind.CLIENT` Span Status | +|---|---|---| +| OK | unset | unset | +| CANCELLED | unset | `Error` | +| UNKNOWN | `Error` | `Error` | +| INVALID_ARGUMENT | unset | `Error` | +| DEADLINE_EXCEEDED | `Error` | `Error` | +| NOT_FOUND | unset | `Error` | +| ALREADY_EXISTS | unset | `Error` | +| PERMISSION_DENIED | unset | `Error` | +| RESOURCE_EXHAUSTED | unset| `Error` | +| FAILED_PRECONDITION | unset | `Error` | +| ABORTED | unset | `Error` | +| OUT_OF_RANGE | unset | `Error` | +| UNIMPLEMENTED | `Error` | `Error` | +| INTERNAL | `Error` | `Error` | +| UNAVAILABLE | `Error` | `Error` | +| DATA_LOSS | `Error` | `Error` | +| UNAUTHENTICATED | unset | `Error` | ### gRPC Request and Response Metadata