From 47615f62ab7ddd9c84edb0fee81b66f1c2467838 Mon Sep 17 00:00:00 2001 From: Joao Grassi Date: Wed, 31 May 2023 16:33:28 +0200 Subject: [PATCH 1/3] Render notes on metric semconv tables --- .../semconv/templating/markdown/__init__.py | 9 ++++++++- .../tests/data/markdown/metrics_tables/expected.md | 12 +++++++++--- .../src/tests/data/yaml/metrics.yaml | 6 ++++++ 3 files changed, 23 insertions(+), 4 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..836b87d3 100644 --- a/semantic-conventions/src/opentelemetry/semconv/templating/markdown/__init__.py +++ b/semantic-conventions/src/opentelemetry/semconv/templating/markdown/__init__.py @@ -224,9 +224,16 @@ 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) def to_markdown_anyof(self, anyof: AnyOf, output: io.StringIO): 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..5a1b7303 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 @@ | 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 **Attributes for `foo.size`** @@ -19,13 +21,17 @@ | Name | Instrument Type | Unit (UCUM) | Description | | -------- | --------------- | ----------- | -------------- | -| `foo.active_eggs` | UpDownCounter | `{cartons}` | Measures how many eggs are currently active. | +| `foo.active_eggs` | UpDownCounter | `{cartons}` | Measures how many eggs are currently active. [1] | + +**[1]:** Some notes on metric.foo.active_eggs **Attributes for `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 diff --git a/semantic-conventions/src/tests/data/yaml/metrics.yaml b/semantic-conventions/src/tests/data/yaml/metrics.yaml index c3f6740c..20fc850b 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 @@ -32,6 +36,8 @@ groups: brief: "Measures how many eggs are currently active." instrument: updowncounter unit: "{cartons}" + note: > + Some notes on metric.foo.active_eggs attributes: - ref: http.method requirement_level: opt_in From 206a2fc0c3b1dc626383dc43a796ee8f76b2e1ef Mon Sep 17 00:00:00 2001 From: Joao Grassi Date: Wed, 31 May 2023 16:39:14 +0200 Subject: [PATCH 2/3] Remove empty space --- .../src/opentelemetry/semconv/templating/markdown/__init__.py | 1 - 1 file changed, 1 deletion(-) diff --git a/semantic-conventions/src/opentelemetry/semconv/templating/markdown/__init__.py b/semantic-conventions/src/opentelemetry/semconv/templating/markdown/__init__.py index 836b87d3..cd154ef7 100644 --- a/semantic-conventions/src/opentelemetry/semconv/templating/markdown/__init__.py +++ b/semantic-conventions/src/opentelemetry/semconv/templating/markdown/__init__.py @@ -233,7 +233,6 @@ def to_markdown_metric_table( output.write( f"| `{semconv.metric_name}` | {instrument} | `{semconv.unit}` | {description} |\n" ) - self.to_markdown_notes(output) def to_markdown_anyof(self, anyof: AnyOf, output: io.StringIO): From 4f3fb3e8c148fe04e0a410b857dc5734893bd8ba Mon Sep 17 00:00:00 2001 From: Joao Grassi Date: Thu, 1 Jun 2023 10:22:45 +0200 Subject: [PATCH 3/3] Leave one metric in test without note --- .../src/tests/data/markdown/metrics_tables/expected.md | 4 +--- semantic-conventions/src/tests/data/yaml/metrics.yaml | 2 -- 2 files changed, 1 insertion(+), 5 deletions(-) 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 5a1b7303..fccac598 100644 --- a/semantic-conventions/src/tests/data/markdown/metrics_tables/expected.md +++ b/semantic-conventions/src/tests/data/markdown/metrics_tables/expected.md @@ -21,9 +21,7 @@ | Name | Instrument Type | Unit (UCUM) | Description | | -------- | --------------- | ----------- | -------------- | -| `foo.active_eggs` | UpDownCounter | `{cartons}` | Measures how many eggs are currently active. [1] | - -**[1]:** Some notes on metric.foo.active_eggs +| `foo.active_eggs` | UpDownCounter | `{cartons}` | Measures how many eggs are currently active. | **Attributes for `foo.active_eggs`** diff --git a/semantic-conventions/src/tests/data/yaml/metrics.yaml b/semantic-conventions/src/tests/data/yaml/metrics.yaml index 20fc850b..5d13f992 100644 --- a/semantic-conventions/src/tests/data/yaml/metrics.yaml +++ b/semantic-conventions/src/tests/data/yaml/metrics.yaml @@ -36,8 +36,6 @@ groups: brief: "Measures how many eggs are currently active." instrument: updowncounter unit: "{cartons}" - note: > - Some notes on metric.foo.active_eggs attributes: - ref: http.method requirement_level: opt_in