Add event semantic conventions, update semantic convention generator …

…to v0.5.0 (#1843)

Co-authored-by: Armin Ruech <[email protected]>

.vscode/settings.json

@@ -10,7 +10,7 @@
         "MD040": false,
     },
     "yaml.schemas": {
-        "https://raw.githubusercontent.com/open-telemetry/build-tools/main/semantic-conventions/semconv.schema.json": [
+        "https://raw.githubusercontent.com/open-telemetry/build-tools/v0.5.0/semantic-conventions/semconv.schema.json": [
             "semantic_conventions/**/*.yaml"
         ]
     },

CHANGELOG.md

@@ -27,6 +27,10 @@ release.
   ([#1863](https://github.com/open-telemetry/opentelemetry-specification/pull/1863))
 - Lambda instrumentations should check if X-Ray parent context is valid
   ([#1867](https://github.com/open-telemetry/opentelemetry-specification/pull/1867))
+- Update YAML definitions for events
+  ([#1843](https://github.com/open-telemetry/opentelemetry-specification/pull/1843)):
+  - Mark exception as semconv type "event".
+  - Add YAML definitions for grpc events.
 - Add `messaging.consumer_id` to differentiate between message consumers.
   ([#1810](https://github.com/open-telemetry/opentelemetry-specification/pull/1810))
 

Makefile

@@ -7,8 +7,10 @@ MISSPELL_BINARY=bin/misspell
 MISSPELL = $(TOOLS_DIR)/$(MISSPELL_BINARY)
 MARKDOWN_LINK_CHECK=markdown-link-check
 MARKDOWN_LINT=markdownlint
+
 # see https://github.com/open-telemetry/build-tools/releases for semconvgen updates
-SEMCONVGEN_VERSION=0.4.1
+# Keep links in semantic_conventions/README.md and .vscode/settings.json in sync!
+SEMCONVGEN_VERSION=0.5.0
 
 .PHONY: install-misspell
 install-misspell:

semantic_conventions/README.md

@@ -17,12 +17,12 @@ i.e.:
 Semantic conventions for the spec MUST adhere to the
 [attribute naming conventions](../specification/common/attribute-naming.md).
 
-Refer to the [syntax](https://github.com/open-telemetry/build-tools/tree/main/semantic-conventions/syntax.md)
+Refer to the [syntax](https://github.com/open-telemetry/build-tools/tree/v0.5.0/semantic-conventions/syntax.md)
 for how to write the YAML files for semantic conventions and what the YAML properties mean.
 
 A schema file for VS code is configured in the `/.vscode/settings.json` of this
 repository, enabling auto-completion and additional checks. Refer to
-[the generator README](https://github.com/open-telemetry/build-tools/tree/main/semantic-conventions/README.md) for what extension you need.
+[the generator README](https://github.com/open-telemetry/build-tools/tree/v0.5.0/semantic-conventions/README.md) for what extension you need.
 
 ## Generating markdown
 
@@ -33,7 +33,7 @@ formatted Markdown tables for all semantic conventions in the specification. Run
 make table-generation
 ```
 
-For more information, see the [semantic convention generator](https://github.com/open-telemetry/build-tools/tree/main/semantic-conventions)
+For more information, see the [semantic convention generator](https://github.com/open-telemetry/build-tools/tree/v0.5.0/semantic-conventions)
 in the OpenTelemetry build tools repository.
 Using this build tool, it is also possible to generate code for use in OpenTelemetry
 language projects.

semantic_conventions/trace/exception.yaml

@@ -1,6 +1,7 @@
 groups:
   - id: exception
     prefix: exception
+    type: event
     brief: >
       This document defines the attributes used to
       report a single exception associated with a span.

semantic_conventions/trace/rpc.yaml

@@ -2,6 +2,7 @@ groups:
   - id: rpc
     prefix: rpc
     brief: 'This document defines semantic conventions for remote procedure calls.'
+    events: [rpc.grpc.message]
     attributes:
       - id: system
         type: string
@@ -141,3 +142,26 @@ groups:
         note: >
           This is always required for jsonrpc. See the note in the general
           RPC conventions for more information.
+  - id: rpc.grpc.message
+    prefix: "message"  # TODO: Change the prefix to rpc.grpc.message?
+    type: event
+    brief: "gRPC received/sent message."
+    attributes:
+      - id: type
+        type:
+          members:
+            - id: sent
+              value: "SENT"
+            - id: received
+              value: "RECEIVED"
+        brief: "Whether this is a received or sent message."
+      - id: id
+        type: int
+        brief: "MUST be calculated as two different counters starting from `1` one for sent messages and one for received message."
+        note: "This way we guarantee that the values will be consistent between different implementations."
+      - id: compressed_size
+        type: int
+        brief: "Compressed size of the message in bytes."
+      - id: uncompressed_size
+        type: int
+        brief: "Uncompressed size of the message in bytes."

specification/trace/semantic_conventions/rpc.md

@@ -146,31 +146,29 @@ The [Span Status](../api.md#set-status) MUST be left unset for an `OK` gRPC stat
 ### Events
 
 In the lifetime of a gRPC stream, an event for each message sent/received on
-client and server spans SHOULD be created with the following attributes:
+client and server spans SHOULD be created. In case of
+unary calls only one sent and one received message will be recorded for both
+client and server spans.
 
-```
--> [time],
-    "name" = "message",
-    "message.type" = "SENT",
-    "message.id" = id
-    "message.compressed_size" = <compressed size in bytes>,
-    "message.uncompressed_size" = <uncompressed size in bytes>
-```
+The event name MUST be `"message"`.
 
-```
--> [time],
-    "name" = "message",
-    "message.type" = "RECEIVED",
-    "message.id" = id
-    "message.compressed_size" = <compressed size in bytes>,
-    "message.uncompressed_size" = <uncompressed size in bytes>
-```
+<!-- semconv rpc.grpc.message -->
+| Attribute  | Type | Description  | Examples  | Required |
+|---|---|---|---|---|
+| `message.type` | string | Whether this is a received or sent message. | `SENT` | No |
+| `message.id` | int | MUST be calculated as two different counters starting from `1` one for sent messages and one for received message. [1] |  | No |
+| `message.compressed_size` | int | Compressed size of the message in bytes. |  | No |
+| `message.uncompressed_size` | int | Uncompressed size of the message in bytes. |  | No |
 
-The `message.id` MUST be calculated as two different counters starting from `1`
-one for sent messages and one for received message. This way we guarantee that
-the values will be consistent between different implementations. In case of
-unary calls only one sent and one received message will be recorded for both
-client and server spans.
+**[1]:** This way we guarantee that the values will be consistent between different implementations.
+
+`message.type` MUST be one of the following:
+
+| Value  | Description |
+|---|---|
+| `SENT` | sent |
+| `RECEIVED` | received |
+<!-- endsemconv -->
 
 ## JSON RPC