From 76cfefa4bc7ee627fd11d9849aa76e4f50d4405d Mon Sep 17 00:00:00 2001
From: Joao Grassi <joao.grassi@dynatrace.com>
Date: Fri, 2 Jun 2023 09:37:52 +0200
Subject: [PATCH] Render notes on metric semconv tables (#177)

---
 .../opentelemetry/semconv/templating/markdown/__init__.py | 8 +++++++-
 .../src/tests/data/markdown/metrics_tables/expected.md    | 8 ++++++--
 semantic-conventions/src/tests/data/yaml/metrics.yaml     | 4 ++++
 3 files changed, 17 insertions(+), 3 deletions(-)

diff --git a/semantic-conventions/src/opentelemetry/semconv/templating/markdown/__init__.py b/semantic-conventions/src/opentelemetry/semconv/templating/markdown/__init__.py
index ffb8faf0..cd154ef7 100644
--- a/semantic-conventions/src/opentelemetry/semconv/templating/markdown/__init__.py
+++ b/semantic-conventions/src/opentelemetry/semconv/templating/markdown/__init__.py
@@ -224,8 +224,14 @@ def to_markdown_metric_table(
             "| Name     | Instrument Type | Unit (UCUM) | Description    |\n"
             "| -------- | --------------- | ----------- | -------------- |\n"
         )
+
+        description = semconv.brief
+        if semconv.note:
+            self.render_ctx.add_note(semconv.note)
+            description += f" [{len(self.render_ctx.notes)}]"
+
         output.write(
-            f"| `{semconv.metric_name}` | {instrument} | `{semconv.unit}` | {semconv.brief} |\n"
+            f"| `{semconv.metric_name}` | {instrument} | `{semconv.unit}` | {description} |\n"
         )
         self.to_markdown_notes(output)
 
diff --git a/semantic-conventions/src/tests/data/markdown/metrics_tables/expected.md b/semantic-conventions/src/tests/data/markdown/metrics_tables/expected.md
index 25e956ef..fccac598 100644
--- a/semantic-conventions/src/tests/data/markdown/metrics_tables/expected.md
+++ b/semantic-conventions/src/tests/data/markdown/metrics_tables/expected.md
@@ -4,7 +4,9 @@
 <!-- semconv metric.foo.size(metric_table) -->
 | Name     | Instrument Type | Unit (UCUM) | Description    |
 | -------- | --------------- | ----------- | -------------- |
-| `foo.size` | Histogram | `{bars}` | Measures the size of foo. |
+| `foo.size` | Histogram | `{bars}` | Measures the size of foo. [1] |
+
+**[1]:** Some notes on metric.foo.size
 <!-- endsemconv -->
 
 **Attributes for `foo.size`**
@@ -26,6 +28,8 @@
 <!-- semconv metric.foo.active_eggs -->
 | Attribute  | Type | Description  | Examples  | Requirement Level |
 |---|---|---|---|---|
-| `bar.egg.type` | string | Type of egg. | `chicken`; `emu`; `dragon` | Conditionally Required: if available to instrumentation. |
+| `bar.egg.type` | string | Type of egg. [1] | `chicken`; `emu`; `dragon` | Conditionally Required: if available to instrumentation. |
 | `http.method` | string | HTTP request method. | `GET`; `POST`; `HEAD` | Opt-In |
+
+**[1]:** Some notes on attribute
 <!-- endsemconv -->
diff --git a/semantic-conventions/src/tests/data/yaml/metrics.yaml b/semantic-conventions/src/tests/data/yaml/metrics.yaml
index c3f6740c..5d13f992 100644
--- a/semantic-conventions/src/tests/data/yaml/metrics.yaml
+++ b/semantic-conventions/src/tests/data/yaml/metrics.yaml
@@ -10,6 +10,8 @@ groups:
         type: string
         brief: 'Type of egg.'
         examples: ["chicken", "emu", "dragon"]
+        note: >
+          Some notes on attribute
 
   - id: metric.foo.size
     prefix: foo
@@ -18,6 +20,8 @@ groups:
     brief: "Measures the size of foo."
     instrument: histogram
     unit: "{bars}"
+    note: >
+      Some notes on metric.foo.size
     attributes:
       - ref: http.method
         requirement_level: required