Render notes on metric semconv tables (#177)

open-telemetry · Jun 2, 2023 · 76cfefa · 76cfefa
1 parent 6a8b919
commit 76cfefa
Show file tree

Hide file tree

Showing 3 changed files with 17 additions and 3 deletions.
diff --git 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
@@ -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
@@ -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