Updating gRPC status semantic conventions (open-telemetry#1156)

* Updating gRPC status semantic conventions Since the simplification of trace status codes, they no longer align with gRPC. Clarifying the expected status code field for gRPC, as well as the mappings between gRPC and OpenTelemetry status. * Adding changelog entry * Addressing feedback Clarifying that gRPC spans should include the status code number, rather than leave it ambiguous. Adding gRPC semantic conventions in the yaml files to reflect these changes. * adding trailing whitespace * Apply suggestions from code review Co-authored-by: Christian Neumüller <[email protected]> * addressing feedback Ran table-generation to ensure that semantic conventions are added. Removed tags for rpc.grpc yaml for now (not explicitly used). * Update specification/trace/semantic_conventions/rpc.md Co-authored-by: Armin Ruech <[email protected]> * Addressing feedback re-generating TOC with markdown-toc There was a conflict with sub-headings matching the same string. As such qualified all headings. * Switching gRPC status_code type to enum gRPC's status_code code is better expressed as an enum. Co-authored-by: Christian Neumüller <[email protected]> Co-authored-by: Armin Ruech <[email protected]>
carlosalberto · Nov 6, 2020 · 1e0e22c · 1e0e22c
1 parent 3e9d4ad
commit 1e0e22c
Show file tree

Hide file tree

Showing 3 changed files with 82 additions and 7 deletions.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -130,6 +130,8 @@ Updates:
   ([#993](https://github.com/open-telemetry/opentelemetry-specification/pull/993))
 - Trace API: Clarifications for `Span.End`, e.g. IsRecording becomes false after End
   ([#1011](https://github.com/open-telemetry/opentelemetry-specification/pull/1011))
+- Update semantic conventions for gRPC for new Span Status
+  ([#1156](https://github.com/open-telemetry/opentelemetry-specification/pull/1156))
 
 ## v0.6.0 (07-01-2020)
 

diff --git a/semantic_conventions/trace/rpc.yaml b/semantic_conventions/trace/rpc.yaml
@@ -33,3 +33,48 @@ groups:
           - net.peer.ip
           - net.peer.name
         - include: network
+    - id: rpc.grpc
+      prefix: rpc.grpc
+      extends: rpc
+      brief: 'Tech-specific attributes for gRPC.'
+      attributes:
+        - id: status_code
+          type:
+            members:
+              - id: OK
+                value: 0
+              - id: CANCELLED
+                value: 1
+              - id: UNKNOWN
+                value: 2
+              - id: INVALID_ARGUMENT
+                value: 3
+              - id: DEADLINE_EXCEEDED
+                value: 4
+              - id: NOT_FOUND
+                value: 5
+              - id: ALREADY_EXISTS
+                value: 6
+              - id: PERMISSION_DENIED
+                value: 7
+              - id: RESOURCE_EXHAUSTED
+                value: 8
+              - id: FAILED_PRECONDITION
+                value: 9
+              - id: ABORTED
+                value: 10
+              - id: OUT_OF_RANGE
+                value: 11
+              - id: UNIMPLEMENTED
+                value: 12
+              - id: INTERNAL
+                value: 13
+              - id: UNAVAILABLE
+                value: 14
+              - id: DATA_LOSS
+                value: 15
+              - id: UNAUTHENTICATED
+                value: 16
+          required: always
+          brief: "The [numeric status code](https://github.com/grpc/grpc/blob/v1.33.2/doc/statuscodes.md) of the gRPC request."
+          examples: [0, 1, 16]
diff --git a/specification/trace/semantic_conventions/rpc.md b/specification/trace/semantic_conventions/rpc.md
@@ -13,7 +13,8 @@ This document defines how to describe remote procedure calls
     + [Service name](#service-name)
   * [Distinction from HTTP spans](#distinction-from-http-spans)
 - [gRPC](#grpc)
-  * [Status](#status)
+  * [gRPC Attributes](#grpc-attributes)
+  * [gRPC Status](#grpc-status)
   * [Events](#events)
 
 <!-- tocstop -->
@@ -42,7 +43,7 @@ Examples of span names:
 
 - `grpc.test.EchoService/Echo`
 - `com.example.ExampleRmiService/exampleMethod`
-- `MyCalcService.Calculator/Add` reported by the server and  
+- `MyCalcService.Calculator/Add` reported by the server and
   `MyServiceReference.ICalculator/Add` reported by the client for .NET WCF calls
 - `MyServiceWithNoPackage/theMethod`
 
@@ -97,14 +98,41 @@ For remote procedure calls via [gRPC][], additional conventions are described in
 
 `rpc.system` MUST be set to `"grpc"`.
 
+### gRPC Attributes
+
+<!-- semconv rpc.grpc -->
+| Attribute  | Type | Description  | Example  | Required |
+|---|---|---|---|---|
+| `rpc.grpc.status_code` | number enum | The [numeric status code](https://github.com/grpc/grpc/blob/v1.33.2/doc/statuscodes.md) of the gRPC request. | `0`<br>`1`<br>`16` | Yes |
+
+`rpc.grpc.status_code` MUST be one of the following:
+
+| Value  | Description |
+|---|---|
+| `0` | OK |
+| `1` | CANCELLED |
+| `2` | UNKNOWN |
+| `3` | INVALID_ARGUMENT |
+| `4` | DEADLINE_EXCEEDED |
+| `5` | NOT_FOUND |
+| `6` | ALREADY_EXISTS |
+| `7` | PERMISSION_DENIED |
+| `8` | RESOURCE_EXHAUSTED |
+| `9` | FAILED_PRECONDITION |
+| `10` | ABORTED |
+| `11` | OUT_OF_RANGE |
+| `12` | UNIMPLEMENTED |
+| `13` | INTERNAL |
+| `14` | UNAVAILABLE |
+| `15` | DATA_LOSS |
+| `16` | UNAUTHENTICATED |
+<!-- endsemconv -->
+
 [gRPC]: https://grpc.io/
 
-### Status
+### gRPC Status
 
-Implementations MUST set status which MUST be the same as the gRPC client/server
-status. The mapping between gRPC canonical codes and OpenTelemetry status codes
-is 1:1 as OpenTelemetry canonical codes is just a snapshot of grpc codes which
-can be found [here](https://github.com/grpc/grpc-go/blob/master/codes/codes.go).
+The [Span Status](../api.md#set-status) MUST be left unset for an `OK` gRPC status code, and set to `Error` for all others.
 
 ### Events