From 9187143130f365dc050d180c6d3d25848e3dc536 Mon Sep 17 00:00:00 2001 From: Alexander Wert Date: Tue, 12 Sep 2023 11:15:11 +0200 Subject: [PATCH] Added `omit_requirement_level` option for markdown table rendering (#190) --- .../semconv/templating/markdown/__init__.py | 36 ++++++++++++++++--- .../omit_requirement_level/expected.md | 9 +++++ .../markdown/omit_requirement_level/http.yaml | 25 +++++++++++++ .../markdown/omit_requirement_level/input.md | 4 +++ .../tests/semconv/templating/test_markdown.py | 3 ++ 5 files changed, 72 insertions(+), 5 deletions(-) create mode 100644 semantic-conventions/src/tests/data/markdown/omit_requirement_level/expected.md create mode 100644 semantic-conventions/src/tests/data/markdown/omit_requirement_level/http.yaml create mode 100644 semantic-conventions/src/tests/data/markdown/omit_requirement_level/input.md diff --git a/semantic-conventions/src/opentelemetry/semconv/templating/markdown/__init__.py b/semantic-conventions/src/opentelemetry/semconv/templating/markdown/__init__.py index 9aec9aaa..630e3c80 100644 --- a/semantic-conventions/src/opentelemetry/semconv/templating/markdown/__init__.py +++ b/semantic-conventions/src/opentelemetry/semconv/templating/markdown/__init__.py @@ -45,6 +45,7 @@ def __init__(self): self.is_full = False self.is_remove_constraint = False self.is_metric_table = False + self.is_omit_requirement_level = False self.group_key = "" self.enums = [] self.notes = [] @@ -70,10 +71,19 @@ class MarkdownRenderer: ) p_end = re.compile("") default_break_conditional_labels = 50 - valid_parameters = ["tag", "full", "remove_constraints", "metric_table"] + valid_parameters = [ + "tag", + "full", + "remove_constraints", + "metric_table", + "omit_requirement_level", + ] prelude = "\n" table_headers = "| Attribute | Type | Description | Examples | Requirement Level |\n|---|---|---|---|---|\n" + table_headers_omitting_req_level = ( + "| Attribute | Type | Description | Examples |\n|---|---|---|---|\n" + ) def __init__( self, md_folder, semconvset: SemanticConventionSet, options=MarkdownOptions() @@ -148,6 +158,16 @@ def to_markdown_attr( examples = "`[" + ", ".join(f"{ex}" for ex in example_list) + "]`" else: examples = "; ".join(f"`{ex}`" for ex in example_list) + + if self.render_ctx.is_omit_requirement_level: + output.write(f"| {name} | {attr_type} | {description} | {examples} |\n") + else: + required = self.derive_requirement_level(attribute) + output.write( + f"| {name} | {attr_type} | {description} | {examples} | {required} |\n" + ) + + def derive_requirement_level(self, attribute: SemanticAttribute): if attribute.requirement_level == RequirementLevel.REQUIRED: required = "Required" elif attribute.requirement_level == RequirementLevel.CONDITIONALLY_REQUIRED: @@ -175,10 +195,13 @@ def to_markdown_attr( # We put the condition in the notes after the table self.render_ctx.add_note(attribute.requirement_level_msg) required = f"Recommended: [{len(self.render_ctx.notes)}]" + return required - output.write( - f"| {name} | {attr_type} | {description} | {examples} | {required} |\n" - ) + def write_table_header(self, output: io.StringIO): + if self.render_ctx.is_omit_requirement_level: + output.write(MarkdownRenderer.table_headers_omitting_req_level) + else: + output.write(MarkdownRenderer.table_headers) def to_markdown_attribute_table( self, semconv: BaseSemanticConvention, output: io.StringIO @@ -200,7 +223,7 @@ def to_markdown_attribute_table( f"No attributes retained for '{semconv.semconv_id}' filtering by '{self.render_ctx.group_key}'" ) if attr_to_print: - output.write(MarkdownRenderer.table_headers) + self.write_table_header(output) for attr in attr_to_print: self.to_markdown_attr(attr, output) attr_sampling_relevant = [ @@ -495,6 +518,9 @@ def _render_group(self, semconv, parameters, output): self.render_ctx.group_key = parameters.get("tag") self.render_ctx.is_full = "full" in parameters self.render_ctx.is_metric_table = "metric_table" in parameters + self.render_ctx.is_omit_requirement_level = ( + "omit_requirement_level" in parameters + ) if self.render_ctx.is_metric_table: self.to_markdown_metric_table(semconv, output) diff --git a/semantic-conventions/src/tests/data/markdown/omit_requirement_level/expected.md b/semantic-conventions/src/tests/data/markdown/omit_requirement_level/expected.md new file mode 100644 index 00000000..501567bc --- /dev/null +++ b/semantic-conventions/src/tests/data/markdown/omit_requirement_level/expected.md @@ -0,0 +1,9 @@ +# Common Attributes + + +| Attribute | Type | Description | Examples | +|---|---|---|---| +| `http.method` | string | HTTP request method. | `GET`; `POST`; `HEAD` | +| `http.url` | string | Full HTTP request URL in the form `scheme://host[:port]/path?query[#fragment]`. Usually the fragment is not transmitted over HTTP, but if it is known, it should be included nevertheless. | `https://www.foo.bar/search?q=OpenTelemetry#SemConv` | +| `http.target` | string | The full request target as passed in a HTTP request line or equivalent. | `/path/12314/?q=ddds#123` | + diff --git a/semantic-conventions/src/tests/data/markdown/omit_requirement_level/http.yaml b/semantic-conventions/src/tests/data/markdown/omit_requirement_level/http.yaml new file mode 100644 index 00000000..0186d65e --- /dev/null +++ b/semantic-conventions/src/tests/data/markdown/omit_requirement_level/http.yaml @@ -0,0 +1,25 @@ +groups: + - id: http + type: span + prefix: http + brief: 'This document defines semantic conventions for HTTP client and server Spans.' + note: > + These conventions can be used for http and https schemes + and various HTTP versions like 1.1, 2 and SPDY. + attributes: + - id: method + type: string + requirement_level: required + sampling_relevant: false + brief: 'HTTP request method.' + examples: ["GET", "POST", "HEAD"] + - id: url + type: string + brief: > + Full HTTP request URL in the form `scheme://host[:port]/path?query[#fragment]`. + Usually the fragment is not transmitted over HTTP, but if it is known, it should be included nevertheless. + examples: ['https://www.foo.bar/search?q=OpenTelemetry#SemConv'] + - id: target + type: string + brief: 'The full request target as passed in a HTTP request line or equivalent.' + examples: ['/path/12314/?q=ddds#123'] diff --git a/semantic-conventions/src/tests/data/markdown/omit_requirement_level/input.md b/semantic-conventions/src/tests/data/markdown/omit_requirement_level/input.md new file mode 100644 index 00000000..5e58cee3 --- /dev/null +++ b/semantic-conventions/src/tests/data/markdown/omit_requirement_level/input.md @@ -0,0 +1,4 @@ +# Common Attributes + + + diff --git a/semantic-conventions/src/tests/semconv/templating/test_markdown.py b/semantic-conventions/src/tests/semconv/templating/test_markdown.py index c35d81bb..b34af20e 100644 --- a/semantic-conventions/src/tests/semconv/templating/test_markdown.py +++ b/semantic-conventions/src/tests/semconv/templating/test_markdown.py @@ -133,6 +133,9 @@ def test_metric_tables(self): ], ) + def test_omit_requirement_level(self): + self.check("markdown/omit_requirement_level/") + def testSamplingRelevant(self): self.check("markdown/sampling_relevant/")