From 32ca5a72cb4c67084b92101f8abceee7ca35dee0 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Christian=20Neum=C3=BCller?= Date: Fri, 3 Sep 2021 16:59:33 +0200 Subject: [PATCH] Add event semantic conventions, update semantic convention generator to v0.5.0 (#1843) Co-authored-by: Armin Ruech --- .vscode/settings.json | 2 +- CHANGELOG.md | 4 ++ Makefile | 4 +- semantic_conventions/README.md | 6 +-- semantic_conventions/trace/exception.yaml | 1 + semantic_conventions/trace/rpc.yaml | 24 +++++++++++ .../trace/semantic_conventions/rpc.md | 42 +++++++++---------- 7 files changed, 56 insertions(+), 27 deletions(-) diff --git a/.vscode/settings.json b/.vscode/settings.json index 77fab00c653..45a5840412a 100644 --- 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" ] }, diff --git a/CHANGELOG.md b/CHANGELOG.md index c6fd1db3a40..e3b636c4722 100644 --- a/CHANGELOG.md +++ b/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)) diff --git a/Makefile b/Makefile index d7eb60cff3e..989f353ac8e 100644 --- a/Makefile +++ b/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: diff --git a/semantic_conventions/README.md b/semantic_conventions/README.md index 3b59de62dac..95ce5ba2ef2 100644 --- 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. diff --git a/semantic_conventions/trace/exception.yaml b/semantic_conventions/trace/exception.yaml index 81c1a298ce7..29573771030 100644 --- 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. diff --git a/semantic_conventions/trace/rpc.yaml b/semantic_conventions/trace/rpc.yaml index f549cd10ca7..c4399519f23 100644 --- 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." diff --git a/specification/trace/semantic_conventions/rpc.md b/specification/trace/semantic_conventions/rpc.md index 9a14e465b2f..87879313a6b 100644 --- a/specification/trace/semantic_conventions/rpc.md +++ b/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" = , - "message.uncompressed_size" = -``` +The event name MUST be `"message"`. -``` --> [time], - "name" = "message", - "message.type" = "RECEIVED", - "message.id" = id - "message.compressed_size" = , - "message.uncompressed_size" = -``` + +| 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 | + ## JSON RPC