Add event semantic conventions, update semantic convention generator to v0.5.0 (#1843)

Co-authored-by: Armin Ruech <armin.ruech@dynatrace.com>
2021-09-03 16:59:33 +02:00 · 2021-09-03 16:59:33 +02:00 · 525baf1b76
parent 7c04982127
commit 525baf1b76
6 changed files with 53 additions and 28 deletions
--- a/.vscode/settings.json
+++ b/.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"
        ]
    },
--- a/4
+++ b/4
@ -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:
--- a/semantic_conventions/README.md
+++ b/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.
--- a/semantic_conventions/trace/exception.yaml
+++ b/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.
--- a/semantic_conventions/trace/rpc.yaml
+++ b/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."
--- a/specification/trace/semantic_conventions/rpc.md
+++ b/specification/trace/semantic_conventions/rpc.md
@ -146,32 +146,30 @@ 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:
-
-```
-> [time],
-    "name" = "message",
-    "message.type" = "SENT",
-    "message.id" = id
-    "message.compressed_size" = <compressed size in bytes>,
-    "message.uncompressed_size" = <uncompressed size in bytes>
-```
-
-```
-> [time],
-    "name" = "message",
-    "message.type" = "RECEIVED",
-    "message.id" = id
-    "message.compressed_size" = <compressed size in bytes>,
-    "message.uncompressed_size" = <uncompressed size in bytes>
-```
-
-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
+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.

+The event name MUST be `"message"`.
+
+<!-- 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 |
+
+**[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

 Conventions specific to [JSON RPC](https://www.jsonrpc.org/).