From 95f749e73664b32735f9fee8d12aa54eccf07126 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Christian=20Neum=C3=BCller?= Date: Tue, 3 Aug 2021 18:14:42 +0200 Subject: [PATCH 1/7] Add event semantic conventions. This is a demo for open-telemetry/build-tools#57. (also needs open-telemetry/build-tools#58) --- semantic_conventions/trace/exception.yaml | 1 + semantic_conventions/trace/rpc.yaml | 24 +++++++++++ .../trace/semantic_conventions/rpc.md | 40 +++++++++---------- 3 files changed, 43 insertions(+), 22 deletions(-) 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 202c6ab3ead..7aa2740fb86 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 @@ -124,3 +125,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..89759a4f75b 100644 --- a/specification/trace/semantic_conventions/rpc.md +++ b/specification/trace/semantic_conventions/rpc.md @@ -146,31 +146,27 @@ 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" = -``` + +| 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 | -``` --> [time], - "name" = "message", - "message.type" = "RECEIVED", - "message.id" = id - "message.compressed_size" = , - "message.uncompressed_size" = -``` +**[1]:** This way we guarantee that the values will be consistent between different implementations. -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. +`message.type` MUST be one of the following: + +| Value | Description | +|---|---| +| `SENT` | sent | +| `RECEIVED` | received | + ## JSON RPC From 6e9fe5c96edb244eae70c6df65b8a13c37087c47 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Christian=20Neum=C3=BCller?= Date: Tue, 3 Aug 2021 18:18:57 +0200 Subject: [PATCH 2/7] Add CHANGELOG. --- .vscode/settings.json | 2 +- CHANGELOG.md | 4 ++++ 2 files changed, 5 insertions(+), 1 deletion(-) diff --git a/.vscode/settings.json b/.vscode/settings.json index 77fab00c653..4b3952c1b60 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/dynatrace-oss-contrib/build-tools/events/semantic-conventions/semconv.schema.json": [ "semantic_conventions/**/*.yaml" ] }, diff --git a/CHANGELOG.md b/CHANGELOG.md index 1a184f9578a..2e3a89f9661 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -26,6 +26,10 @@ release. - Adding alibaba cloud as a cloud provider. ([#1831](https://github.com/open-telemetry/opentelemetry-specification/pull/1831)) +- 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. ### Compatibility From 8ee8179c04a8b5eff22569272836a20ab2a4a971 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Christian=20Neum=C3=BCller?= Date: Thu, 5 Aug 2021 11:10:13 +0200 Subject: [PATCH 3/7] Update semantic_conventions/trace/rpc.yaml Co-authored-by: Armin Ruech --- semantic_conventions/trace/rpc.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/semantic_conventions/trace/rpc.yaml b/semantic_conventions/trace/rpc.yaml index 7aa2740fb86..30ea42ab63e 100644 --- a/semantic_conventions/trace/rpc.yaml +++ b/semantic_conventions/trace/rpc.yaml @@ -126,7 +126,7 @@ groups: 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? + prefix: "message" # TODO: Change the prefix to rpc.grpc.message? type: event brief: "gRPC received/sent message." attributes: From fd8ae02dcde810605d5093dbfc5217030043b6c6 Mon Sep 17 00:00:00 2001 From: Armin Ruech Date: Tue, 24 Aug 2021 11:05:57 +0200 Subject: [PATCH 4/7] Update reference to schema --- .vscode/settings.json | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.vscode/settings.json b/.vscode/settings.json index 4b3952c1b60..77fab00c653 100644 --- a/.vscode/settings.json +++ b/.vscode/settings.json @@ -10,7 +10,7 @@ "MD040": false, }, "yaml.schemas": { - "https://raw.githubusercontent.com/dynatrace-oss-contrib/build-tools/events/semantic-conventions/semconv.schema.json": [ + "https://raw.githubusercontent.com/open-telemetry/build-tools/main/semantic-conventions/semconv.schema.json": [ "semantic_conventions/**/*.yaml" ] }, From ce4d7112019a4e03db04f72355c126757869f019 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Christian=20Neum=C3=BCller?= Date: Tue, 24 Aug 2021 11:57:38 +0200 Subject: [PATCH 5/7] Bump/pin links to tool v0.5.0. --- .vscode/settings.json | 2 +- Makefile | 4 +++- semantic_conventions/README.md | 6 +++--- 3 files changed, 7 insertions(+), 5 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/Makefile b/Makefile index d7eb60cff3e..a793a4ab307 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 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. From 4c89b3031832151f2cf0998282ecb2906f5947e5 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Christian=20Neum=C3=BCller?= Date: Tue, 24 Aug 2021 12:00:11 +0200 Subject: [PATCH 6/7] Also mention .vscode in comment. --- Makefile | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Makefile b/Makefile index a793a4ab307..989f353ac8e 100644 --- a/Makefile +++ b/Makefile @@ -9,7 +9,7 @@ MARKDOWN_LINK_CHECK=markdown-link-check MARKDOWN_LINT=markdownlint # see https://github.com/open-telemetry/build-tools/releases for semconvgen updates -# Keep links in semantic_conventions/README.md in sync! +# Keep links in semantic_conventions/README.md and .vscode/settings.json in sync! SEMCONVGEN_VERSION=0.5.0 .PHONY: install-misspell From 0c551b4ea87f6e71e493c52fdc9a80561643b240 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Christian=20Neum=C3=BCller?= Date: Fri, 3 Sep 2021 16:27:43 +0200 Subject: [PATCH 7/7] Update specification/trace/semantic_conventions/rpc.md Co-authored-by: Armin Ruech --- specification/trace/semantic_conventions/rpc.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/specification/trace/semantic_conventions/rpc.md b/specification/trace/semantic_conventions/rpc.md index 89759a4f75b..87879313a6b 100644 --- a/specification/trace/semantic_conventions/rpc.md +++ b/specification/trace/semantic_conventions/rpc.md @@ -150,6 +150,8 @@ 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"`. + | Attribute | Type | Description | Examples | Required | |---|---|---|---|---|