From 95f749e73664b32735f9fee8d12aa54eccf07126 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Christian=20Neum=C3=BCller?=
 <christian.neumueller@dynatrace.com>
Date: Tue, 3 Aug 2021 18:14:42 +0200
Subject: [PATCH] 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" = <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 |
 
-```
--> [time],
-    "name" = "message",
-    "message.type" = "RECEIVED",
-    "message.id" = id
-    "message.compressed_size" = <compressed size in bytes>,
-    "message.uncompressed_size" = <uncompressed size in bytes>
-```
+**[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 |
+<!-- endsemconv -->
 
 ## JSON RPC