From 3ff0eeb828d0e3bcb63b6cf4c548bc98951f0f4d Mon Sep 17 00:00:00 2001 From: Liudmila Molkova Date: Wed, 13 Mar 2024 11:55:45 -0700 Subject: [PATCH] Add stability as a separate column in Markdown tables (#278) --- semantic-conventions/CHANGELOG.md | 2 + semantic-conventions/README.md | 3 + .../src/opentelemetry/semconv/main.py | 30 +-- .../semconv/templating/markdown/__init__.py | 76 +++--- .../semconv/templating/markdown/options.py | 28 +- .../data/markdown/attribute_group/expected.md | 8 +- .../markdown/attribute_templates/expected.md | 12 +- .../data/markdown/deprecated/expected.md | 36 +-- .../tests/data/markdown/deprecated/http.yaml | 2 +- .../tests/data/markdown/deprecated/input.md | 14 +- .../src/tests/data/markdown/empty/expected.md | 253 +----------------- .../src/tests/data/markdown/empty/input.md | 253 +----------------- .../tests/data/markdown/enum_int/expected.md | 44 +-- .../src/tests/data/markdown/event/expected.md | 12 +- .../data/markdown/event_noprefix/expected.md | 6 +- .../data/markdown/event_renamed/expected.md | 6 +- .../data/markdown/example_array/expected.md | 6 +- .../markdown/extend_constraint/expected.md | 150 +++++------ .../data/markdown/extend_constraint/input.md | 146 +++++----- .../markdown/extend_grandparent/expected.md | 22 +- .../tests/data/markdown/include/expected.md | 44 +-- .../data/markdown/metrics_tables/expected.md | 28 +- .../data/markdown/missing_end_tag/input.md | 19 +- .../tests/data/markdown/multiple/expected.md | 40 +-- .../src/tests/data/markdown/multiple/input.md | 6 +- .../data/markdown/multiple_enum/expected.md | 68 ++--- .../omit_requirement_level/expected.md | 10 +- .../data/markdown/parameter_empty/http.md | 10 +- .../data/markdown/parameter_full/expected.md | 44 +-- .../data/markdown/parameter_full/http.md | 10 +- .../parameter_remove_constraint/expected.md | 34 +-- .../parameter_remove_constraint/input.md | 36 +-- .../data/markdown/parameter_tag/expected.md | 34 +-- .../markdown/parameter_tag_empty/expected.md | 86 +++--- .../src/tests/data/markdown/ref/expected.md | 14 +- .../data/markdown/ref_extends/expected.md | 18 +- .../markdown/sampling_relevant/expected.md | 24 +- .../src/tests/data/markdown/scope/expected.md | 6 +- .../tests/data/markdown/single/expected.md | 20 +- .../src/tests/data/markdown/single/input.md | 6 +- .../tests/data/markdown/sorting/expected.md | 16 +- .../data/markdown/spec_version/expected.md | 2 +- .../markdown/stability/all_badges_expected.md | 84 +++--- .../stability/stable_badges_expected.md | 84 +++--- .../data/markdown/wrong_semconv_id/input.md | 6 +- .../tests/semconv/templating/test_markdown.py | 18 +- 46 files changed, 670 insertions(+), 1206 deletions(-) diff --git a/semantic-conventions/CHANGELOG.md b/semantic-conventions/CHANGELOG.md index 786f0f40..b919527b 100644 --- a/semantic-conventions/CHANGELOG.md +++ b/semantic-conventions/CHANGELOG.md @@ -8,6 +8,8 @@ Please update the changelog as part of any significant pull request. ([#267](https://github.com/open-telemetry/build-tools/pull/267)) - Change minimum support python version to 3.10 in setup.cfg and Dockerfile ([#285](https://github.com/open-telemetry/build-tools/pull/285)) +- BREAKING: Add dedicated column for stability to Markdown tables. + ([#278](https://github.com/open-telemetry/build-tools/pull/278)) - BREAKING: Make stability required (also: fix ref and extends, render badges on metrics). ([#272](https://github.com/open-telemetry/build-tools/pull/272)) - BREAKING: Make stability and deprecation independent properties. diff --git a/semantic-conventions/README.md b/semantic-conventions/README.md index e52a12a2..cad1bf5a 100644 --- a/semantic-conventions/README.md +++ b/semantic-conventions/README.md @@ -67,6 +67,9 @@ After `{semantic_convention_id}`, optional parameters enclosed in parentheses ca - `ref`: prints attributes that are referenced from another semantic convention; - `remove_constraint`: does not print additional constraints of the semantic convention. +By default markdown tables are rendered with stability badges (like ![Stable](https://img.shields.io/badge/-stable-lightgreen) or ![Experimental](https://img.shields.io/badge/-experimental-blue)) which can be disabled with `--md-disable-stable-badge`, `--md-disable-experimental-badge`, `--md-disable-deprecated-badge`. +When badges are disabled, the stability column contains plain text representation of stability or deprecation status. + ### Examples These examples assume that a semantic convention with the id `http.server` extends another semantic convention with the id `http`. diff --git a/semantic-conventions/src/opentelemetry/semconv/main.py b/semantic-conventions/src/opentelemetry/semconv/main.py index 461d0c28..c3f9b708 100644 --- a/semantic-conventions/src/opentelemetry/semconv/main.py +++ b/semantic-conventions/src/opentelemetry/semconv/main.py @@ -91,10 +91,9 @@ def main(): def process_markdown(semconv, args): options = MarkdownOptions( check_only=args.md_check, - enable_stable=args.md_stable, - enable_experimental=args.md_experimental, - enable_deprecated=args.md_enable_deprecated, - use_badge=args.md_use_badges, + disable_stable_badge=args.md_disable_stable, + disable_experimental_badge=args.md_disable_experimental, + disable_deprecated_badge=args.md_disable_deprecated, break_count=args.md_break_conditional, exclude_files=exclude_file_list(args.markdown_root, args.exclude), ) @@ -221,31 +220,26 @@ def add_md_parser(subparsers): required=False, ) parser.add_argument( - "--md-use-badges", - help="Use stability badges instead of labels for attributes.", + "--md-disable-stable-badge", + help="Removes badges from attributes marked as stable.", required=False, + default=False, action="store_true", ) parser.add_argument( - "--md-stable", - help="Add labels to attributes marked as stable.", + "--md-disable-experimental-badge", + help="Removes badges from attributes marked as experimental.", required=False, + default=False, action="store_true", ) parser.add_argument( - "--md-experimental", - help="Add labels to attributes marked as experimental.", + "--md-disable-deprecated-badge", + help="Removes badges from attributes marked as deprecated.", required=False, + default=False, action="store_true", ) - parser.add_argument( - "--md-disable-deprecated", - help="Removes deprecated notes of deprecated attributes.", - required=False, - default=True, - dest="md_enable_deprecated", - action="store_false", - ) def add_compat_check_parser(subparsers): diff --git a/semantic-conventions/src/opentelemetry/semconv/templating/markdown/__init__.py b/semantic-conventions/src/opentelemetry/semconv/templating/markdown/__init__.py index 4accf983..360aa29d 100644 --- a/semantic-conventions/src/opentelemetry/semconv/templating/markdown/__init__.py +++ b/semantic-conventions/src/opentelemetry/semconv/templating/markdown/__init__.py @@ -41,8 +41,9 @@ from .utils import VisualDiffer +_OPENTELEMETRY_IO_SPEC_URL = "https://opentelemetry.io/docs/specs/" _REQUIREMENT_LEVEL_URL = ( - "https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/" + _OPENTELEMETRY_IO_SPEC_URL + "semconv/general/attribute-requirement-level/" ) @@ -105,11 +106,12 @@ def __init__( req_level = f"[Requirement Level]({_REQUIREMENT_LEVEL_URL})" self.table_headers = ( - f"| Attribute | Type | Description | Examples | {req_level} |" - "\n|---|---|---|---|---|\n" + f"| Attribute | Type | Description | Examples | {req_level} | Stability |" + "\n|---|---|---|---|---|---|\n" ) self.table_headers_omitting_req_level = ( - "| Attribute | Type | Description | Examples |\n|---|---|---|---|\n" + "| Attribute | Type | Description | Examples | Stability |" + "\n|---|---|---|---|---|\n" ) def to_markdown_attr( @@ -126,10 +128,7 @@ def to_markdown_attr( if isinstance(attribute.attr_type, EnumAttributeType) else AttributeType.get_instantiated_type(attribute.attr_type) ) - description = ( - self._description_with_badge(attribute.stability, attribute.deprecated) - + attribute.brief - ) + description = attribute.brief if attribute.note: self.render_ctx.add_note(attribute.note) description += f" [{len(self.render_ctx.notes)}]" @@ -156,12 +155,15 @@ def to_markdown_attr( else: examples = "; ".join(f"`{ex}`" for ex in example_list) + stability = self._render_stability(attribute) if self.render_ctx.is_omit_requirement_level: - output.write(f"| {name} | {attr_type} | {description} | {examples} |\n") + output.write( + f"| {name} | {attr_type} | {description} | {examples} | {stability} |\n" + ) else: required = self.derive_requirement_level(attribute) output.write( - f"| {name} | {attr_type} | {description} | {examples} | {required} |\n" + f"| {name} | {attr_type} | {description} | {examples} | {required} | {stability} |\n" ) def derive_requirement_level(self, attribute: SemanticAttribute): @@ -175,7 +177,7 @@ def derive_requirement_level(self, attribute: SemanticAttribute): self.render_ctx.add_note(attribute.requirement_level_msg) required = f"`Conditionally Required` [{len(self.render_ctx.notes)}]" elif attribute.requirement_level == RequirementLevel.OPT_IN: - required = "Opt-In" + required = "`Opt-In`" else: # attribute.requirement_level == Required.RECOMMENDED or None # check if there are any notes if ( @@ -240,21 +242,20 @@ def to_markdown_metric_table( instrument = MetricSemanticConvention.canonical_instrument_name_by_yaml_name[ semconv.instrument ] + output.write( - "| Name | Instrument Type | Unit (UCUM) | Description |\n" - "| -------- | --------------- | ----------- | -------------- |\n" + "| Name | Instrument Type | Unit (UCUM) | Description | Stability |\n" + "| -------- | --------------- | ----------- | -------------- | --------- |\n" ) - description = ( - self._description_with_badge(semconv.stability, semconv.deprecated) - + semconv.brief - ) + description = semconv.brief if semconv.note: self.render_ctx.add_note(semconv.note) description += f" [{len(self.render_ctx.notes)}]" + stability = self._render_stability(semconv) output.write( - f"| `{semconv.metric_name}` | {instrument} | `{semconv.unit}` | {description} |\n" + f"| `{semconv.metric_name}` | {instrument} | `{semconv.unit}` | {description} | {stability} |\n" ) self.to_markdown_notes(output) @@ -328,20 +329,18 @@ def to_markdown_enum(self, output: io.StringIO): else: output.write("MUST be one of the following:") output.write("\n\n") - output.write("| Value | Description |\n|---|---|") + output.write("| Value | Description | Stability |\n|---|---|---|") member: EnumMember counter = 1 notes = [] for member in enum.members: - description = ( - self._description_with_badge(member.stability, member.deprecated) - + member.brief - ) + description = member.brief if member.note: description += f" [{counter}]" counter += 1 notes.append(member.note) - output.write(f"\n| `{member.value}` | {description} |") + stability = self._render_stability(member) + output.write(f"\n| `{member.value}` | {description} | {stability} |") counter = 1 if not notes: output.write("\n") @@ -537,20 +536,15 @@ def _render_group(self, semconv, parameters, output): output.write("") - def _description_with_badge(self, stability: StabilityLevel, deprecated: str): - description = "" - if deprecated and self.options.enable_deprecated: - if "deprecated" in deprecated.lower(): - description = f"**{deprecated}**
" - else: - deprecated_msg = self.options.deprecated_md_snippet().format(deprecated) - description = f"{deprecated_msg}
" - elif stability == StabilityLevel.STABLE and self.options.enable_stable: - description = f"{self.options.stable_md_snippet()}
" - elif ( - stability == StabilityLevel.EXPERIMENTAL - and self.options.enable_experimental - ): - description = f"{self.options.experimental_md_snippet()}
" - - return description + def _render_stability( + self, + item: typing.Union[SemanticAttribute | BaseSemanticConvention | EnumMember], + ): + if item.deprecated: + return self.options.deprecated_md_snippet(item.deprecated) + if item.stability == StabilityLevel.STABLE: + return self.options.stable_md_snippet() + if item.stability == StabilityLevel.EXPERIMENTAL: + return self.options.experimental_md_snippet() + + raise ValueError(f"Unknown stability level {item.stability}") diff --git a/semantic-conventions/src/opentelemetry/semconv/templating/markdown/options.py b/semantic-conventions/src/opentelemetry/semconv/templating/markdown/options.py index 419ef8f1..af0cfce5 100644 --- a/semantic-conventions/src/opentelemetry/semconv/templating/markdown/options.py +++ b/semantic-conventions/src/opentelemetry/semconv/templating/markdown/options.py @@ -19,24 +19,24 @@ @dataclass() class MarkdownOptions: check_only: bool = False - enable_stable: bool = False - enable_experimental: bool = False - enable_deprecated: bool = True - use_badge: bool = False + disable_stable_badge: bool = False + disable_experimental_badge: bool = False + disable_deprecated_badge: bool = False break_count: int = 50 exclude_files: List[str] = field(default_factory=list) def stable_md_snippet(self): - if self.use_badge: - return "![Stable](https://img.shields.io/badge/-stable-lightgreen)" - return "**Stable**" + if self.disable_stable_badge: + return "Stable" + return "![Stable](https://img.shields.io/badge/-stable-lightgreen)" def experimental_md_snippet(self): - if self.use_badge: - return "![Experimental](https://img.shields.io/badge/-experimental-blue)" - return "**Experimental**" + if self.disable_experimental_badge: + return "Experimental" + return "![Experimental](https://img.shields.io/badge/-experimental-blue)" - def deprecated_md_snippet(self): - if self.use_badge: - return "![Deprecated](https://img.shields.io/badge/-deprecated-red)" - return "**Deprecated: {}**" + def deprecated_md_snippet(self, deprecated_note: str): + if self.disable_deprecated_badge: + return f"Deprecated: {deprecated_note}" + + return f"![Deprecated](https://img.shields.io/badge/-deprecated-red)
{deprecated_note}" diff --git a/semantic-conventions/src/tests/data/markdown/attribute_group/expected.md b/semantic-conventions/src/tests/data/markdown/attribute_group/expected.md index 51fe266d..09b038e6 100644 --- a/semantic-conventions/src/tests/data/markdown/attribute_group/expected.md +++ b/semantic-conventions/src/tests/data/markdown/attribute_group/expected.md @@ -1,8 +1,8 @@ # Attribute Group Example -| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | -|---|---|---|---|---| -| `foo.bar` | string | Attribute 1 | `baz` | `Recommended` if available | -| `foo.qux` | int | Attribute 2 | `42` | `Conditionally Required` if available | +| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | +|---|---|---|---|---|---| +| `foo.bar` | string | Attribute 1 | `baz` | `Recommended` if available | Experimental | +| `foo.qux` | int | Attribute 2 | `42` | `Conditionally Required` if available | Experimental | diff --git a/semantic-conventions/src/tests/data/markdown/attribute_templates/expected.md b/semantic-conventions/src/tests/data/markdown/attribute_templates/expected.md index 9a8be2b5..41599ce8 100644 --- a/semantic-conventions/src/tests/data/markdown/attribute_templates/expected.md +++ b/semantic-conventions/src/tests/data/markdown/attribute_templates/expected.md @@ -1,10 +1,10 @@ # Custom HTTP Semantic Conventions -| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | -|---|---|---|---|---| -| `custom_http.request.header.` | string[] | HTTP request headers, `` being the normalized HTTP Header name (lowercase, with - characters replaced by _), the value being the header values. | ``http.request.header.content_type=["application/json"]`` | `Recommended` | -| `custom_http.request.method` | string | HTTP request method. | `GET`; `POST`; `HEAD` | `Required` | -| `general.some_general_attribute.` | string | This is a general attribute. | ``some_general_attribute.some_key="abc"`` | `Recommended` | -| `referenced_http.request.referenced.header.` | string[] | This is a referenced attribute. | ``http.request.header.content_type=["application/json"]`` | `Recommended` | +| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | +|---|---|---|---|---|---| +| `custom_http.request.header.` | string[] | HTTP request headers, `` being the normalized HTTP Header name (lowercase, with - characters replaced by _), the value being the header values. | ``http.request.header.content_type=["application/json"]`` | `Recommended` | Experimental | +| `custom_http.request.method` | string | HTTP request method. | `GET`; `POST`; `HEAD` | `Required` | Experimental | +| `general.some_general_attribute.` | string | This is a general attribute. | ``some_general_attribute.some_key="abc"`` | `Recommended` | Experimental | +| `referenced_http.request.referenced.header.` | string[] | This is a referenced attribute. | ``http.request.header.content_type=["application/json"]`` | `Recommended` | Experimental | diff --git a/semantic-conventions/src/tests/data/markdown/deprecated/expected.md b/semantic-conventions/src/tests/data/markdown/deprecated/expected.md index 964e9d05..aac840f0 100644 --- a/semantic-conventions/src/tests/data/markdown/deprecated/expected.md +++ b/semantic-conventions/src/tests/data/markdown/deprecated/expected.md @@ -2,29 +2,29 @@ -| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | -|---|---|---|---|---| -| `http.flavor` | string | **Deprecated. Use attribute `flavor_new` instead.**
Kind of HTTP protocol used [1] | `1.0` | `Recommended` | -| `http.host` | string | The value of the [HTTP host header](https://tools.ietf.org/html/rfc7230#section-5.4). When the header is empty or not present, this attribute should be the same. | `www.example.org` | `Recommended` | -| `http.method` | string | HTTP request method. | `GET`; `POST`; `HEAD` | `Required` | -| `http.scheme` | string | The URI scheme identifying the used protocol. | `http`; `https` | `Recommended` | -| `http.status_code` | int | [HTTP response status code](https://tools.ietf.org/html/rfc7231#section-6). | `200` | `Conditionally Required` if and only if one was received/sent | -| `http.status_text` | string | **Deprecated: Use attribute `status_description` instead.**
[HTTP reason phrase](https://tools.ietf.org/html/rfc7230#section-3.1.2). | `OK` | `Recommended` | -| `http.target` | string | The full request target as passed in a HTTP request line or equivalent. | `/path/12314/?q=ddds#123` | `Recommended` | -| `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` | `Recommended` | -| `http.user_agent` | string | Value of the [HTTP User-Agent](https://tools.ietf.org/html/rfc7231#section-5.5.3) header sent by the client. | `CERN-LineMode/2.15 libwww/2.17b3` | `Recommended` | +| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | +|---|---|---|---|---|---| +| `http.flavor` | string | Kind of HTTP protocol used [1] | `1.0` | `Recommended` | Deprecated: Use attribute `flavor_new` instead. | +| `http.host` | string | The value of the [HTTP host header](https://tools.ietf.org/html/rfc7230#section-5.4). When the header is empty or not present, this attribute should be the same. | `www.example.org` | `Recommended` | Experimental | +| `http.method` | string | HTTP request method. | `GET`; `POST`; `HEAD` | `Required` | Experimental | +| `http.scheme` | string | The URI scheme identifying the used protocol. | `http`; `https` | `Recommended` | Experimental | +| `http.status_code` | int | [HTTP response status code](https://tools.ietf.org/html/rfc7231#section-6). | `200` | `Conditionally Required` if and only if one was received/sent | Experimental | +| `http.status_text` | string | [HTTP reason phrase](https://tools.ietf.org/html/rfc7230#section-3.1.2). | `OK` | `Recommended` | Deprecated: Use attribute `status_description` instead. | +| `http.target` | string | The full request target as passed in a HTTP request line or equivalent. | `/path/12314/?q=ddds#123` | `Recommended` | Experimental | +| `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` | `Recommended` | Experimental | +| `http.user_agent` | string | Value of the [HTTP User-Agent](https://tools.ietf.org/html/rfc7231#section-5.5.3) header sent by the client. | `CERN-LineMode/2.15 libwww/2.17b3` | `Recommended` | Experimental | **[1]:** If `net.transport` is not specified, it can be assumed to be `IP.TCP` except if `http.flavor` is `QUIC`, in which case `IP.UDP` is assumed. `http.flavor` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. -| Value | Description | -|---|---| -| `1.0` | HTTP 1.0 | -| `1.1` | HTTP 1.1 | -| `2.0` | HTTP 2 | -| `SPDY` | SPDY protocol. | -| `QUIC` | QUIC protocol. | +| Value | Description | Stability | +|---|---|---| +| `1.0` | HTTP 1.0 | Experimental | +| `1.1` | HTTP 1.1 | Experimental | +| `2.0` | HTTP 2 | Experimental | +| `SPDY` | SPDY protocol. | Experimental | +| `QUIC` | QUIC protocol. | Experimental | It is recommended to also use the general [network attributes][], especially `net.peer.ip`. If `net.transport` is not specified, it can be assumed to be `IP.TCP` except if `http.flavor` is `QUIC`, in which case `IP.UDP` is assumed. diff --git a/semantic-conventions/src/tests/data/markdown/deprecated/http.yaml b/semantic-conventions/src/tests/data/markdown/deprecated/http.yaml index e0061b1d..22cce227 100644 --- a/semantic-conventions/src/tests/data/markdown/deprecated/http.yaml +++ b/semantic-conventions/src/tests/data/markdown/deprecated/http.yaml @@ -79,7 +79,7 @@ groups: brief: 'QUIC protocol.' stability: experimental brief: 'Kind of HTTP protocol used' - deprecated: Deprecated. Use attribute `flavor_new` instead. + deprecated: Use attribute `flavor_new` instead. note: > If `net.transport` is not specified, it can be assumed to be `IP.TCP` except if `http.flavor` is `QUIC`, in which case `IP.UDP` is assumed. diff --git a/semantic-conventions/src/tests/data/markdown/deprecated/input.md b/semantic-conventions/src/tests/data/markdown/deprecated/input.md index 4e6e41b1..af396848 100644 --- a/semantic-conventions/src/tests/data/markdown/deprecated/input.md +++ b/semantic-conventions/src/tests/data/markdown/deprecated/input.md @@ -2,19 +2,7 @@ - -| Attribute name | Notes and examples | `Required`? | -| :------------- | :----------------------------------------------------------- | --------- | -| `http.method` | HTTP request method. E.g. `"GET"`. | `Required` | -| `http.url` | 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. | Defined later. | -| `http.target` | The full request target as passed in a [HTTP request line][] or equivalent, e.g. `"/path/12314/?q=ddds#123"`. | Defined later. | -| `http.host` | The value of the [HTTP host header][]. When the header is empty or not present, this attribute should be the same. | Defined later. | -| `http.scheme` | The URI scheme identifying the used protocol: `"http"` or `"https"` | Defined later. | -| `http.status_code` | [HTTP response status code][]. E.g. `200` (integer) | `Conditionally Required` if and only if one was received/sent. | -| `http.status_text` | [HTTP reason phrase][]. E.g. `"OK"` | `Recommended` | -| `http.flavor` | Kind of HTTP protocol used: `"1.0"`, `"1.1"`, `"2"`, `"SPDY"` or `"QUIC"`. | No | -| `http.user_agent` | Value of the HTTP [User-Agent][] header sent by the client. | `Recommended` | - +this will be removed It is recommended to also use the general [network attributes][], especially `net.peer.ip`. If `net.transport` is not specified, it can be assumed to be `IP.TCP` except if `http.flavor` is `QUIC`, in which case `IP.UDP` is assumed. diff --git a/semantic-conventions/src/tests/data/markdown/empty/expected.md b/semantic-conventions/src/tests/data/markdown/empty/expected.md index 0b063ae1..fa8888c3 100644 --- a/semantic-conventions/src/tests/data/markdown/empty/expected.md +++ b/semantic-conventions/src/tests/data/markdown/empty/expected.md @@ -1,252 +1 @@ -# Semantic conventions for HTTP spans - -This document defines semantic conventions for HTTP client and server Spans. -They can be used for http and https schemes -and various HTTP versions like 1.1, 2 and SPDY. - - - - - -- [Name](#name) -- [Status](#status) -- [Common Attributes](#common-attributes) -- [HTTP client](#http-client) -- [HTTP server](#http-server) - * [HTTP server definitions](#http-server-definitions) - * [HTTP Server semantic conventions](#http-server-semantic-conventions) -- [HTTP client-server example](#http-client-server-example) - - - -## Name - -HTTP spans MUST follow the overall [guidelines for span names](../api.md#span). -Many REST APIs encode parameters into URI path, e.g. `/api/users/123` where `123` -is a user id, which creates high cardinality value space not suitable for span -names. In case of HTTP servers, these endpoints are often mapped by the server -frameworks to more concise _HTTP routes_, e.g. `/api/users/{user_id}`, which are -recommended as the low cardinality span names. However, the same approach usually -does not work for HTTP client spans, especially when instrumentation is provided -by a lower-level middleware that is not aware of the specifics of how the URIs -are formed. Therefore, HTTP client spans SHOULD be using conservative, low -cardinality names formed from the available parameters of an HTTP request, -such as `"HTTP {METHOD_NAME}"`. Instrumentation MUST NOT default to using URI -path as span name, but MAY provide hooks to allow custom logic to override the -default span name. - -## Status - -Implementations MUST set the [span status](../api.md#status) if the HTTP communication failed -or an HTTP error status code is returned (e.g. above 3xx). - -In the case of an HTTP redirect, the request should normally be considered successful, -unless the client aborts following redirects due to hitting some limit (redirect loop). -If following a (chain of) redirect(s) successfully, the status should be set according to the result of the final HTTP request. - -Don't set the span status description if the reason can be inferred from `http.status_code` and `http.status_text`. - -| HTTP code | Span status code | -|-------------------------|-----------------------| -| 100...299 | `Ok` | -| 3xx redirect codes | `DeadlineExceeded` in case of loop (see above) [1], otherwise `Ok` | -| 401 Unauthorized ⚠ | `Unauthenticated` ⚠ (Unauthorized actually means unauthenticated according to [RFC 7235][rfc-unauthorized]) | -| 403 Forbidden | `PermissionDenied` | -| 404 Not Found | `NotFound` | -| 429 Too Many Requests | `ResourceExhausted` | -| Other 4xx code | `InvalidArgument` [1] | -| 501 Not Implemented | `Unimplemented` | -| 503 Service Unavailable | `Unavailable` | -| 504 Gateway Timeout | `DeadlineExceeded` | -| Other 5xx code | `Internal` [1] | -| Any status code the client fails to interpret (e.g., 093 or 573) | `Unknown` | - -Note that the items marked with [1] are different from the mapping defined in the [OpenCensus semantic conventions][oc-http-status]. - -[oc-http-status]: https://github.com/census-instrumentation/opencensus-specs/blob/master/trace/HTTP.md#mapping-from-http-status-codes-to-trace-status-codes -[rfc-unauthorized]: https://tools.ietf.org/html/rfc7235#section-3.1 - -## Common Attributes - - - -| Attribute name | Notes and examples | `Required`? | -| :------------- | :----------------------------------------------------------- | --------- | -| `http.method` | HTTP request method. E.g. `"GET"`. | `Required` | -| `http.url` | 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. | Defined later. | -| `http.target` | The full request target as passed in a [HTTP request line][] or equivalent, e.g. `"/path/12314/?q=ddds#123"`. | Defined later. | -| `http.host` | The value of the [HTTP host header][]. When the header is empty or not present, this attribute should be the same. | Defined later. | -| `http.scheme` | The URI scheme identifying the used protocol: `"http"` or `"https"` | Defined later. | -| `http.status_code` | [HTTP response status code][]. E.g. `200` (integer) | `Conditionally Required` if and only if one was received/sent. | -| `http.status_text` | [HTTP reason phrase][]. E.g. `"OK"` | `Recommended` | -| `http.flavor` | Kind of HTTP protocol used: `"1.0"`, `"1.1"`, `"2"`, `"SPDY"` or `"QUIC"`. | Opt-In | -| `http.user_agent` | Value of the HTTP [User-Agent][] header sent by the client. | `Recommended` | - -It is recommended to also use the general [network attributes][], especially `net.peer.ip`. If `net.transport` is not specified, it can be assumed to be `IP.TCP` except if `http.flavor` is `QUIC`, in which case `IP.UDP` is assumed. - -[network attributes]: span-general.md#general-network-connection-attributes -[HTTP response status code]: https://tools.ietf.org/html/rfc7231#section-6 -[HTTP reason phrase]: https://tools.ietf.org/html/rfc7230#section-3.1.2 -[User-Agent]: https://tools.ietf.org/html/rfc7231#section-5.5.3 - -## HTTP client - -This span type represents an outbound HTTP request. - -For an HTTP client span, `SpanKind` MUST be `Client`. - -If set, `http.url` must be the originally requested URL, -before any HTTP-redirects that may happen when executing the request. - -One of the following sets of attributes is required (in order of usual preference unless for a particular web client/framework it is known that some other set is preferable for some reason; all strings must be non-empty): - -* `http.url` -* `http.scheme`, `http.host`, `http.target` -* `http.scheme`, `net.peer.name`, `net.peer.port`, `http.target` -* `http.scheme`, `net.peer.ip`, `net.peer.port`, `http.target` - -Note that in some cases `http.host` might be different -from the `net.peer.name` -used to look up the `net.peer.ip` that is actually connected to. -In that case it is strongly recommended to set the `net.peer.name` attribute in addition to `http.host`. - -For status, the following special cases have canonical error codes assigned: - -| Client error | Trace status code | -|-----------------------------|--------------------| -| DNS resolution failed | `Unknown` | -| Request cancelled by caller | `Cancelled` | -| URL cannot be parsed | `InvalidArgument` | -| Request timed out | `DeadlineExceeded` | - -This is not meant to be an exhaustive list -but if there is no clear mapping for some error conditions, -instrumentation developers are encouraged to use `Unknown` -and open a PR or issue in the specification repository. - -## HTTP server - -To understand the attributes defined in this section, it is helpful to read the "Definitions" subsection. - -### HTTP server definitions - -This section gives a short summary of some concepts -in web server configuration and web app deployment -that are relevant to tracing. - -Usually, on a physical host, reachable by one or multiple IP addresses, a single HTTP listener process runs. -If multiple processes are running, they must listen on distinct TCP/UDP ports so that the OS can route incoming TCP/UDP packets to the right one. - -Within a single server process, there can be multiple **virtual hosts**. -The [HTTP host header][] (in combination with a port number) is normally used to determine to which of them to route incoming HTTP requests. - -The host header value that matches some virtual host is called the virtual hosts's **server name**. If there are multiple aliases for the virtual host, one of them (often the first one listed in the configuration) is called the **primary server name**. See for example, the Apache [`ServerName`][ap-sn] or NGINX [`server_name`][nx-sn] directive or the CGI specification on `SERVER_NAME` ([RFC 3875][rfc-servername]). -In practice the HTTP host header is often ignored when just a single virtual host is configured for the IP. - -Within a single virtual host, some servers support the concepts of an **HTTP application** -(for example in Java, the Servlet JSR defines an application as -"a collection of servlets, HTML pages, classes, and other resources that make up a complete application on a Web server" --- SRV.9 in [JSR 53][]; -in a deployment of a Python application to Apache, the application would be the [PEP 3333][] conformant callable that is configured using the -[`WSGIScriptAlias` directive][modwsgisetup] of `mod_wsgi`). - -An application can be "mounted" under some **application root** -(also know as *[context root][]* *[context prefix][]*, or *[document base][]*) -which is a fixed path prefix of the URL that determines to which application a request is routed -(e.g., the server could be configured to route all requests that go to an URL path starting with `/webshop/` -at a particular virtual host -to the `com.example.webshop` web application). - -Some servers allow to bind the same HTTP application to multiple `(virtual host, application root)` pairs. - -> TODO: Find way to trace HTTP application and application root ([opentelemetry/opentelementry-specification#335][]) - -[PEP 3333]: https://www.python.org/dev/peps/pep-3333/ -[modwsgisetup]: https://modwsgi.readthedocs.io/en/develop/user-guides/quick-configuration-guide.html -[context root]: https://docs.jboss.org/jbossas/guides/webguide/r2/en/html/ch06.html -[context prefix]: https://marc.info/?l=apache-cvs&m=130928191414740 -[document base]: http://tomcat.apache.org/tomcat-5.5-doc/config/context.html -[rfc-servername]: https://tools.ietf.org/html/rfc3875#section-4.1.14 -[ap-sn]: https://httpd.apache.org/docs/2.4/mod/core.html#servername -[nx-sn]: http://nginx.org/en/docs/http/ngx_http_core_module.html#server_name -[JSR 53]: https://jcp.org/aboutJava/communityprocess/maintenance/jsr053/index2.html -[opentelemetry/opentelementry-specification#335]: https://github.com/open-telemetry/opentelemetry-specification/issues/335 - -### HTTP Server semantic conventions - -This span type represents an inbound HTTP request. - -For an HTTP server span, `SpanKind` MUST be `Server`. - -Given an inbound request for a route (e.g. `"/users/:userID?"`) the `name` attribute of the span SHOULD be set to this route. -If the route does not include the application root, it SHOULD be prepended to the span name. - -If the route cannot be determined, the `name` attribute MUST be set as defined in the general semantic conventions for HTTP. - -| Attribute name | Notes and examples | `Required`? | -| :------------- | :----------------------------------------------------------- | --------- | -| `http.server_name` | The primary server name of the matched virtual host. This should be obtained via configuration. If no such configuration can be obtained, this attribute MUST NOT be set ( `net.host.name` should be used instead). | [1] | -| `http.route` | The matched route (path template). (TODO: Define whether to prepend application root) E.g. `"/users/:userID?"`. | `Recommended` | -| `http.client_ip` | The IP address of the original client behind all proxies, if known (e.g. from [X-Forwarded-For][]). Note that this is not necessarily the same as `net.peer.ip`, which would identify the network-level peer, which may be a proxy. | `Recommended` | - -[HTTP request line]: https://tools.ietf.org/html/rfc7230#section-3.1.1 -[HTTP host header]: https://tools.ietf.org/html/rfc7230#section-5.4 -[X-Forwarded-For]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/X-Forwarded-For - -**[1]**: `http.url` is usually not readily available on the server side but would have to be assembled in a cumbersome and sometimes lossy process from other information (see e.g. ). -It is thus preferred to supply the raw data that *is* available. -Namely, one of the following sets is required (in order of usual preference unless for a particular web server/framework it is known that some other set is preferable for some reason; all strings must be non-empty): - -* `http.scheme`, `http.host`, `http.target` -* `http.scheme`, `http.server_name`, `net.host.port`, `http.target` -* `http.scheme`, `net.host.name`, `net.host.port`, `http.target` -* `http.url` - -Of course, more than the required attributes can be supplied, but this is recommended only if they cannot be inferred from the sent ones. -For example, `http.server_name` has shown great value in practice, as bogus HTTP Host headers occur often in the wild. - -It is strongly recommended to set `http.server_name` to allow associating requests with some logical server entity. - -## HTTP client-server example - -As an example, if a browser request for `https://example.com:8080/webshop/articles/4?s=1` is invoked from a host with IP 192.0.2.4, we may have the following Span on the client side: - -Span name: `/webshop/articles/4` (NOTE: This is subject to change, see [open-telemetry/opentelemetry-specification#270][].) - -[open-telemetry/opentelemetry-specification#270]: https://github.com/open-telemetry/opentelemetry-specification/issues/270 - -| Attribute name | Value | -| :----------------- | :-------------------------------------------------------| -| `http.method` | `"GET"` | -| `http.flavor` | `"1.1"` | -| `http.url` | `"https://example.com:8080/webshop/articles/4?s=1"` | -| `net.peer.ip` | `"192.0.2.5"` | -| `http.status_code` | `200` | -| `http.status_text` | `"OK"` | - -The corresponding server Span may look like this: - -Span name: `/webshop/articles/:article_id`. - -| Attribute name | Value | -| :----------------- | :---------------------------------------------- | -| `http.method` | `"GET"` | -| `http.flavor` | `"1.1"` | -| `http.target` | `"/webshop/articles/4?s=1"` | -| `http.host` | `"example.com:8080"` | -| `http.server_name` | `"example.com"` | -| `host.port` | `8080` | -| `http.scheme` | `"https"` | -| `http.route` | `"/webshop/articles/:article_id"` | -| `http.status_code` | `200` | -| `http.status_text` | `"OK"` | -| `http.client_ip` | `"192.0.2.4"` | -| `net.peer.ip` | `"192.0.2.5"` (the client goes through a proxy) | -| `http.user_agent` | `"Mozilla/5.0 (Windows NT 10.0; Win64; x64; rv:72.0) Gecko/20100101 Firefox/72.0"` | - -Note that following the recommendations above, `http.url` is not set in the above example. -If set, it would be -`"https://example.com:8080/webshop/articles/4?s=1"` -but due to `http.scheme`, `http.host` and `http.target` being set, it would be redundant. -As explained above, these separate values are preferred but if for some reason the URL is available but the other values are not, -URL can replace `http.scheme`, `http.host` and `http.target`. +This is an arbitrary markdown file that does not have any semantic conventions anchors. diff --git a/semantic-conventions/src/tests/data/markdown/empty/input.md b/semantic-conventions/src/tests/data/markdown/empty/input.md index 0b063ae1..fa8888c3 100644 --- a/semantic-conventions/src/tests/data/markdown/empty/input.md +++ b/semantic-conventions/src/tests/data/markdown/empty/input.md @@ -1,252 +1 @@ -# Semantic conventions for HTTP spans - -This document defines semantic conventions for HTTP client and server Spans. -They can be used for http and https schemes -and various HTTP versions like 1.1, 2 and SPDY. - - - - - -- [Name](#name) -- [Status](#status) -- [Common Attributes](#common-attributes) -- [HTTP client](#http-client) -- [HTTP server](#http-server) - * [HTTP server definitions](#http-server-definitions) - * [HTTP Server semantic conventions](#http-server-semantic-conventions) -- [HTTP client-server example](#http-client-server-example) - - - -## Name - -HTTP spans MUST follow the overall [guidelines for span names](../api.md#span). -Many REST APIs encode parameters into URI path, e.g. `/api/users/123` where `123` -is a user id, which creates high cardinality value space not suitable for span -names. In case of HTTP servers, these endpoints are often mapped by the server -frameworks to more concise _HTTP routes_, e.g. `/api/users/{user_id}`, which are -recommended as the low cardinality span names. However, the same approach usually -does not work for HTTP client spans, especially when instrumentation is provided -by a lower-level middleware that is not aware of the specifics of how the URIs -are formed. Therefore, HTTP client spans SHOULD be using conservative, low -cardinality names formed from the available parameters of an HTTP request, -such as `"HTTP {METHOD_NAME}"`. Instrumentation MUST NOT default to using URI -path as span name, but MAY provide hooks to allow custom logic to override the -default span name. - -## Status - -Implementations MUST set the [span status](../api.md#status) if the HTTP communication failed -or an HTTP error status code is returned (e.g. above 3xx). - -In the case of an HTTP redirect, the request should normally be considered successful, -unless the client aborts following redirects due to hitting some limit (redirect loop). -If following a (chain of) redirect(s) successfully, the status should be set according to the result of the final HTTP request. - -Don't set the span status description if the reason can be inferred from `http.status_code` and `http.status_text`. - -| HTTP code | Span status code | -|-------------------------|-----------------------| -| 100...299 | `Ok` | -| 3xx redirect codes | `DeadlineExceeded` in case of loop (see above) [1], otherwise `Ok` | -| 401 Unauthorized ⚠ | `Unauthenticated` ⚠ (Unauthorized actually means unauthenticated according to [RFC 7235][rfc-unauthorized]) | -| 403 Forbidden | `PermissionDenied` | -| 404 Not Found | `NotFound` | -| 429 Too Many Requests | `ResourceExhausted` | -| Other 4xx code | `InvalidArgument` [1] | -| 501 Not Implemented | `Unimplemented` | -| 503 Service Unavailable | `Unavailable` | -| 504 Gateway Timeout | `DeadlineExceeded` | -| Other 5xx code | `Internal` [1] | -| Any status code the client fails to interpret (e.g., 093 or 573) | `Unknown` | - -Note that the items marked with [1] are different from the mapping defined in the [OpenCensus semantic conventions][oc-http-status]. - -[oc-http-status]: https://github.com/census-instrumentation/opencensus-specs/blob/master/trace/HTTP.md#mapping-from-http-status-codes-to-trace-status-codes -[rfc-unauthorized]: https://tools.ietf.org/html/rfc7235#section-3.1 - -## Common Attributes - - - -| Attribute name | Notes and examples | `Required`? | -| :------------- | :----------------------------------------------------------- | --------- | -| `http.method` | HTTP request method. E.g. `"GET"`. | `Required` | -| `http.url` | 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. | Defined later. | -| `http.target` | The full request target as passed in a [HTTP request line][] or equivalent, e.g. `"/path/12314/?q=ddds#123"`. | Defined later. | -| `http.host` | The value of the [HTTP host header][]. When the header is empty or not present, this attribute should be the same. | Defined later. | -| `http.scheme` | The URI scheme identifying the used protocol: `"http"` or `"https"` | Defined later. | -| `http.status_code` | [HTTP response status code][]. E.g. `200` (integer) | `Conditionally Required` if and only if one was received/sent. | -| `http.status_text` | [HTTP reason phrase][]. E.g. `"OK"` | `Recommended` | -| `http.flavor` | Kind of HTTP protocol used: `"1.0"`, `"1.1"`, `"2"`, `"SPDY"` or `"QUIC"`. | Opt-In | -| `http.user_agent` | Value of the HTTP [User-Agent][] header sent by the client. | `Recommended` | - -It is recommended to also use the general [network attributes][], especially `net.peer.ip`. If `net.transport` is not specified, it can be assumed to be `IP.TCP` except if `http.flavor` is `QUIC`, in which case `IP.UDP` is assumed. - -[network attributes]: span-general.md#general-network-connection-attributes -[HTTP response status code]: https://tools.ietf.org/html/rfc7231#section-6 -[HTTP reason phrase]: https://tools.ietf.org/html/rfc7230#section-3.1.2 -[User-Agent]: https://tools.ietf.org/html/rfc7231#section-5.5.3 - -## HTTP client - -This span type represents an outbound HTTP request. - -For an HTTP client span, `SpanKind` MUST be `Client`. - -If set, `http.url` must be the originally requested URL, -before any HTTP-redirects that may happen when executing the request. - -One of the following sets of attributes is required (in order of usual preference unless for a particular web client/framework it is known that some other set is preferable for some reason; all strings must be non-empty): - -* `http.url` -* `http.scheme`, `http.host`, `http.target` -* `http.scheme`, `net.peer.name`, `net.peer.port`, `http.target` -* `http.scheme`, `net.peer.ip`, `net.peer.port`, `http.target` - -Note that in some cases `http.host` might be different -from the `net.peer.name` -used to look up the `net.peer.ip` that is actually connected to. -In that case it is strongly recommended to set the `net.peer.name` attribute in addition to `http.host`. - -For status, the following special cases have canonical error codes assigned: - -| Client error | Trace status code | -|-----------------------------|--------------------| -| DNS resolution failed | `Unknown` | -| Request cancelled by caller | `Cancelled` | -| URL cannot be parsed | `InvalidArgument` | -| Request timed out | `DeadlineExceeded` | - -This is not meant to be an exhaustive list -but if there is no clear mapping for some error conditions, -instrumentation developers are encouraged to use `Unknown` -and open a PR or issue in the specification repository. - -## HTTP server - -To understand the attributes defined in this section, it is helpful to read the "Definitions" subsection. - -### HTTP server definitions - -This section gives a short summary of some concepts -in web server configuration and web app deployment -that are relevant to tracing. - -Usually, on a physical host, reachable by one or multiple IP addresses, a single HTTP listener process runs. -If multiple processes are running, they must listen on distinct TCP/UDP ports so that the OS can route incoming TCP/UDP packets to the right one. - -Within a single server process, there can be multiple **virtual hosts**. -The [HTTP host header][] (in combination with a port number) is normally used to determine to which of them to route incoming HTTP requests. - -The host header value that matches some virtual host is called the virtual hosts's **server name**. If there are multiple aliases for the virtual host, one of them (often the first one listed in the configuration) is called the **primary server name**. See for example, the Apache [`ServerName`][ap-sn] or NGINX [`server_name`][nx-sn] directive or the CGI specification on `SERVER_NAME` ([RFC 3875][rfc-servername]). -In practice the HTTP host header is often ignored when just a single virtual host is configured for the IP. - -Within a single virtual host, some servers support the concepts of an **HTTP application** -(for example in Java, the Servlet JSR defines an application as -"a collection of servlets, HTML pages, classes, and other resources that make up a complete application on a Web server" --- SRV.9 in [JSR 53][]; -in a deployment of a Python application to Apache, the application would be the [PEP 3333][] conformant callable that is configured using the -[`WSGIScriptAlias` directive][modwsgisetup] of `mod_wsgi`). - -An application can be "mounted" under some **application root** -(also know as *[context root][]* *[context prefix][]*, or *[document base][]*) -which is a fixed path prefix of the URL that determines to which application a request is routed -(e.g., the server could be configured to route all requests that go to an URL path starting with `/webshop/` -at a particular virtual host -to the `com.example.webshop` web application). - -Some servers allow to bind the same HTTP application to multiple `(virtual host, application root)` pairs. - -> TODO: Find way to trace HTTP application and application root ([opentelemetry/opentelementry-specification#335][]) - -[PEP 3333]: https://www.python.org/dev/peps/pep-3333/ -[modwsgisetup]: https://modwsgi.readthedocs.io/en/develop/user-guides/quick-configuration-guide.html -[context root]: https://docs.jboss.org/jbossas/guides/webguide/r2/en/html/ch06.html -[context prefix]: https://marc.info/?l=apache-cvs&m=130928191414740 -[document base]: http://tomcat.apache.org/tomcat-5.5-doc/config/context.html -[rfc-servername]: https://tools.ietf.org/html/rfc3875#section-4.1.14 -[ap-sn]: https://httpd.apache.org/docs/2.4/mod/core.html#servername -[nx-sn]: http://nginx.org/en/docs/http/ngx_http_core_module.html#server_name -[JSR 53]: https://jcp.org/aboutJava/communityprocess/maintenance/jsr053/index2.html -[opentelemetry/opentelementry-specification#335]: https://github.com/open-telemetry/opentelemetry-specification/issues/335 - -### HTTP Server semantic conventions - -This span type represents an inbound HTTP request. - -For an HTTP server span, `SpanKind` MUST be `Server`. - -Given an inbound request for a route (e.g. `"/users/:userID?"`) the `name` attribute of the span SHOULD be set to this route. -If the route does not include the application root, it SHOULD be prepended to the span name. - -If the route cannot be determined, the `name` attribute MUST be set as defined in the general semantic conventions for HTTP. - -| Attribute name | Notes and examples | `Required`? | -| :------------- | :----------------------------------------------------------- | --------- | -| `http.server_name` | The primary server name of the matched virtual host. This should be obtained via configuration. If no such configuration can be obtained, this attribute MUST NOT be set ( `net.host.name` should be used instead). | [1] | -| `http.route` | The matched route (path template). (TODO: Define whether to prepend application root) E.g. `"/users/:userID?"`. | `Recommended` | -| `http.client_ip` | The IP address of the original client behind all proxies, if known (e.g. from [X-Forwarded-For][]). Note that this is not necessarily the same as `net.peer.ip`, which would identify the network-level peer, which may be a proxy. | `Recommended` | - -[HTTP request line]: https://tools.ietf.org/html/rfc7230#section-3.1.1 -[HTTP host header]: https://tools.ietf.org/html/rfc7230#section-5.4 -[X-Forwarded-For]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/X-Forwarded-For - -**[1]**: `http.url` is usually not readily available on the server side but would have to be assembled in a cumbersome and sometimes lossy process from other information (see e.g. ). -It is thus preferred to supply the raw data that *is* available. -Namely, one of the following sets is required (in order of usual preference unless for a particular web server/framework it is known that some other set is preferable for some reason; all strings must be non-empty): - -* `http.scheme`, `http.host`, `http.target` -* `http.scheme`, `http.server_name`, `net.host.port`, `http.target` -* `http.scheme`, `net.host.name`, `net.host.port`, `http.target` -* `http.url` - -Of course, more than the required attributes can be supplied, but this is recommended only if they cannot be inferred from the sent ones. -For example, `http.server_name` has shown great value in practice, as bogus HTTP Host headers occur often in the wild. - -It is strongly recommended to set `http.server_name` to allow associating requests with some logical server entity. - -## HTTP client-server example - -As an example, if a browser request for `https://example.com:8080/webshop/articles/4?s=1` is invoked from a host with IP 192.0.2.4, we may have the following Span on the client side: - -Span name: `/webshop/articles/4` (NOTE: This is subject to change, see [open-telemetry/opentelemetry-specification#270][].) - -[open-telemetry/opentelemetry-specification#270]: https://github.com/open-telemetry/opentelemetry-specification/issues/270 - -| Attribute name | Value | -| :----------------- | :-------------------------------------------------------| -| `http.method` | `"GET"` | -| `http.flavor` | `"1.1"` | -| `http.url` | `"https://example.com:8080/webshop/articles/4?s=1"` | -| `net.peer.ip` | `"192.0.2.5"` | -| `http.status_code` | `200` | -| `http.status_text` | `"OK"` | - -The corresponding server Span may look like this: - -Span name: `/webshop/articles/:article_id`. - -| Attribute name | Value | -| :----------------- | :---------------------------------------------- | -| `http.method` | `"GET"` | -| `http.flavor` | `"1.1"` | -| `http.target` | `"/webshop/articles/4?s=1"` | -| `http.host` | `"example.com:8080"` | -| `http.server_name` | `"example.com"` | -| `host.port` | `8080` | -| `http.scheme` | `"https"` | -| `http.route` | `"/webshop/articles/:article_id"` | -| `http.status_code` | `200` | -| `http.status_text` | `"OK"` | -| `http.client_ip` | `"192.0.2.4"` | -| `net.peer.ip` | `"192.0.2.5"` (the client goes through a proxy) | -| `http.user_agent` | `"Mozilla/5.0 (Windows NT 10.0; Win64; x64; rv:72.0) Gecko/20100101 Firefox/72.0"` | - -Note that following the recommendations above, `http.url` is not set in the above example. -If set, it would be -`"https://example.com:8080/webshop/articles/4?s=1"` -but due to `http.scheme`, `http.host` and `http.target` being set, it would be redundant. -As explained above, these separate values are preferred but if for some reason the URL is available but the other values are not, -URL can replace `http.scheme`, `http.host` and `http.target`. +This is an arbitrary markdown file that does not have any semantic conventions anchors. diff --git a/semantic-conventions/src/tests/data/markdown/enum_int/expected.md b/semantic-conventions/src/tests/data/markdown/enum_int/expected.md index e8361396..c481f605 100644 --- a/semantic-conventions/src/tests/data/markdown/enum_int/expected.md +++ b/semantic-conventions/src/tests/data/markdown/enum_int/expected.md @@ -1,29 +1,29 @@ # RPC.GRPC with int enum -| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | -|---|---|---|---|---| -| `rpc.grpc.status_code` | int | The [numeric status code](https://github.com/grpc/grpc/blob/v1.33.2/doc/statuscodes.md) of the gRPC request. | `0`; `1`; `16` | `Required` | +| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | +|---|---|---|---|---|---| +| `rpc.grpc.status_code` | int | The [numeric status code](https://github.com/grpc/grpc/blob/v1.33.2/doc/statuscodes.md) of the gRPC request. | `0`; `1`; `16` | `Required` | Experimental | `rpc.grpc.status_code` MUST be one of the following: -| Value | Description | -|---|---| -| `0` | ok | -| `1` | cancelled | -| `2` | unknown | -| `3` | invalid_argument | -| `4` | deadline_exceeded | -| `5` | not_found | -| `6` | already_exists | -| `7` | permission_denied | -| `8` | resource_exhausted | -| `9` | failed_precondition | -| `10` | aborted | -| `11` | out_of_range | -| `12` | unimplemented | -| `13` | internal | -| `14` | unavailable | -| `15` | data_loss | -| `16` | unauthenticated | +| Value | Description | Stability | +|---|---|---| +| `0` | ok | Experimental | +| `1` | cancelled | Experimental | +| `2` | unknown | Experimental | +| `3` | invalid_argument | Experimental | +| `4` | deadline_exceeded | Experimental | +| `5` | not_found | Experimental | +| `6` | already_exists | Experimental | +| `7` | permission_denied | Experimental | +| `8` | resource_exhausted | Experimental | +| `9` | failed_precondition | Experimental | +| `10` | aborted | Experimental | +| `11` | out_of_range | Experimental | +| `12` | unimplemented | Experimental | +| `13` | internal | Experimental | +| `14` | unavailable | Experimental | +| `15` | data_loss | Experimental | +| `16` | unauthenticated | Experimental | diff --git a/semantic-conventions/src/tests/data/markdown/event/expected.md b/semantic-conventions/src/tests/data/markdown/event/expected.md index ed3e9f0e..a4606a7d 100644 --- a/semantic-conventions/src/tests/data/markdown/event/expected.md +++ b/semantic-conventions/src/tests/data/markdown/event/expected.md @@ -3,12 +3,12 @@ The event name MUST be `exception`. -| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | -|---|---|---|---|---| -| `exception.escaped` | boolean | SHOULD be set to true if the exception event is recorded at a point where it is known that the exception is escaping the scope of the span. [1] | | `Recommended` | -| `exception.message` | string | The exception message. | `Division by zero`; `Can't convert 'int' object to str implicitly` | See below | -| `exception.stacktrace` | string | A stacktrace. | `Exception in thread "main" java.lang.RuntimeException: Test exception\n at com.example.GenerateTrace.methodB(GenerateTrace.java:13)\n at com.example.GenerateTrace.methodA(GenerateTrace.java:9)\n at com.example.GenerateTrace.main(GenerateTrace.java:5)` | `Recommended` | -| `exception.type` | string | The type of the exception. | `java.net.ConnectException`; `OSError` | See below | +| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | +|---|---|---|---|---|---| +| `exception.escaped` | boolean | SHOULD be set to true if the exception event is recorded at a point where it is known that the exception is escaping the scope of the span. [1] | | `Recommended` | Experimental | +| `exception.message` | string | The exception message. | `Division by zero`; `Can't convert 'int' object to str implicitly` | See below | Experimental | +| `exception.stacktrace` | string | A stacktrace. | `Exception in thread "main" java.lang.RuntimeException: Test exception\n at com.example.GenerateTrace.methodB(GenerateTrace.java:13)\n at com.example.GenerateTrace.methodA(GenerateTrace.java:9)\n at com.example.GenerateTrace.main(GenerateTrace.java:5)` | `Recommended` | Experimental | +| `exception.type` | string | The type of the exception. | `java.net.ConnectException`; `OSError` | See below | Experimental | **[1]:** An exception is considered to have escaped. diff --git a/semantic-conventions/src/tests/data/markdown/event_noprefix/expected.md b/semantic-conventions/src/tests/data/markdown/event_noprefix/expected.md index 1cb8695e..dc6cfa03 100644 --- a/semantic-conventions/src/tests/data/markdown/event_noprefix/expected.md +++ b/semantic-conventions/src/tests/data/markdown/event_noprefix/expected.md @@ -3,7 +3,7 @@ The event name MUST be `myname`. -| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | -|---|---|---|---|---| -| `attr` | boolean | attrbrief | | `Recommended` | +| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | +|---|---|---|---|---|---| +| `attr` | boolean | attrbrief | | `Recommended` | Experimental | diff --git a/semantic-conventions/src/tests/data/markdown/event_renamed/expected.md b/semantic-conventions/src/tests/data/markdown/event_renamed/expected.md index dd574537..9529c603 100644 --- a/semantic-conventions/src/tests/data/markdown/event_renamed/expected.md +++ b/semantic-conventions/src/tests/data/markdown/event_renamed/expected.md @@ -3,7 +3,7 @@ The event name MUST be `myname`. -| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | -|---|---|---|---|---| -| `myprefix.attr` | boolean | attrbrief | | `Recommended` | +| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | +|---|---|---|---|---|---| +| `myprefix.attr` | boolean | attrbrief | | `Recommended` | Experimental | diff --git a/semantic-conventions/src/tests/data/markdown/example_array/expected.md b/semantic-conventions/src/tests/data/markdown/example_array/expected.md index 4c1609f2..042075d5 100644 --- a/semantic-conventions/src/tests/data/markdown/example_array/expected.md +++ b/semantic-conventions/src/tests/data/markdown/example_array/expected.md @@ -1,7 +1,7 @@ # Common Attributes -| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | -|---|---|---|---|---| -| `http.method` | string[] | HTTP request method. | `[GET, POST, HEAD]` | `Required` | +| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | +|---|---|---|---|---|---| +| `http.method` | string[] | HTTP request method. | `[GET, POST, HEAD]` | `Required` | Experimental | \ No newline at end of file diff --git a/semantic-conventions/src/tests/data/markdown/extend_constraint/expected.md b/semantic-conventions/src/tests/data/markdown/extend_constraint/expected.md index 414f25f8..efa11282 100644 --- a/semantic-conventions/src/tests/data/markdown/extend_constraint/expected.md +++ b/semantic-conventions/src/tests/data/markdown/extend_constraint/expected.md @@ -34,15 +34,15 @@ These attributes will usually be the same for all operations performed over the Some database systems may allow a connection to switch to a different `db.user`, for example, and other database systems may not even have the concept of a connection at all. -| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | -|---|---|---|---|---| -| `db.connection_string` | string | The connection string used to connect to the database. [1] | `Server=(localdb)\v11.0;Integrated Security=true;` | `Recommended` | -| `db.system` | string | An identifier for the database management system (DBMS) product being used. See below for a list of well-known identifiers. | `other_sql` | `Required` | -| `db.user` | string | Username for accessing the database. | `readonly_user`; `reporting_user` | `Recommended` | -| `net.peer.ip` | string | Remote address of the peer (dotted decimal for IPv4 or [RFC5952](https://tools.ietf.org/html/rfc5952) for IPv6) | `127.0.0.1` | See below | -| `net.peer.name` | string | Remote hostname or similar, see note below. | `example.com` | See below | -| `net.peer.port` | int | Remote port number. | `80`; `8080`; `443` | `Conditionally Required` [2] | -| `net.transport` | string | Transport protocol used. See note below. | `IP.TCP` | `Conditionally Required` [3] | +| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | +|---|---|---|---|---|---| +| `db.connection_string` | string | The connection string used to connect to the database. [1] | `Server=(localdb)\v11.0;Integrated Security=true;` | `Recommended` | Experimental | +| `db.system` | string | An identifier for the database management system (DBMS) product being used. See below for a list of well-known identifiers. | `other_sql` | `Required` | Experimental | +| `db.user` | string | Username for accessing the database. | `readonly_user`; `reporting_user` | `Recommended` | Experimental | +| `net.peer.ip` | string | Remote address of the peer (dotted decimal for IPv4 or [RFC5952](https://tools.ietf.org/html/rfc5952) for IPv6) | `127.0.0.1` | See below | Experimental | +| `net.peer.name` | string | Remote hostname or similar, see note below. | `example.com` | See below | Experimental | +| `net.peer.port` | int | Remote port number. | `80`; `8080`; `443` | `Conditionally Required` [2] | Experimental | +| `net.transport` | string | Transport protocol used. See note below. | `IP.TCP` | `Conditionally Required` [3] | Experimental | **[1]:** It is recommended to remove embedded credentials. @@ -57,51 +57,51 @@ Some database systems may allow a connection to switch to a different `db.user`, `db.system` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. -| Value | Description | -|---|---| -| `other_sql` | Some other SQL database. Fallback only. See notes. | -| `mssql` | Microsoft SQL Server | -| `mysql` | MySQL | -| `oracle` | Oracle Database | -| `db2` | IBM Db2 | -| `postgresql` | PostgreSQL | -| `redshift` | Amazon Redshift | -| `hive` | Apache Hive | -| `cloudscape` | Cloudscape | -| `hsqlsb` | HyperSQL DataBase | -| `progress` | Progress Database | -| `maxdb` | SAP MaxDB | -| `hanadb` | SAP HANA | -| `ingres` | Ingres | -| `firstsql` | FirstSQL | -| `edb` | EnterpriseDB | -| `cache` | InterSystems Caché | -| `adabas` | Adabas (Adaptable Database System) | -| `firebird` | Firebird | -| `derby` | Apache Derby | -| `filemaker` | FileMaker | -| `informix` | Informix | -| `instantdb` | InstantDB | -| `interbase` | InterBase | -| `mariadb` | MariaDB | -| `netezza` | Netezza | -| `pervasive` | Pervasive PSQL | -| `pointbase` | PointBase | -| `sqlite` | SQLite | -| `sybase` | Sybase | -| `teradata` | Teradata | -| `vertica` | Vertica | -| `h2` | H2 | -| `coldfusion` | ColdFusion IMQ | -| `cassandra` | Apache Cassandra | -| `hbase` | Apache HBase | -| `mongodb` | MongoDB | -| `redis` | Redis | -| `couchbase` | Couchbase | -| `couchdb` | CouchDB | -| `cosmosdb` | Microsoft Azure Cosmos DB | -| `dynamodb` | Amazon DynamoDB | -| `neo4j` | Neo4j | +| Value | Description | Stability | +|---|---|---| +| `other_sql` | Some other SQL database. Fallback only. See notes. | Experimental | +| `mssql` | Microsoft SQL Server | Experimental | +| `mysql` | MySQL | Experimental | +| `oracle` | Oracle Database | Experimental | +| `db2` | IBM Db2 | Experimental | +| `postgresql` | PostgreSQL | Experimental | +| `redshift` | Amazon Redshift | Experimental | +| `hive` | Apache Hive | Experimental | +| `cloudscape` | Cloudscape | Experimental | +| `hsqlsb` | HyperSQL DataBase | Experimental | +| `progress` | Progress Database | Experimental | +| `maxdb` | SAP MaxDB | Experimental | +| `hanadb` | SAP HANA | Experimental | +| `ingres` | Ingres | Experimental | +| `firstsql` | FirstSQL | Experimental | +| `edb` | EnterpriseDB | Experimental | +| `cache` | InterSystems Caché | Experimental | +| `adabas` | Adabas (Adaptable Database System) | Experimental | +| `firebird` | Firebird | Experimental | +| `derby` | Apache Derby | Experimental | +| `filemaker` | FileMaker | Experimental | +| `informix` | Informix | Experimental | +| `instantdb` | InstantDB | Experimental | +| `interbase` | InterBase | Experimental | +| `mariadb` | MariaDB | Experimental | +| `netezza` | Netezza | Experimental | +| `pervasive` | Pervasive PSQL | Experimental | +| `pointbase` | PointBase | Experimental | +| `sqlite` | SQLite | Experimental | +| `sybase` | Sybase | Experimental | +| `teradata` | Teradata | Experimental | +| `vertica` | Vertica | Experimental | +| `h2` | H2 | Experimental | +| `coldfusion` | ColdFusion IMQ | Experimental | +| `cassandra` | Apache Cassandra | Experimental | +| `hbase` | Apache HBase | Experimental | +| `mongodb` | MongoDB | Experimental | +| `redis` | Redis | Experimental | +| `couchbase` | Couchbase | Experimental | +| `couchdb` | CouchDB | Experimental | +| `cosmosdb` | Microsoft Azure Cosmos DB | Experimental | +| `dynamodb` | Amazon DynamoDB | Experimental | +| `neo4j` | Neo4j | Experimental | ### Notes on `db.system` @@ -125,10 +125,10 @@ When additional attributes are added that only apply to a specific DBMS, its ide ### Connection-level attributes for specific technologies -| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | -|---|---|---|---|---| -| `db.jdbc.driver_classname` | string | The fully-qualified class name of the JDBC driver used to connect. | `org.postgresql.Driver`; `com.microsoft.sqlserver.jdbc.SQLServerDriver` | `Recommended` | -| `db.mssql.instance_name` | string | The Microsoft SQL Server [instance name](https://docs.microsoft.com/en-us/sql/connect/jdbc/building-the-connection-url?view=sql-server-ver15) connecting to. This name is used to determine the port of a named instance. [1] | `MSSQLSERVER` | `Recommended` | +| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | +|---|---|---|---|---|---| +| `db.jdbc.driver_classname` | string | The fully-qualified class name of the JDBC driver used to connect. | `org.postgresql.Driver`; `com.microsoft.sqlserver.jdbc.SQLServerDriver` | `Recommended` | Experimental | +| `db.mssql.instance_name` | string | The Microsoft SQL Server [instance name](https://docs.microsoft.com/en-us/sql/connect/jdbc/building-the-connection-url?view=sql-server-ver15) connecting to. This name is used to determine the port of a named instance. [1] | `MSSQLSERVER` | `Recommended` | Experimental | **[1]:** If setting a `db.mssql.instance_name`, `net.peer.port` is no longer required (but still recommended if non-standard). @@ -139,11 +139,11 @@ These attributes may be different for each operation performed, even if the same Usually only one `db.name` will be used per connection though. -| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | -|---|---|---|---|---| -| `db.name` | string | If no tech-specific attribute is defined, this attribute is used to report the name of the database being accessed. For commands that switch the database, this should be set to the target database (even if the command fails). [1] | `customers`; `main` | `Conditionally Required` [2] | -| `db.operation` | string | The name of the operation being executed, e.g. the [MongoDB command name](https://docs.mongodb.com/manual/reference/command/#database-operations) such as `findAndModify`. [3] | `findAndModify`; `HMSET` | `Conditionally Required` if `db.statement` is not applicable. | -| `db.statement` | string | The database statement being executed. [4] | `SELECT * FROM wuser_table`; `SET mykey "WuValue"` | `Conditionally Required` if applicable. | +| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | +|---|---|---|---|---|---| +| `db.name` | string | If no tech-specific attribute is defined, this attribute is used to report the name of the database being accessed. For commands that switch the database, this should be set to the target database (even if the command fails). [1] | `customers`; `main` | `Conditionally Required` [2] | Experimental | +| `db.operation` | string | The name of the operation being executed, e.g. the [MongoDB command name](https://docs.mongodb.com/manual/reference/command/#database-operations) such as `findAndModify`. [3] | `findAndModify`; `HMSET` | `Conditionally Required` if `db.statement` is not applicable. | Experimental | +| `db.statement` | string | The database statement being executed. [4] | `SELECT * FROM wuser_table`; `SET mykey "WuValue"` | `Conditionally Required` if applicable. | Experimental | **[1]:** In some SQL databases, the database name to be used is called "schema name". @@ -169,33 +169,33 @@ For example, when retrieving a document, `db.operation` would be set to (literal #### Cassandra -| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | -|---|---|---|---|---| -| `db.cassandra.keyspace` | string | The name of the keyspace being accessed. To be used instead of the generic `db.name` attribute. | `mykeyspace` | `Required` | +| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | +|---|---|---|---|---|---| +| `db.cassandra.keyspace` | string | The name of the keyspace being accessed. To be used instead of the generic `db.name` attribute. | `mykeyspace` | `Required` | Experimental | #### Apache HBase -| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | -|---|---|---|---|---| -| `db.hbase.namespace` | string | The [HBase namespace](https://hbase.apache.org/book.html#_namespace) being accessed. To be used instead of the generic `db.name` attribute. | `default` | `Required` | +| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | +|---|---|---|---|---|---| +| `db.hbase.namespace` | string | The [HBase namespace](https://hbase.apache.org/book.html#_namespace) being accessed. To be used instead of the generic `db.name` attribute. | `default` | `Required` | Experimental | #### Redis -| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | -|---|---|---|---|---| -| `db.redis.database_index` | int | The index of the database being accessed as used in the [`SELECT` command](https://redis.io/commands/select), provided as an integer. To be used instead of the generic `db.name` attribute. | `0`; `1`; `15` | `Conditionally Required` if other than the default database (`0`). | +| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | +|---|---|---|---|---|---| +| `db.redis.database_index` | int | The index of the database being accessed as used in the [`SELECT` command](https://redis.io/commands/select), provided as an integer. To be used instead of the generic `db.name` attribute. | `0`; `1`; `15` | `Conditionally Required` if other than the default database (`0`). | Experimental | #### MongoDB -| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | -|---|---|---|---|---| -| `db.mongodb.collection` | string | The collection being accessed within the database stated in `db.name`. | `customers`; `products` | `Required` | +| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | +|---|---|---|---|---|---| +| `db.mongodb.collection` | string | The collection being accessed within the database stated in `db.name`. | `customers`; `products` | `Required` | Experimental | ## Examples diff --git a/semantic-conventions/src/tests/data/markdown/extend_constraint/input.md b/semantic-conventions/src/tests/data/markdown/extend_constraint/input.md index 28049197..ce07dbab 100644 --- a/semantic-conventions/src/tests/data/markdown/extend_constraint/input.md +++ b/semantic-conventions/src/tests/data/markdown/extend_constraint/input.md @@ -34,15 +34,15 @@ These attributes will usually be the same for all operations performed over the Some database systems may allow a connection to switch to a different `db.user`, for example, and other database systems may not even have the concept of a connection at all. -| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | -|---|---|---|---|---| -| `db.system` | string | An identifier for the database management system (DBMS) product being used. See below for a list of well-known identifiers. | `other_sql` | `Required` | -| `db.connection_string` | string | The connection string used to connect to the database. [1] | `Server=(localdb)\v11.0;Integrated Security=true;` | `Recommended` | -| `db.user` | string | Username for accessing the database. | `readonly_user`
`reporting_user` | `Recommended` | +| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | +|---|---|---|---|---|---| +| `db.system` | string | An identifier for the database management system (DBMS) product being used. See below for a list of well-known identifiers. | `other_sql` | `Required` | Experimental | +| `db.connection_string` | string | The connection string used to connect to the database. [1] | `Server=(localdb)\v11.0;Integrated Security=true;` | `Recommended` | Experimental | +| `db.user` | string | Username for accessing the database. | `readonly_user`
`reporting_user` | `Recommended` | Experimental | | `net.peer.ip` | string | Remote address of the peer (dotted decimal for IPv4 or [RFC5952](https://tools.ietf.org/html/rfc5952) for IPv6) | `127.0.0.1` | Conditional
See below. | -| `net.peer.name` | string | Remote hostname or similar, see note below. | `example.com` | Conditional
See below. | -| `net.peer.port` | int | Remote port number. | `80`
`8080`
`443` | `Conditionally Required` [2] | -| `net.transport` | string enum | Transport protocol used. See note below. | `IP.TCP` | `Conditionally Required` [3] | +| `net.peer.name` | string | Remote hostname or similar, see note below. | `example.com` | Conditional
See below. | Experimental | +| `net.peer.port` | int | Remote port number. | `80`
`8080`
`443` | `Conditionally Required` [2] | Experimental | +| `net.transport` | string enum | Transport protocol used. See note below. | `IP.TCP` | `Conditionally Required` [3] | Experimental | **[1]:** It is recommended to remove embedded credentials. @@ -57,51 +57,51 @@ At least one of the following is required: `db.system` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. -| Value | Description | -|---|---| -| `other_sql` | Some other SQL database. Fallback only. See notes. | -| `mssql` | Microsoft SQL Server | -| `mysql` | MySQL | -| `oracle` | Oracle Database | -| `db2` | IBM Db2 | -| `postgresql` | PostgreSQL | -| `redshift` | Amazon Redshift | -| `hive` | Apache Hive | -| `cloudscape` | Cloudscape | -| `hsqlsb` | HyperSQL DataBase | -| `progress` | Progress Database | -| `maxdb` | SAP MaxDB | -| `hanadb` | SAP HANA | -| `ingres` | Ingres | -| `firstsql` | FirstSQL | -| `edb` | EnterpriseDB | -| `cache` | InterSystems Caché | -| `adabas` | Adabas (Adaptable Database System) | -| `firebird` | Firebird | -| `derby` | Apache Derby | -| `filemaker` | FileMaker | -| `informix` | Informix | -| `instantdb` | InstantDB | -| `interbase` | InterBase | -| `mariadb` | MariaDB | -| `netezza` | Netezza | -| `pervasive` | Pervasive PSQL | -| `pointbase` | PointBase | -| `sqlite` | SQLite | -| `sybase` | Sybase | -| `teradata` | Teradata | -| `vertica` | Vertica | -| `h2` | H2 | -| `coldfusion` | ColdFusion IMQ | -| `cassandra` | Apache Cassandra | -| `hbase` | Apache HBase | -| `mongodb` | MongoDB | -| `redis` | Redis | -| `couchbase` | Couchbase | -| `couchdb` | CouchDB | -| `cosmosdb` | Microsoft Azure Cosmos DB | -| `dynamodb` | Amazon DynamoDB | -| `neo4j` | Neo4j | +| Value | Description | Stability | +|---|---|---| +| `other_sql` | Some other SQL database. Fallback only. See notes. | Experimental | +| `mssql` | Microsoft SQL Server | Experimental | +| `mysql` | MySQL | Experimental | +| `oracle` | Oracle Database | Experimental | +| `db2` | IBM Db2 | Experimental | +| `postgresql` | PostgreSQL | Experimental | +| `redshift` | Amazon Redshift | Experimental | +| `hive` | Apache Hive | Experimental | +| `cloudscape` | Cloudscape | Experimental | +| `hsqlsb` | HyperSQL DataBase | Experimental | +| `progress` | Progress Database | Experimental | +| `maxdb` | SAP MaxDB | Experimental | +| `hanadb` | SAP HANA | Experimental | +| `ingres` | Ingres | Experimental | +| `firstsql` | FirstSQL | Experimental | +| `edb` | EnterpriseDB | Experimental | +| `cache` | InterSystems Caché | Experimental | +| `adabas` | Adabas (Adaptable Database System) | Experimental | +| `firebird` | Firebird | Experimental | +| `derby` | Apache Derby | Experimental | +| `filemaker` | FileMaker | Experimental | +| `informix` | Informix | Experimental | +| `instantdb` | InstantDB | Experimental | +| `interbase` | InterBase | Experimental | +| `mariadb` | MariaDB | Experimental | +| `netezza` | Netezza | Experimental | +| `pervasive` | Pervasive PSQL | Experimental | +| `pointbase` | PointBase | Experimental | +| `sqlite` | SQLite | Experimental | +| `sybase` | Sybase | Experimental | +| `teradata` | Teradata | Experimental | +| `vertica` | Vertica | Experimental | +| `h2` | H2 | Experimental | +| `coldfusion` | ColdFusion IMQ | Experimental | +| `cassandra` | Apache Cassandra | Experimental | +| `hbase` | Apache HBase | Experimental | +| `mongodb` | MongoDB | Experimental | +| `redis` | Redis | Experimental | +| `couchbase` | Couchbase | Experimental | +| `couchdb` | CouchDB | Experimental | +| `cosmosdb` | Microsoft Azure Cosmos DB | Experimental | +| `dynamodb` | Amazon DynamoDB | Experimental | +| `neo4j` | Neo4j | Experimental | ### Notes on `db.system` @@ -125,10 +125,10 @@ When additional attributes are added that only apply to a specific DBMS, its ide ### Connection-level attributes for specific technologies -| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | -|---|---|---|---|---| -| `db.mssql.instance_name` | string | The Microsoft SQL Server [instance name](https://docs.microsoft.com/en-us/sql/connect/jdbc/building-the-connection-url?view=sql-server-ver15) connecting to. This name is used to determine the port of a named instance. [1] | `MSSQLSERVER` | `Recommended` | -| `db.jdbc.driver_classname` | string | The fully-qualified class name of the JDBC driver used to connect. | `org.postgresql.Driver`
`com.microsoft.sqlserver.jdbc.SQLServerDriver` | `Recommended` | +| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | +|---|---|---|---|---|---| +| `db.mssql.instance_name` | string | The Microsoft SQL Server [instance name](https://docs.microsoft.com/en-us/sql/connect/jdbc/building-the-connection-url?view=sql-server-ver15) connecting to. This name is used to determine the port of a named instance. [1] | `MSSQLSERVER` | `Recommended` | Experimental | +| `db.jdbc.driver_classname` | string | The fully-qualified class name of the JDBC driver used to connect. | `org.postgresql.Driver`
`com.microsoft.sqlserver.jdbc.SQLServerDriver` | `Recommended` | Experimental | **[1]:** If setting a `db.mssql.instance_name`, `net.peer.port` is no longer required (but still recommended if non-standard). @@ -139,11 +139,11 @@ These attributes may be different for each operation performed, even if the same Usually only one `db.name` will be used per connection though. -| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | -|---|---|---|---|---| -| `db.name` | string | If no tech-specific attribute is defined, this attribute is used to report the name of the database being accessed. For commands that switch the database, this should be set to the target database (even if the command fails). [1] | `customers`
`main` | `Conditionally Required` [2] | -| `db.statement` | string | The database statement being executed. [3] | `SELECT * FROM wuser_table`
`SET mykey "WuValue"` | Conditional
Conditionally Required if applicable. | -| `db.operation` | string | The name of the operation being executed, e.g. the [MongoDB command name](https://docs.mongodb.com/manual/reference/command/#database-operations) such as `findAndModify`. [4] | `findAndModify`
`HMSET` | Conditional
Conditionally Required if `db.statement` is not applicable. | +| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | +|---|---|---|---|---|---| +| `db.name` | string | If no tech-specific attribute is defined, this attribute is used to report the name of the database being accessed. For commands that switch the database, this should be set to the target database (even if the command fails). [1] | `customers`
`main` | `Conditionally Required` [2] | Experimental | +| `db.statement` | string | The database statement being executed. [3] | `SELECT * FROM wuser_table`
`SET mykey "WuValue"` | Conditional
Conditionally Required if applicable. | Experimental | +| `db.operation` | string | The name of the operation being executed, e.g. the [MongoDB command name](https://docs.mongodb.com/manual/reference/command/#database-operations) such as `findAndModify`. [4] | `findAndModify`
`HMSET` | Conditional
Conditionally Required if `db.statement` is not applicable. | Experimental | **[1]:** In some SQL databases, the database name to be used is called "schema name". @@ -169,24 +169,24 @@ For example, when retrieving a document, `db.operation` would be set to (literal #### Cassandra -| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | -|---|---|---|---|---| -| `db.cassandra.keyspace` | string | The name of the keyspace being accessed. To be used instead of the generic `db.name` attribute. | `mykeyspace` | `Required` | +| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | +|---|---|---|---|---|---| +| `db.cassandra.keyspace` | string | The name of the keyspace being accessed. To be used instead of the generic `db.name` attribute. | `mykeyspace` | `Required` | Experimental | #### Apache HBase -| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | -|---|---|---|---|---| -| `db.hbase.namespace` | string | The [HBase namespace](https://hbase.apache.org/book.html#_namespace) being accessed. To be used instead of the generic `db.name` attribute. | `default` | `Required` | +| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | +|---|---|---|---|---|---| +| `db.hbase.namespace` | string | The [HBase namespace](https://hbase.apache.org/book.html#_namespace) being accessed. To be used instead of the generic `db.name` attribute. | `default` | `Required` | Experimental | #### Redis -| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | -|---|---|---|---|---| +| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | +|---|---|---|---|---|---| | `db.redis.database_index` | int | The index of the database being accessed as used in the [`SELECT` command](https://redis.io/commands/select), provided as an integer. To be used instead of the generic `db.name` attribute. | `0`
`1`
`15` | Conditional [1] | **[1]:** if other than the default database (`0`). @@ -195,9 +195,9 @@ For example, when retrieving a document, `db.operation` would be set to (literal #### MongoDB -| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | -|---|---|---|---|---| -| `db.mongodb.collection` | string | The collection being accessed within the database stated in `db.name`. | `customers`
`products` | `Required` | +| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | +|---|---|---|---|---|---| +| `db.mongodb.collection` | string | The collection being accessed within the database stated in `db.name`. | `customers`
`products` | `Required` | Experimental | ## Examples diff --git a/semantic-conventions/src/tests/data/markdown/extend_grandparent/expected.md b/semantic-conventions/src/tests/data/markdown/extend_grandparent/expected.md index 40906dce..46fce809 100644 --- a/semantic-conventions/src/tests/data/markdown/extend_grandparent/expected.md +++ b/semantic-conventions/src/tests/data/markdown/extend_grandparent/expected.md @@ -1,23 +1,23 @@ ## DB spans -| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | -|---|---|---|---|---| -| `db.foo.bar` | string | Some property. | `baz` | `Recommended` | -| `db.name` | string | Database name. | `the_shop` | `Recommended` | +| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | +|---|---|---|---|---|---| +| `db.foo.bar` | string | Some property. | `baz` | `Recommended` | Experimental | +| `db.name` | string | Database name. | `the_shop` | `Recommended` | Experimental | ## DB metrics -| Name | Instrument Type | Unit (UCUM) | Description | -| -------- | --------------- | ----------- | -------------- | -| `db.foo.duration` | Histogram | `s` | Measures the duration of database Foo calls. | +| Name | Instrument Type | Unit (UCUM) | Description | Stability | +| -------- | --------------- | ----------- | -------------- | --------- | +| `db.foo.duration` | Histogram | `s` | Measures the duration of database Foo calls. | Experimental | -| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | -|---|---|---|---|---| -| `db.foo.bar` | string | Some property. | `baz` | `Recommended` | -| `db.name` | string | Database name. | `the_shop` | `Recommended` | +| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | +|---|---|---|---|---|---| +| `db.foo.bar` | string | Some property. | `baz` | `Recommended` | Experimental | +| `db.name` | string | Database name. | `the_shop` | `Recommended` | Experimental | diff --git a/semantic-conventions/src/tests/data/markdown/include/expected.md b/semantic-conventions/src/tests/data/markdown/include/expected.md index 7102b13e..331d979f 100644 --- a/semantic-conventions/src/tests/data/markdown/include/expected.md +++ b/semantic-conventions/src/tests/data/markdown/include/expected.md @@ -1,21 +1,21 @@ # Test Markdown -| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | -|---|---|---|---|---| -| `faas.execution` | string | The execution id of the current function execution. | `af9d5aa4-a685-4c5f-a22b-444f80b3cc28` | `Recommended` | -| `faas.trigger` | string | Type of the trigger on which the function is executed. | `datasource` | `Required` | -| `http.host` | string | The value of the [HTTP host header](https://tools.ietf.org/html/rfc7230#section-5.4). When the header is empty or not present, this attribute should be the same. | `www.example.org` | See below | -| `http.method` | string | HTTP request method. | `GET`; `POST`; `HEAD` | `Required` | -| `http.recommended_attribute` | string | brief | `foo` | `Recommended` short note | -| `http.recommended_attribute_long_note` | string | brief | `bar` | `Recommended` [1] | -| `http.scheme` | string | The URI scheme identifying the used protocol. | `http`; `https` | See below | -| [`http.server_name`](input_http.md) | string | The primary server name of the matched virtual host. [2] | `example.com` | `Conditionally Required` [3] | -| `http.status_code` | int | [HTTP response status code](https://tools.ietf.org/html/rfc7231#section-6). | `200` | `Conditionally Required` if and only if one was received/sent | -| `http.status_text` | string | [HTTP reason phrase](https://tools.ietf.org/html/rfc7230#section-3.1.2). | `OK` | `Recommended` | -| `http.target` | string | The full request target as passed in a HTTP request line or equivalent. | `/path/12314/?q=ddds#123` | See below | -| `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` | See below | -| `http.user_agent` | string | Value of the [HTTP User-Agent](https://tools.ietf.org/html/rfc7231#section-5.5.3) header sent by the client. | `CERN-LineMode/2.15 libwww/2.17b3` | `Recommended` | +| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | +|---|---|---|---|---|---| +| `faas.execution` | string | The execution id of the current function execution. | `af9d5aa4-a685-4c5f-a22b-444f80b3cc28` | `Recommended` | Experimental | +| `faas.trigger` | string | Type of the trigger on which the function is executed. | `datasource` | `Required` | Experimental | +| `http.host` | string | The value of the [HTTP host header](https://tools.ietf.org/html/rfc7230#section-5.4). When the header is empty or not present, this attribute should be the same. | `www.example.org` | See below | Experimental | +| `http.method` | string | HTTP request method. | `GET`; `POST`; `HEAD` | `Required` | Experimental | +| `http.recommended_attribute` | string | brief | `foo` | `Recommended` short note | Experimental | +| `http.recommended_attribute_long_note` | string | brief | `bar` | `Recommended` [1] | Experimental | +| `http.scheme` | string | The URI scheme identifying the used protocol. | `http`; `https` | See below | Experimental | +| [`http.server_name`](input_http.md) | string | The primary server name of the matched virtual host. [2] | `example.com` | `Conditionally Required` [3] | Experimental | +| `http.status_code` | int | [HTTP response status code](https://tools.ietf.org/html/rfc7231#section-6). | `200` | `Conditionally Required` if and only if one was received/sent | Experimental | +| `http.status_text` | string | [HTTP reason phrase](https://tools.ietf.org/html/rfc7230#section-3.1.2). | `OK` | `Recommended` | Experimental | +| `http.target` | string | The full request target as passed in a HTTP request line or equivalent. | `/path/12314/?q=ddds#123` | See below | Experimental | +| `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` | See below | Experimental | +| `http.user_agent` | string | Value of the [HTTP User-Agent](https://tools.ietf.org/html/rfc7231#section-5.5.3) header sent by the client. | `CERN-LineMode/2.15 libwww/2.17b3` | `Recommended` | Experimental | **[1]:** some very long note that should be written under the semconv table @@ -35,11 +35,11 @@ `faas.trigger` MUST be one of the following: -| Value | Description | -|---|---| -| `datasource` | A response to some data source operation such as a database or filesystem read/write. | -| `http` | To provide an answer to an inbound HTTP request | -| `pubsub` | A function is set to be executed when messages are sent to a messaging system. | -| `timer` | A function is scheduled to be executed regularly. | -| `other` | other | +| Value | Description | Stability | +|---|---|---| +| `datasource` | A response to some data source operation such as a database or filesystem read/write. | Experimental | +| `http` | To provide an answer to an inbound HTTP request | Experimental | +| `pubsub` | A function is set to be executed when messages are sent to a messaging system. | Experimental | +| `timer` | A function is scheduled to be executed regularly. | Experimental | +| `other` | other | Experimental | 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 8074bd93..a34ac25b 100644 --- a/semantic-conventions/src/tests/data/markdown/metrics_tables/expected.md +++ b/semantic-conventions/src/tests/data/markdown/metrics_tables/expected.md @@ -2,34 +2,34 @@ **`foo.size`** -| Name | Instrument Type | Unit (UCUM) | Description | -| -------- | --------------- | ----------- | -------------- | -| `foo.size` | Histogram | `{bars}` | Measures the size of foo. [1] | +| Name | Instrument Type | Unit (UCUM) | Description | Stability | +| -------- | --------------- | ----------- | -------------- | --------- | +| `foo.size` | Histogram | `{bars}` | Measures the size of foo. [1] | Stable | **[1]:** Some notes on metric.foo.size **Attributes for `foo.size`** -| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | -|---|---|---|---|---| -| `http.method` | string | HTTP request method. | `GET`; `POST`; `HEAD` | `Required` | -| `http.status_code` | int | [HTTP response status code](https://tools.ietf.org/html/rfc7231#section-6). | `200` | `Conditionally Required` if and only if one was received/sent. | +| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | +|---|---|---|---|---|---| +| `http.method` | string | HTTP request method. | `GET`; `POST`; `HEAD` | `Required` | Experimental | +| `http.status_code` | int | [HTTP response status code](https://tools.ietf.org/html/rfc7231#section-6). | `200` | `Conditionally Required` if and only if one was received/sent. | Experimental | **`foo.active_eggs`** -| Name | Instrument Type | Unit (UCUM) | Description | -| -------- | --------------- | ----------- | -------------- | -| `foo.active_eggs` | UpDownCounter | `{cartons}` | **Deprecated: Removed.**
Measures how many eggs are currently active. | +| Name | Instrument Type | Unit (UCUM) | Description | Stability | +| -------- | --------------- | ----------- | -------------- | --------- | +| `foo.active_eggs` | UpDownCounter | `{cartons}` | Measures how many eggs are currently active. | Deprecated: Removed. | **Attributes for `foo.active_eggs`** -| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | -|---|---|---|---|---| -| `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 | +| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | +|---|---|---|---|---|---| +| `bar.egg.type` | string | Type of egg. [1] | `chicken`; `emu`; `dragon` | `Conditionally Required` if available to instrumentation. | Experimental | +| `http.method` | string | HTTP request method. | `GET`; `POST`; `HEAD` | `Opt-In` | Experimental | **[1]:** Some notes on attribute diff --git a/semantic-conventions/src/tests/data/markdown/missing_end_tag/input.md b/semantic-conventions/src/tests/data/markdown/missing_end_tag/input.md index 8b5289a6..f3c75e9b 100644 --- a/semantic-conventions/src/tests/data/markdown/missing_end_tag/input.md +++ b/semantic-conventions/src/tests/data/markdown/missing_end_tag/input.md @@ -3,21 +3,4 @@ -| Attribute name | Notes and examples | `Required`? | -| :------------- | :----------------------------------------------------------- | --------- | -| `http.method` | HTTP request method. E.g. `"GET"`. | `Required` | -| `http.url` | 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. | Defined later. | -| `http.target` | The full request target as passed in a [HTTP request line][] or equivalent, e.g. `"/path/12314/?q=ddds#123"`. | Defined later. | -| `http.host` | The value of the [HTTP host header][]. When the header is empty or not present, this attribute should be the same. | Defined later. | -| `http.scheme` | The URI scheme identifying the used protocol: `"http"` or `"https"` | Defined later. | -| `http.status_code` | [HTTP response status code][]. E.g. `200` (integer) | `Conditionally Required` if and only if one was received/sent. | -| `http.status_text` | [HTTP reason phrase][]. E.g. `"OK"` | `Recommended` | -| `http.flavor` | Kind of HTTP protocol used: `"1.0"`, `"1.1"`, `"2"`, `"SPDY"` or `"QUIC"`. | Opt-In | -| `http.user_agent` | Value of the HTTP [User-Agent][] header sent by the client. | `Recommended` | - -It is recommended to also use the general [network attributes][], especially `net.peer.ip`. If `net.transport` is not specified, it can be assumed to be `IP.TCP` except if `http.flavor` is `QUIC`, in which case `IP.UDP` is assumed. - -[network attributes]: span-general.md#general-network-connection-attributes -[HTTP response status code]: https://tools.ietf.org/html/rfc7231#section-6 -[HTTP reason phrase]: https://tools.ietf.org/html/rfc7230#section-3.1.2 -[User-Agent]: https://tools.ietf.org/html/rfc7231#section-5.5.3 +There is no end tag here - we expect an error to be raised \ No newline at end of file diff --git a/semantic-conventions/src/tests/data/markdown/multiple/expected.md b/semantic-conventions/src/tests/data/markdown/multiple/expected.md index a3fd8769..8eacf0fa 100644 --- a/semantic-conventions/src/tests/data/markdown/multiple/expected.md +++ b/semantic-conventions/src/tests/data/markdown/multiple/expected.md @@ -2,29 +2,29 @@ -| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | -|---|---|---|---|---| -| `http.host` | string | The value of the [HTTP host header](https://tools.ietf.org/html/rfc7230#section-5.4). When the header is empty or not present, this attribute should be the same. | `www.example.org` | `Recommended` | -| `http.method` | string | HTTP request method. | `GET`; `POST`; `HEAD` | `Required` | -| `http.scheme` | string | The URI scheme identifying the used protocol. | `http`; `https` | `Recommended` | -| `http.status_code` | int | [HTTP response status code](https://tools.ietf.org/html/rfc7231#section-6). | `200` | `Conditionally Required` if and only if one was received/sent | -| `http.status_text` | string | [HTTP reason phrase](https://tools.ietf.org/html/rfc7230#section-3.1.2). | `OK` | `Recommended` | -| `http.target` | string | The full request target as passed in a HTTP request line or equivalent. | `/path/12314/?q=ddds#123` | `Recommended` | -| `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` | `Recommended` | -| `http.user_agent` | string | Value of the [HTTP User-Agent](https://tools.ietf.org/html/rfc7231#section-5.5.3) header sent by the client. | `CERN-LineMode/2.15 libwww/2.17b3` | `Recommended` | +| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | +|---|---|---|---|---|---| +| `http.host` | string | The value of the [HTTP host header](https://tools.ietf.org/html/rfc7230#section-5.4). When the header is empty or not present, this attribute should be the same. | `www.example.org` | `Recommended` | Experimental | +| `http.method` | string | HTTP request method. | `GET`; `POST`; `HEAD` | `Required` | Experimental | +| `http.scheme` | string | The URI scheme identifying the used protocol. | `http`; `https` | `Recommended` | Experimental | +| `http.status_code` | int | [HTTP response status code](https://tools.ietf.org/html/rfc7231#section-6). | `200` | `Conditionally Required` if and only if one was received/sent | Experimental | +| `http.status_text` | string | [HTTP reason phrase](https://tools.ietf.org/html/rfc7230#section-3.1.2). | `OK` | `Recommended` | Experimental | +| `http.target` | string | The full request target as passed in a HTTP request line or equivalent. | `/path/12314/?q=ddds#123` | `Recommended` | Experimental | +| `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` | `Recommended` | Experimental | +| `http.user_agent` | string | Value of the [HTTP User-Agent](https://tools.ietf.org/html/rfc7231#section-5.5.3) header sent by the client. | `CERN-LineMode/2.15 libwww/2.17b3` | `Recommended` | Experimental | -| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | -|---|---|---|---|---| -| `http.host` | string | The value of the [HTTP host header](https://tools.ietf.org/html/rfc7230#section-5.4). When the header is empty or not present, this attribute should be the same. | `www.example.org` | `Recommended` | -| `http.method` | string | HTTP request method. | `GET`; `POST`; `HEAD` | `Required` | -| `http.scheme` | string | The URI scheme identifying the used protocol. | `http`; `https` | `Recommended` | -| `http.status_code` | int | [HTTP response status code](https://tools.ietf.org/html/rfc7231#section-6). | `200` | `Conditionally Required` if and only if one was received/sent | -| `http.status_text` | string | [HTTP reason phrase](https://tools.ietf.org/html/rfc7230#section-3.1.2). | `OK` | `Recommended` | -| `http.target` | string | The full request target as passed in a HTTP request line or equivalent. | `/path/12314/?q=ddds#123` | `Recommended` | -| `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` | `Recommended` | -| `http.user_agent` | string | Value of the [HTTP User-Agent](https://tools.ietf.org/html/rfc7231#section-5.5.3) header sent by the client. | `CERN-LineMode/2.15 libwww/2.17b3` | `Recommended` | +| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | +|---|---|---|---|---|---| +| `http.host` | string | The value of the [HTTP host header](https://tools.ietf.org/html/rfc7230#section-5.4). When the header is empty or not present, this attribute should be the same. | `www.example.org` | `Recommended` | Experimental | +| `http.method` | string | HTTP request method. | `GET`; `POST`; `HEAD` | `Required` | Experimental | +| `http.scheme` | string | The URI scheme identifying the used protocol. | `http`; `https` | `Recommended` | Experimental | +| `http.status_code` | int | [HTTP response status code](https://tools.ietf.org/html/rfc7231#section-6). | `200` | `Conditionally Required` if and only if one was received/sent | Experimental | +| `http.status_text` | string | [HTTP reason phrase](https://tools.ietf.org/html/rfc7230#section-3.1.2). | `OK` | `Recommended` | Experimental | +| `http.target` | string | The full request target as passed in a HTTP request line or equivalent. | `/path/12314/?q=ddds#123` | `Recommended` | Experimental | +| `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` | `Recommended` | Experimental | +| `http.user_agent` | string | Value of the [HTTP User-Agent](https://tools.ietf.org/html/rfc7231#section-5.5.3) header sent by the client. | `CERN-LineMode/2.15 libwww/2.17b3` | `Recommended` | Experimental | It is recommended to also use the general [network attributes][], especially `net.peer.ip`. If `net.transport` is not specified, it can be assumed to be `IP.TCP` except if `http.flavor` is `QUIC`, in which case `IP.UDP` is assumed. diff --git a/semantic-conventions/src/tests/data/markdown/multiple/input.md b/semantic-conventions/src/tests/data/markdown/multiple/input.md index 45ae85c2..e44cb842 100644 --- a/semantic-conventions/src/tests/data/markdown/multiple/input.md +++ b/semantic-conventions/src/tests/data/markdown/multiple/input.md @@ -5,15 +5,15 @@ | Attribute name | Notes and examples | `Required`? | | :------------- | :----------------------------------------------------------- | --------- | -| `http.method` | HTTP request method. E.g. `"GET"`. | `Required` | +| `http.method` | HTTP request method. E.g. `"GET"`. | `Required` | Experimental | | `http.url` | 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. | Defined later. | | `http.target` | The full request target as passed in a [HTTP request line][] or equivalent, e.g. `"/path/12314/?q=ddds#123"`. | Defined later. | | `http.host` | The value of the [HTTP host header][]. When the header is empty or not present, this attribute should be the same. | Defined later. | | `http.scheme` | The URI scheme identifying the used protocol: `"http"` or `"https"` | Defined later. | | `http.status_code` | [HTTP response status code][]. E.g. `200` (integer) | `Conditionally Required` if and only if one was received/sent. | -| `http.status_text` | [HTTP reason phrase][]. E.g. `"OK"` | `Recommended` | +| `http.status_text` | [HTTP reason phrase][]. E.g. `"OK"` | `Recommended` | Experimental | | `http.flavor` | Kind of HTTP protocol used: `"1.0"`, `"1.1"`, `"2"`, `"SPDY"` or `"QUIC"`. | No | -| `http.user_agent` | Value of the HTTP [User-Agent][] header sent by the client. | `Recommended` | +| `http.user_agent` | Value of the HTTP [User-Agent][] header sent by the client. | `Recommended` | Experimental | diff --git a/semantic-conventions/src/tests/data/markdown/multiple_enum/expected.md b/semantic-conventions/src/tests/data/markdown/multiple_enum/expected.md index c3780d61..d652b47f 100644 --- a/semantic-conventions/src/tests/data/markdown/multiple_enum/expected.md +++ b/semantic-conventions/src/tests/data/markdown/multiple_enum/expected.md @@ -2,51 +2,51 @@ -| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | -|---|---|---|---|---| -| `net.host.carrier.icc` | string | host.carrier.icc | `DE` | `Recommended` | -| `net.host.carrier.mcc` | string | host.carrier.mcc | `310` | `Recommended` | -| `net.host.carrier.mnc` | string | host.carrier.mnc | `001` | `Recommended` | -| `net.host.carrier.name` | string | host.carrier.name | `sprint` | `Recommended` | -| `net.host.connection.subtype` | string | This describes more details regarding the connection.type. It may be the type of cell connection, but it could be used for describing details about a wifi connection. | `2G` | `Recommended` | -| `net.host.connection.type` | string | unavailable | `wifi` | `Recommended` | -| `net.host.ip` | string | Like `net.peer.ip` but for the host IP. Useful in case of a multi-IP host. | `192.168.0.1` | `Recommended` | -| `net.host.name` | string | Local hostname or similar, see note below. | `localhost` | `Recommended` | -| `net.host.port` | int | Like `net.peer.port` but for the host port. | `35555` | `Recommended` | -| `net.peer.ip` | string | Remote address of the peer (dotted decimal for IPv4 or [RFC5952](https://tools.ietf.org/html/rfc5952) for IPv6) | `127.0.0.1` | `Recommended` | -| `net.peer.name` | string | Remote hostname or similar, see note below. | `example.com` | `Recommended` | -| `net.peer.port` | int | Remote port number. | `80`; `8080`; `443` | `Recommended` | -| `net.transport` | string | Transport protocol used. See note below. | `IP.TCP` | `Recommended` | +| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | +|---|---|---|---|---|---| +| `net.host.carrier.icc` | string | host.carrier.icc | `DE` | `Recommended` | Experimental | +| `net.host.carrier.mcc` | string | host.carrier.mcc | `310` | `Recommended` | Experimental | +| `net.host.carrier.mnc` | string | host.carrier.mnc | `001` | `Recommended` | Experimental | +| `net.host.carrier.name` | string | host.carrier.name | `sprint` | `Recommended` | Experimental | +| `net.host.connection.subtype` | string | This describes more details regarding the connection.type. It may be the type of cell connection, but it could be used for describing details about a wifi connection. | `2G` | `Recommended` | Experimental | +| `net.host.connection.type` | string | unavailable | `wifi` | `Recommended` | Experimental | +| `net.host.ip` | string | Like `net.peer.ip` but for the host IP. Useful in case of a multi-IP host. | `192.168.0.1` | `Recommended` | Experimental | +| `net.host.name` | string | Local hostname or similar, see note below. | `localhost` | `Recommended` | Experimental | +| `net.host.port` | int | Like `net.peer.port` but for the host port. | `35555` | `Recommended` | Experimental | +| `net.peer.ip` | string | Remote address of the peer (dotted decimal for IPv4 or [RFC5952](https://tools.ietf.org/html/rfc5952) for IPv6) | `127.0.0.1` | `Recommended` | Experimental | +| `net.peer.name` | string | Remote hostname or similar, see note below. | `example.com` | `Recommended` | Experimental | +| `net.peer.port` | int | Remote port number. | `80`; `8080`; `443` | `Recommended` | Experimental | +| `net.transport` | string | Transport protocol used. See note below. | `IP.TCP` | `Recommended` | Experimental | `net.host.connection.subtype` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. -| Value | Description | -|---|---| -| `1G` | 1G | -| `2G` | 2G | +| Value | Description | Stability | +|---|---|---| +| `1G` | 1G | Experimental | +| `2G` | 2G | Experimental | `net.host.connection.type` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. -| Value | Description | -|---|---| -| `wifi` | wifi [1] | -| `wired` | wired | -| `cell` | cell | -| `unavailable` | unavailable | +| Value | Description | Stability | +|---|---|---| +| `wifi` | wifi [1] | Experimental | +| `wired` | wired | Experimental | +| `cell` | cell | Experimental | +| `unavailable` | unavailable | Experimental | **[1]:** Usually 802.11 `net.transport` MUST be one of the following: -| Value | Description | -|---|---| -| `IP.TCP` | ip.tcp | -| `IP.UDP` | ip.udp | -| `IP` | Another IP-based protocol | -| `Unix` | Unix Domain socket. See below. | -| `pipe` | Named or anonymous pipe. See note below. | -| `inproc` | In-process communication. [1] | -| `other` | Something else (non IP-based). | +| Value | Description | Stability | +|---|---|---| +| `IP.TCP` | ip.tcp | Experimental | +| `IP.UDP` | ip.udp | Experimental | +| `IP` | Another IP-based protocol | Experimental | +| `Unix` | Unix Domain socket. See below. | Experimental | +| `pipe` | Named or anonymous pipe. See note below. | Experimental | +| `inproc` | In-process communication. [1] | Experimental | +| `other` | Something else (non IP-based). | Experimental | **[1]:** Signals that there is only in-process communication not using a "real" network protocol in cases where network attributes would normally be expected. Usually all other network attributes can be left out in that case. 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 index ffa730ac..0d0e99cd 100644 --- a/semantic-conventions/src/tests/data/markdown/omit_requirement_level/expected.md +++ b/semantic-conventions/src/tests/data/markdown/omit_requirement_level/expected.md @@ -1,9 +1,9 @@ # Common Attributes -| Attribute | Type | Description | Examples | -|---|---|---|---| -| `http.method` | string | HTTP request method. | `GET`; `POST`; `HEAD` | -| `http.target` | string | The full request target as passed in a HTTP request line or equivalent. | `/path/12314/?q=ddds#123` | -| `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` | +| Attribute | Type | Description | Examples | Stability | +|---|---|---|---|---| +| `http.method` | string | HTTP request method. | `GET`; `POST`; `HEAD` | Experimental | +| `http.target` | string | The full request target as passed in a HTTP request line or equivalent. | `/path/12314/?q=ddds#123` | Experimental | +| `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` | Experimental | diff --git a/semantic-conventions/src/tests/data/markdown/parameter_empty/http.md b/semantic-conventions/src/tests/data/markdown/parameter_empty/http.md index de3e6daa..cfaaf1d4 100644 --- a/semantic-conventions/src/tests/data/markdown/parameter_empty/http.md +++ b/semantic-conventions/src/tests/data/markdown/parameter_empty/http.md @@ -1,11 +1,11 @@ # General -| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | -|---|---|---|---|---| -| `http.server_name` | String | The primary server name of the matched virtual host. [1] | `example.com` | `Conditionally Required` [2] | -| `http.route` | String | The matched route (path template). | `/users/:userID?` | `Recommended` | -| `http.client_ip` | String | The IP address of the original client behind all proxies, if known (e.g. from [X-Forwarded-For](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/X-Forwarded-For)). [3] | `83.164.160.102` | `Recommended` | +| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | +|---|---|---|---|---|---| +| `http.server_name` | String | The primary server name of the matched virtual host. [1] | `example.com` | `Conditionally Required` [2] | Experimental | +| `http.route` | String | The matched route (path template). | `/users/:userID?` | `Recommended` | Experimental | +| `http.client_ip` | String | The IP address of the original client behind all proxies, if known (e.g. from [X-Forwarded-For](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/X-Forwarded-For)). [3] | `83.164.160.102` | `Recommended` | Experimental | **[1]:** http.url is usually not readily available on the server side but would have to be assembled in a cumbersome and sometimes lossy process from other information (see e.g. open-telemetry/opentelemetry-python/pull/148). It is thus preferred to supply the raw data that is available. diff --git a/semantic-conventions/src/tests/data/markdown/parameter_full/expected.md b/semantic-conventions/src/tests/data/markdown/parameter_full/expected.md index 52f04e18..34b5b5ea 100644 --- a/semantic-conventions/src/tests/data/markdown/parameter_full/expected.md +++ b/semantic-conventions/src/tests/data/markdown/parameter_full/expected.md @@ -1,21 +1,21 @@ # Attributes -| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | -|---|---|---|---|---| -| `faas.execution` | string | The execution id of the current function execution. | `af9d5aa4-a685-4c5f-a22b-444f80b3cc28` | `Recommended` | -| `faas.trigger` | string | Type of the trigger on which the function is executed. | `datasource` | `Required` | -| [`http.client_ip`](http.md) | string | The IP address of the original client behind all proxies, if known (e.g. from [X-Forwarded-For](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/X-Forwarded-For)). [1] | `83.164.160.102` | `Recommended` | -| `http.host` | string | The value of the [HTTP host header](https://tools.ietf.org/html/rfc7230#section-5.4). When the header is empty or not present, this attribute should be the same. | `www.example.org` | `Conditionally Required` | -| `http.method` | string | HTTP request method. | `GET`; `POST`; `HEAD` | `Required` | -| [`http.route`](http.md) | string | The matched route (path template). | `/users/:userID?` | `Recommended` | -| `http.scheme` | string | The URI scheme identifying the used protocol. | `http`; `https` | See below | -| [`http.server_name`](http.md) | string | The primary server name of the matched virtual host. [2] | `example.com` | `Conditionally Required` [3] | -| `http.status_code` | int | [HTTP response status code](https://tools.ietf.org/html/rfc7231#section-6). | `200` | `Conditionally Required` if and only if one was received/sent. | -| `http.status_text` | string | [HTTP reason phrase](https://tools.ietf.org/html/rfc7230#section-3.1.2). | `OK` | `Recommended` | -| `http.target` | string | The full request target as passed in a HTTP request line or equivalent. | `/path/12314/?q=ddds#123` | See below | -| `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` | See below | -| `http.user_agent` | string | Value of the [HTTP User-Agent](https://tools.ietf.org/html/rfc7231#section-5.5.3) header sent by the client. | `CERN-LineMode/2.15 libwww/2.17b3` | `Recommended` | +| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | +|---|---|---|---|---|---| +| `faas.execution` | string | The execution id of the current function execution. | `af9d5aa4-a685-4c5f-a22b-444f80b3cc28` | `Recommended` | Experimental | +| `faas.trigger` | string | Type of the trigger on which the function is executed. | `datasource` | `Required` | Experimental | +| [`http.client_ip`](http.md) | string | The IP address of the original client behind all proxies, if known (e.g. from [X-Forwarded-For](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/X-Forwarded-For)). [1] | `83.164.160.102` | `Recommended` | Experimental | +| `http.host` | string | The value of the [HTTP host header](https://tools.ietf.org/html/rfc7230#section-5.4). When the header is empty or not present, this attribute should be the same. | `www.example.org` | `Conditionally Required` | Experimental | +| `http.method` | string | HTTP request method. | `GET`; `POST`; `HEAD` | `Required` | Experimental | +| [`http.route`](http.md) | string | The matched route (path template). | `/users/:userID?` | `Recommended` | Experimental | +| `http.scheme` | string | The URI scheme identifying the used protocol. | `http`; `https` | See below | Experimental | +| [`http.server_name`](http.md) | string | The primary server name of the matched virtual host. [2] | `example.com` | `Conditionally Required` [3] | Experimental | +| `http.status_code` | int | [HTTP response status code](https://tools.ietf.org/html/rfc7231#section-6). | `200` | `Conditionally Required` if and only if one was received/sent. | Experimental | +| `http.status_text` | string | [HTTP reason phrase](https://tools.ietf.org/html/rfc7230#section-3.1.2). | `OK` | `Recommended` | Experimental | +| `http.target` | string | The full request target as passed in a HTTP request line or equivalent. | `/path/12314/?q=ddds#123` | See below | Experimental | +| `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` | See below | Experimental | +| `http.user_agent` | string | Value of the [HTTP User-Agent](https://tools.ietf.org/html/rfc7231#section-5.5.3) header sent by the client. | `CERN-LineMode/2.15 libwww/2.17b3` | `Recommended` | Experimental | **[1]:** This is not necessarily the same as `net.peer.ip`, which would identify the network-level peer, which may be a proxy. @@ -32,11 +32,11 @@ `faas.trigger` MUST be one of the following: -| Value | Description | -|---|---| -| `datasource` | A response to some data source operation such as a database or filesystem read/write. | -| `http` | To provide an answer to an inbound HTTP request | -| `pubsub` | A function is set to be executed when messages are sent to a messaging system. | -| `timer` | A function is scheduled to be executed regularly. | -| `other` | other | +| Value | Description | Stability | +|---|---|---| +| `datasource` | A response to some data source operation such as a database or filesystem read/write. | Experimental | +| `http` | To provide an answer to an inbound HTTP request | Experimental | +| `pubsub` | A function is set to be executed when messages are sent to a messaging system. | Experimental | +| `timer` | A function is scheduled to be executed regularly. | Experimental | +| `other` | other | Experimental | diff --git a/semantic-conventions/src/tests/data/markdown/parameter_full/http.md b/semantic-conventions/src/tests/data/markdown/parameter_full/http.md index b634120b..01eab08d 100644 --- a/semantic-conventions/src/tests/data/markdown/parameter_full/http.md +++ b/semantic-conventions/src/tests/data/markdown/parameter_full/http.md @@ -1,11 +1,11 @@ # General -| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | -|---|---|---|---|---| -| `http.server_name` | String | The primary server name of the matched virtual host. [1] | `example.com` | `Conditionally Required` [2] | -| `http.route` | String | The matched route (path template). | `/users/:userID?` | `Recommended` | -| `http.client_ip` | String | The IP address of the original client behind all proxies, if known (e.g. from [X-Forwarded-For](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/X-Forwarded-For)). [3] | `83.164.160.102` | `Recommended` | +| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | +|---|---|---|---|---|---| +| `http.server_name` | String | The primary server name of the matched virtual host. [1] | `example.com` | `Conditionally Required` [2] | Experimental | +| `http.route` | String | The matched route (path template). | `/users/:userID?` | `Recommended` | Experimental | +| `http.client_ip` | String | The IP address of the original client behind all proxies, if known (e.g. from [X-Forwarded-For](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/X-Forwarded-For)). [3] | `83.164.160.102` | `Recommended` | Experimental | **[1]:** http.url is usually not readily available on the server side but would have to be assembled in a cumbersome and sometimes lossy process from other information (see e.g. open-telemetry/opentelemetry-python/pull/148). It is thus preferred to supply the raw data that is available. diff --git a/semantic-conventions/src/tests/data/markdown/parameter_remove_constraint/expected.md b/semantic-conventions/src/tests/data/markdown/parameter_remove_constraint/expected.md index 6d062e68..b9b93999 100644 --- a/semantic-conventions/src/tests/data/markdown/parameter_remove_constraint/expected.md +++ b/semantic-conventions/src/tests/data/markdown/parameter_remove_constraint/expected.md @@ -1,26 +1,26 @@ # DB -| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | -|---|---|---|---|---| -| `db.connection_string` | string | The connection string used to connect to the database. [1] | `Server=(localdb)\v11.0;Integrated Security=true;` | `Recommended` | -| `db.type` | string | Database type. For any SQL database, "sql". For others, the lower-case database category. | `sql` | `Required` | -| `db.user` | string | Username for accessing the database. | `readonly_user`; `reporting_user` | `Recommended` | -| `net.peer.ip` | string | Remote address of the peer (dotted decimal for IPv4 or [RFC5952](https://tools.ietf.org/html/rfc5952) for IPv6) | `127.0.0.1` | `Recommended` | -| `net.peer.name` | string | Remote hostname or similar, see note below. | `example.com` | `Recommended` | -| `net.peer.port` | int | Remote port number. | `80`; `8080`; `443` | `Recommended` | +| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | +|---|---|---|---|---|---| +| `db.connection_string` | string | The connection string used to connect to the database. [1] | `Server=(localdb)\v11.0;Integrated Security=true;` | `Recommended` | Experimental | +| `db.type` | string | Database type. For any SQL database, "sql". For others, the lower-case database category. | `sql` | `Required` | Experimental | +| `db.user` | string | Username for accessing the database. | `readonly_user`; `reporting_user` | `Recommended` | Experimental | +| `net.peer.ip` | string | Remote address of the peer (dotted decimal for IPv4 or [RFC5952](https://tools.ietf.org/html/rfc5952) for IPv6) | `127.0.0.1` | `Recommended` | Experimental | +| `net.peer.name` | string | Remote hostname or similar, see note below. | `example.com` | `Recommended` | Experimental | +| `net.peer.port` | int | Remote port number. | `80`; `8080`; `443` | `Recommended` | Experimental | **[1]:** It is recommended to remove embedded credentials. `db.type` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. -| Value | Description | -|---|---| -| `sql` | A SQL database | -| `cassandra` | Apache Cassandra | -| `hbase` | Apache HBase | -| `mongodb` | MongoDB | -| `redis` | Redis | -| `couchbase` | Couchbase | -| `couchdb` | CouchDB | +| Value | Description | Stability | +|---|---|---| +| `sql` | A SQL database | Experimental | +| `cassandra` | Apache Cassandra | Experimental | +| `hbase` | Apache HBase | Experimental | +| `mongodb` | MongoDB | Experimental | +| `redis` | Redis | Experimental | +| `couchbase` | Couchbase | Experimental | +| `couchdb` | CouchDB | Experimental | diff --git a/semantic-conventions/src/tests/data/markdown/parameter_remove_constraint/input.md b/semantic-conventions/src/tests/data/markdown/parameter_remove_constraint/input.md index aa49e453..2d4bffac 100644 --- a/semantic-conventions/src/tests/data/markdown/parameter_remove_constraint/input.md +++ b/semantic-conventions/src/tests/data/markdown/parameter_remove_constraint/input.md @@ -1,28 +1,28 @@ # DB -| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | -|---|---|---|---|---| -| `db.type` | String | Database type. For any SQL database, "sql". For others, the lower-case database category. | `sql` | `Required` | -| `db.connection_string` | String | The connection string used to connect to the database. [1] | `Server=(localdb)\v11.0;Integrated Security=true;` | `Recommended` | -| `db.user` | String | Username for accessing the database. | `readonly_user`
`reporting_user` | `Recommended` | -| [net.peer.ip](general.md) | String | None | `127.0.0.1` | `Recommended` | -| [net.peer.name](general.md) | String | None | `example.com` | `Recommended` | -| [net.peer.port](general.md) | int | None | `80`
`8080`
`443` | `Recommended` | -| [net.transport](general.md) | Enum | None | `IP.TCP` | `Recommended` | +| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | +|---|---|---|---|---|---| +| `db.type` | String | Database type. For any SQL database, "sql". For others, the lower-case database category. | `sql` | `Required` | Experimental | +| `db.connection_string` | String | The connection string used to connect to the database. [1] | `Server=(localdb)\v11.0;Integrated Security=true;` | `Recommended` | Experimental | +| `db.user` | String | Username for accessing the database. | `readonly_user`
`reporting_user` | `Recommended` | Experimental | +| [net.peer.ip](general.md) | String | None | `127.0.0.1` | `Recommended` | Experimental | +| [net.peer.name](general.md) | String | None | `example.com` | `Recommended` | Experimental | +| [net.peer.port](general.md) | int | None | `80`
`8080`
`443` | `Recommended` | Experimental | +| [net.transport](general.md) | Enum | None | `IP.TCP` | `Recommended` | Experimental | **[1]:** It is recommended to remove embedded credentials. `db.type` MUST be one of the following: -| Value | Description | -|---|---| -| sql | A SQL database | -| cassandra | Apache Cassandra | -| hbase | Apache HBase | -| mongodb | MongoDB | -| redis | Redis | -| couchbase | Couchbase | -| couchdb | CouchDB | +| Value | Description | Stability | +|---|---|---| +| sql | A SQL database | Experimental | +| cassandra | Apache Cassandra | Experimental | +| hbase | Apache HBase | Experimental | +| mongodb | MongoDB | Experimental | +| redis | Redis | Experimental | +| couchbase | Couchbase | Experimental | +| couchdb | CouchDB | Experimental | diff --git a/semantic-conventions/src/tests/data/markdown/parameter_tag/expected.md b/semantic-conventions/src/tests/data/markdown/parameter_tag/expected.md index bf1dd634..38ce374f 100644 --- a/semantic-conventions/src/tests/data/markdown/parameter_tag/expected.md +++ b/semantic-conventions/src/tests/data/markdown/parameter_tag/expected.md @@ -1,14 +1,14 @@ # DB -| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | -|---|---|---|---|---| -| `db.connection_string` | string | The connection string used to connect to the database. [1] | `Server=(localdb)\v11.0;Integrated Security=true;` | `Recommended` | -| `db.type` | string | Database type. For any SQL database, "sql". For others, the lower-case database category. | `sql` | `Required` | -| `db.user` | string | Username for accessing the database. | `readonly_user`; `reporting_user` | `Recommended` | -| `net.peer.ip` | string | Remote address of the peer (dotted decimal for IPv4 or [RFC5952](https://tools.ietf.org/html/rfc5952) for IPv6) | `127.0.0.1` | See below | -| `net.peer.name` | string | Remote hostname or similar, see note below. | `example.com` | See below | -| `net.peer.port` | int | Remote port number. | `80`; `8080`; `443` | `Recommended` | +| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | +|---|---|---|---|---|---| +| `db.connection_string` | string | The connection string used to connect to the database. [1] | `Server=(localdb)\v11.0;Integrated Security=true;` | `Recommended` | Experimental | +| `db.type` | string | Database type. For any SQL database, "sql". For others, the lower-case database category. | `sql` | `Required` | Experimental | +| `db.user` | string | Username for accessing the database. | `readonly_user`; `reporting_user` | `Recommended` | Experimental | +| `net.peer.ip` | string | Remote address of the peer (dotted decimal for IPv4 or [RFC5952](https://tools.ietf.org/html/rfc5952) for IPv6) | `127.0.0.1` | See below | Experimental | +| `net.peer.name` | string | Remote hostname or similar, see note below. | `example.com` | See below | Experimental | +| `net.peer.port` | int | Remote port number. | `80`; `8080`; `443` | `Recommended` | Experimental | **[1]:** It is recommended to remove embedded credentials. @@ -19,13 +19,13 @@ `db.type` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. -| Value | Description | -|---|---| -| `sql` | A SQL database | -| `cassandra` | Apache Cassandra | -| `hbase` | Apache HBase | -| `mongodb` | MongoDB | -| `redis` | Redis | -| `couchbase` | Couchbase | -| `couchdb` | CouchDB | +| Value | Description | Stability | +|---|---|---| +| `sql` | A SQL database | Experimental | +| `cassandra` | Apache Cassandra | Experimental | +| `hbase` | Apache HBase | Experimental | +| `mongodb` | MongoDB | Experimental | +| `redis` | Redis | Experimental | +| `couchbase` | Couchbase | Experimental | +| `couchdb` | CouchDB | Experimental | diff --git a/semantic-conventions/src/tests/data/markdown/parameter_tag_empty/expected.md b/semantic-conventions/src/tests/data/markdown/parameter_tag_empty/expected.md index 6197be43..bfdee699 100644 --- a/semantic-conventions/src/tests/data/markdown/parameter_tag_empty/expected.md +++ b/semantic-conventions/src/tests/data/markdown/parameter_tag_empty/expected.md @@ -1,14 +1,14 @@ # DB -| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | -|---|---|---|---|---| -| `db.dbms` | string | An identifier for the DBMS (database management system) product | `mssql` | `Conditionally Required` for `db.type="sql"` | -| `db.jdbc.driver_classname` | string | The fully-qualified class name of the JDBC driver used to connect. | `org.postgresql.Driver`; `com.microsoft.sqlserver.jdbc.SQLServerDriver` | `Recommended` | -| `db.mssql.instance_name` | string | The Microsoft SQL Server [instance name](https://docs.microsoft.com/en-us/sql/connect/jdbc/building-the-connection-url?view=sql-server-ver15) connecting to. This name is used to determine the port of a named instance. [1] | `MSSQLSERVER` | `Recommended` | -| `db.name` | string | If no tech-specific attribute is defined below, this attribute is used to report the name of the database being accessed. For commands that switch the database, this should be set to the target database (even if the command fails). [2] | `customers`; `master` | `Conditionally Required` [3] | -| `db.operation` | string | The type of operation that is executed, e.g. the [MongoDB command name](https://docs.mongodb.com/manual/reference/command/#database-operations) such as `findAndModify`. While it would semantically make sense to set this, e.g., to a SQL keyword like `SELECT` or `INSERT`, it is not recommended to attempt any client-side parsing of `db.statement` just to get this property (the back end can do that if required). | `findAndModify` | `Conditionally Required` if `db.statement` is not applicable. | -| `db.statement` | string | A database statement for the given database type. [4] | `SELECT * FROM wuser_table`; `SET mykey "WuValue"` | `Conditionally Required` if applicable. | +| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | +|---|---|---|---|---|---| +| `db.dbms` | string | An identifier for the DBMS (database management system) product | `mssql` | `Conditionally Required` for `db.type="sql"` | Experimental | +| `db.jdbc.driver_classname` | string | The fully-qualified class name of the JDBC driver used to connect. | `org.postgresql.Driver`; `com.microsoft.sqlserver.jdbc.SQLServerDriver` | `Recommended` | Experimental | +| `db.mssql.instance_name` | string | The Microsoft SQL Server [instance name](https://docs.microsoft.com/en-us/sql/connect/jdbc/building-the-connection-url?view=sql-server-ver15) connecting to. This name is used to determine the port of a named instance. [1] | `MSSQLSERVER` | `Recommended` | Experimental | +| `db.name` | string | If no tech-specific attribute is defined below, this attribute is used to report the name of the database being accessed. For commands that switch the database, this should be set to the target database (even if the command fails). [2] | `customers`; `master` | `Conditionally Required` [3] | Experimental | +| `db.operation` | string | The type of operation that is executed, e.g. the [MongoDB command name](https://docs.mongodb.com/manual/reference/command/#database-operations) such as `findAndModify`. While it would semantically make sense to set this, e.g., to a SQL keyword like `SELECT` or `INSERT`, it is not recommended to attempt any client-side parsing of `db.statement` just to get this property (the back end can do that if required). | `findAndModify` | `Conditionally Required` if `db.statement` is not applicable. | Experimental | +| `db.statement` | string | A database statement for the given database type. [4] | `SELECT * FROM wuser_table`; `SET mykey "WuValue"` | `Conditionally Required` if applicable. | Experimental | **[1]:** If setting a `db.mssql.instance_name`, `net.peer.port` is no longer required (but still recommended if non-standard). @@ -25,39 +25,39 @@ `db.dbms` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. -| Value | Description | -|---|---| -| `mssql` | Microsoft SQL Server | -| `mysql` | MySQL | -| `oracle` | Oracle | -| `db2` | IBM Db2 | -| `postgresql` | PostgreSQL | -| `redshift` | Amazon Redshift | -| `hive` | Apache Hive | -| `cloudscape` | Cloudscape | -| `hsqlsb` | HyperSQL DataBase | -| `progress` | Progress Database | -| `maxdb` | SAP MaxDB | -| `hanadb` | SAP HANA | -| `ingres` | Ingres | -| `firstsql` | FirstSQL | -| `edb` | EnterpriseDB | -| `cache` | InterSystems Caché | -| `adabas` | Adabas (Adaptable Database System) | -| `firebird` | Firebird | -| `derby` | Apache Derby | -| `filemaker` | FileMaker | -| `informix` | Informix | -| `instantdb` | InstantDB | -| `interbase` | InterBase | -| `mariadb` | MariaDB | -| `netezza` | Netezza | -| `pervasive` | Pervasive PSQL | -| `pointbase` | PointBase | -| `sqlite` | SQLite | -| `sybase` | Sybase | -| `teradata` | Teradata | -| `vertica` | Vertica | -| `h2` | H2 | -| `coldfusion` | ColdFusion IMQ | +| Value | Description | Stability | +|---|---|---| +| `mssql` | Microsoft SQL Server | Experimental | +| `mysql` | MySQL | Experimental | +| `oracle` | Oracle | Experimental | +| `db2` | IBM Db2 | Experimental | +| `postgresql` | PostgreSQL | Experimental | +| `redshift` | Amazon Redshift | Experimental | +| `hive` | Apache Hive | Experimental | +| `cloudscape` | Cloudscape | Experimental | +| `hsqlsb` | HyperSQL DataBase | Experimental | +| `progress` | Progress Database | Experimental | +| `maxdb` | SAP MaxDB | Experimental | +| `hanadb` | SAP HANA | Experimental | +| `ingres` | Ingres | Experimental | +| `firstsql` | FirstSQL | Experimental | +| `edb` | EnterpriseDB | Experimental | +| `cache` | InterSystems Caché | Experimental | +| `adabas` | Adabas (Adaptable Database System) | Experimental | +| `firebird` | Firebird | Experimental | +| `derby` | Apache Derby | Experimental | +| `filemaker` | FileMaker | Experimental | +| `informix` | Informix | Experimental | +| `instantdb` | InstantDB | Experimental | +| `interbase` | InterBase | Experimental | +| `mariadb` | MariaDB | Experimental | +| `netezza` | Netezza | Experimental | +| `pervasive` | Pervasive PSQL | Experimental | +| `pointbase` | PointBase | Experimental | +| `sqlite` | SQLite | Experimental | +| `sybase` | Sybase | Experimental | +| `teradata` | Teradata | Experimental | +| `vertica` | Vertica | Experimental | +| `h2` | H2 | Experimental | +| `coldfusion` | ColdFusion IMQ | Experimental | \ No newline at end of file diff --git a/semantic-conventions/src/tests/data/markdown/ref/expected.md b/semantic-conventions/src/tests/data/markdown/ref/expected.md index ad50fff0..2fade255 100644 --- a/semantic-conventions/src/tests/data/markdown/ref/expected.md +++ b/semantic-conventions/src/tests/data/markdown/ref/expected.md @@ -1,13 +1,13 @@ # Attributes -| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | -|---|---|---|---|---| -| [`net.peer.name`](input_general.md) | string | override brief. [1] | `example.com` | Opt-In | -| [`net.peer.port`](input_general.md) | int | It describes the server port the client is connecting to | `80`; `8080`; `443` | `Required` | -| [`net.sock.peer.addr`](input_general.md) | string | Remote socket peer address. | `127.0.0.1`; `/tmp/mysql.sock` | `Required` | -| [`net.sock.peer.port`](input_general.md) | int | Remote socket peer port. | `16456` | `Conditionally Required` | -| `rpc.service` | string | The service name, must be equal to the $service part in the span name. | `EchoService` | `Required` | +| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | +|---|---|---|---|---|---| +| [`net.peer.name`](input_general.md) | string | override brief. [1] | `example.com` | `Opt-In` | Experimental | +| [`net.peer.port`](input_general.md) | int | It describes the server port the client is connecting to | `80`; `8080`; `443` | `Required` | Experimental | +| [`net.sock.peer.addr`](input_general.md) | string | Remote socket peer address. | `127.0.0.1`; `/tmp/mysql.sock` | `Required` | Experimental | +| [`net.sock.peer.port`](input_general.md) | int | Remote socket peer port. | `16456` | `Conditionally Required` | Experimental | +| `rpc.service` | string | The service name, must be equal to the $service part in the span name. | `EchoService` | `Required` | Experimental | **[1]:** override note. diff --git a/semantic-conventions/src/tests/data/markdown/ref_extends/expected.md b/semantic-conventions/src/tests/data/markdown/ref_extends/expected.md index e08408c3..1a795493 100644 --- a/semantic-conventions/src/tests/data/markdown/ref_extends/expected.md +++ b/semantic-conventions/src/tests/data/markdown/ref_extends/expected.md @@ -1,9 +1,9 @@ # Spans -| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | -|---|---|---|---|---| -| [`server.address`](input_server.md) | string | Server component of Host header. (overridden brief) [1] | `foo.io` | `Required` | +| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | +|---|---|---|---|---|---| +| [`server.address`](input_server.md) | string | Server component of Host header. (overridden brief) [1] | `foo.io` | `Required` | Experimental | **[1]:** Note on the overridden attribute definition. @@ -15,15 +15,15 @@ The following attributes can be important for making sampling decisions and SHOU # Metrics -| Name | Instrument Type | Unit (UCUM) | Description | -| -------- | --------------- | ----------- | -------------- | -| `http.client.request.duration` | Histogram | `s` | Measures request duration. | +| Name | Instrument Type | Unit (UCUM) | Description | Stability | +| -------- | --------------- | ----------- | -------------- | --------- | +| `http.client.request.duration` | Histogram | `s` | Measures request duration. | Experimental | -| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | -|---|---|---|---|---| -| [`server.address`](input_server.md) | string | Server component of Host header. (overridden brief) [1] | `foo.io` | `Required` | +| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | +|---|---|---|---|---|---| +| [`server.address`](input_server.md) | string | Server component of Host header. (overridden brief) [1] | `foo.io` | `Required` | Experimental | **[1]:** Note on the overridden attribute definition. diff --git a/semantic-conventions/src/tests/data/markdown/sampling_relevant/expected.md b/semantic-conventions/src/tests/data/markdown/sampling_relevant/expected.md index ed838467..1bf30abd 100644 --- a/semantic-conventions/src/tests/data/markdown/sampling_relevant/expected.md +++ b/semantic-conventions/src/tests/data/markdown/sampling_relevant/expected.md @@ -1,18 +1,18 @@ # Attributes -| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | -|---|---|---|---|---| -| `http.host` | string | . | `.` | `Recommended` | -| `http.method` | string | . | `GET` | `Required` | -| `http.scheme` | string | . | `http` | `Recommended` | -| `http.status_code` | int | . | | `Conditionally Required` | -| `http.target` | string | . | `.` | `Recommended` | -| `http.url` | string | . [1] | `.` | `Recommended` | -| `http.user_agent` | string | . | `.` | `Recommended` | -| [`net.peer.ip`](span-general.md) | string | . | `.` | `Recommended` | -| [`net.peer.name`](span-general.md) | string | . | `.` | `Recommended` | -| [`net.peer.port`](span-general.md) | int | . | | `Recommended` | +| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | +|---|---|---|---|---|---| +| `http.host` | string | . | `.` | `Recommended` | Experimental | +| `http.method` | string | . | `GET` | `Required` | Experimental | +| `http.scheme` | string | . | `http` | `Recommended` | Experimental | +| `http.status_code` | int | . | | `Conditionally Required` | Experimental | +| `http.target` | string | . | `.` | `Recommended` | Experimental | +| `http.url` | string | . [1] | `.` | `Recommended` | Experimental | +| `http.user_agent` | string | . | `.` | `Recommended` | Experimental | +| [`net.peer.ip`](span-general.md) | string | . | `.` | `Recommended` | Experimental | +| [`net.peer.name`](span-general.md) | string | . | `.` | `Recommended` | Experimental | +| [`net.peer.port`](span-general.md) | int | . | | `Recommended` | Experimental | **[1]:** `http.url` MUST NOT contain credentials passed via URL in form of `https://username:password@www.example.com/`. In such case the attribute's value should be `https://www.example.com/`. diff --git a/semantic-conventions/src/tests/data/markdown/scope/expected.md b/semantic-conventions/src/tests/data/markdown/scope/expected.md index e6ff24f9..29209024 100644 --- a/semantic-conventions/src/tests/data/markdown/scope/expected.md +++ b/semantic-conventions/src/tests/data/markdown/scope/expected.md @@ -1,7 +1,7 @@ # Instrumentation Scope Semantic Conventions -| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | -|---|---|---|---|---| -| `short_name` | string | The single-word name for the instrumentation scope. | `mylibrary` | `Recommended` | +| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | +|---|---|---|---|---|---| +| `short_name` | string | The single-word name for the instrumentation scope. | `mylibrary` | `Recommended` | Experimental | diff --git a/semantic-conventions/src/tests/data/markdown/single/expected.md b/semantic-conventions/src/tests/data/markdown/single/expected.md index 7bee2d95..212af0eb 100644 --- a/semantic-conventions/src/tests/data/markdown/single/expected.md +++ b/semantic-conventions/src/tests/data/markdown/single/expected.md @@ -2,16 +2,16 @@ -| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | -|---|---|---|---|---| -| `http.host` | string | The value of the [HTTP host header](https://tools.ietf.org/html/rfc7230#section-5.4). When the header is empty or not present, this attribute should be the same. | `www.example.org` | `Conditionally Required` | -| `http.method` | string | HTTP request method. | `GET`; `POST`; `HEAD` | `Required` | -| `http.scheme` | string | The URI scheme identifying the used protocol. | `http`; `https` | `Recommended` | -| `http.status_code` | int | [HTTP response status code](https://tools.ietf.org/html/rfc7231#section-6). | `200` | `Conditionally Required` if and only if one was received/sent. | -| `http.status_text` | string | [HTTP reason phrase](https://tools.ietf.org/html/rfc7230#section-3.1.2). | `OK` | `Recommended` | -| `http.target` | string | The full request target as passed in a HTTP request line or equivalent. | `/path/12314/?q=ddds#123` | `Recommended` | -| `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` | `Recommended` | -| `http.user_agent` | string | Value of the [HTTP User-Agent](https://tools.ietf.org/html/rfc7231#section-5.5.3) header sent by the client. | `CERN-LineMode/2.15 libwww/2.17b3` | `Recommended` | +| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | +|---|---|---|---|---|---| +| `http.host` | string | The value of the [HTTP host header](https://tools.ietf.org/html/rfc7230#section-5.4). When the header is empty or not present, this attribute should be the same. | `www.example.org` | `Conditionally Required` | Experimental | +| `http.method` | string | HTTP request method. | `GET`; `POST`; `HEAD` | `Required` | Experimental | +| `http.scheme` | string | The URI scheme identifying the used protocol. | `http`; `https` | `Recommended` | Experimental | +| `http.status_code` | int | [HTTP response status code](https://tools.ietf.org/html/rfc7231#section-6). | `200` | `Conditionally Required` if and only if one was received/sent. | Experimental | +| `http.status_text` | string | [HTTP reason phrase](https://tools.ietf.org/html/rfc7230#section-3.1.2). | `OK` | `Recommended` | Experimental | +| `http.target` | string | The full request target as passed in a HTTP request line or equivalent. | `/path/12314/?q=ddds#123` | `Recommended` | Experimental | +| `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` | `Recommended` | Experimental | +| `http.user_agent` | string | Value of the [HTTP User-Agent](https://tools.ietf.org/html/rfc7231#section-5.5.3) header sent by the client. | `CERN-LineMode/2.15 libwww/2.17b3` | `Recommended` | Experimental | It is recommended to also use the general [network attributes][], especially `net.peer.ip`. If `net.transport` is not specified, it can be assumed to be `IP.TCP` except if `http.flavor` is `QUIC`, in which case `IP.UDP` is assumed. diff --git a/semantic-conventions/src/tests/data/markdown/single/input.md b/semantic-conventions/src/tests/data/markdown/single/input.md index 4e6e41b1..8ad61ec5 100644 --- a/semantic-conventions/src/tests/data/markdown/single/input.md +++ b/semantic-conventions/src/tests/data/markdown/single/input.md @@ -5,15 +5,15 @@ | Attribute name | Notes and examples | `Required`? | | :------------- | :----------------------------------------------------------- | --------- | -| `http.method` | HTTP request method. E.g. `"GET"`. | `Required` | +| `http.method` | HTTP request method. E.g. `"GET"`. | `Required` | Experimental | | `http.url` | 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. | Defined later. | | `http.target` | The full request target as passed in a [HTTP request line][] or equivalent, e.g. `"/path/12314/?q=ddds#123"`. | Defined later. | | `http.host` | The value of the [HTTP host header][]. When the header is empty or not present, this attribute should be the same. | Defined later. | | `http.scheme` | The URI scheme identifying the used protocol: `"http"` or `"https"` | Defined later. | | `http.status_code` | [HTTP response status code][]. E.g. `200` (integer) | `Conditionally Required` if and only if one was received/sent. | -| `http.status_text` | [HTTP reason phrase][]. E.g. `"OK"` | `Recommended` | +| `http.status_text` | [HTTP reason phrase][]. E.g. `"OK"` | `Recommended` | Experimental | | `http.flavor` | Kind of HTTP protocol used: `"1.0"`, `"1.1"`, `"2"`, `"SPDY"` or `"QUIC"`. | No | -| `http.user_agent` | Value of the HTTP [User-Agent][] header sent by the client. | `Recommended` | +| `http.user_agent` | Value of the HTTP [User-Agent][] header sent by the client. | `Recommended` | Experimental | diff --git a/semantic-conventions/src/tests/data/markdown/sorting/expected.md b/semantic-conventions/src/tests/data/markdown/sorting/expected.md index 7e699905..f1f73b2a 100644 --- a/semantic-conventions/src/tests/data/markdown/sorting/expected.md +++ b/semantic-conventions/src/tests/data/markdown/sorting/expected.md @@ -1,12 +1,12 @@ # Attributes -| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | -|---|---|---|---|---| -| `aaa.aaa` | string | the 1st attribute | `aaa` | `Recommended` | -| `mmm.bbb` | string | the 2nd attribute | `bbb` | `Recommended` | -| `mmm.ccc.` | string | the 3rd attribute | ``mmm.ccc="ccc"`` | `Recommended` | -| `nnn.nnn` | string | the 4th attribute | `nnn` | `Recommended` | -| `zzz.xxx` | string | the 5th attribute | `xxx` | `Recommended` | -| `zzz.yyy` | string | the 6th attribute | `yyy` | `Recommended` | +| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | +|---|---|---|---|---|---| +| `aaa.aaa` | string | the 1st attribute | `aaa` | `Recommended` | Experimental | +| `mmm.bbb` | string | the 2nd attribute | `bbb` | `Recommended` | Experimental | +| `mmm.ccc.` | string | the 3rd attribute | ``mmm.ccc="ccc"`` | `Recommended` | Experimental | +| `nnn.nnn` | string | the 4th attribute | `nnn` | `Recommended` | Experimental | +| `zzz.xxx` | string | the 5th attribute | `xxx` | `Recommended` | Experimental | +| `zzz.yyy` | string | the 6th attribute | `yyy` | `Recommended` | Experimental | diff --git a/semantic-conventions/src/tests/data/markdown/spec_version/expected.md b/semantic-conventions/src/tests/data/markdown/spec_version/expected.md index 3ba03a0a..cab51560 100644 --- a/semantic-conventions/src/tests/data/markdown/spec_version/expected.md +++ b/semantic-conventions/src/tests/data/markdown/spec_version/expected.md @@ -2,6 +2,6 @@ | Attribute | [Type](https://github.com/open-telemetry/opentelemetry-specification/blob/v1.26.0/specification/common/README.md#attribute) | Description | Examples | [Requirement Level](https://github.com/open-telemetry/opentelemetry-specification/blob/v1.26.0/specification/common/attribute-requirement-level.md) | -|---|---|---|---|---| +|---|---|---|---|---|---| | `foo.bar` | string | Attribute 1 | `baz` | `Recommended` if available | diff --git a/semantic-conventions/src/tests/data/markdown/stability/all_badges_expected.md b/semantic-conventions/src/tests/data/markdown/stability/all_badges_expected.md index 21578858..de658878 100644 --- a/semantic-conventions/src/tests/data/markdown/stability/all_badges_expected.md +++ b/semantic-conventions/src/tests/data/markdown/stability/all_badges_expected.md @@ -1,65 +1,65 @@ -| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | -|---|---|---|---|---| -| [`test.deprecated_experimental_attr`](stable_badges_expected.md) | boolean | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
| | `Required` | -| [`test.deprecated_stable_attr`](stable_badges_expected.md) | boolean | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
| | `Required` | -| [`test.exp_attr`](stable_badges_expected.md) | boolean | ![Experimental](https://img.shields.io/badge/-experimental-blue)
| | `Required` | -| [`test.stable_attr`](stable_badges_expected.md) | boolean | ![Stable](https://img.shields.io/badge/-stable-lightgreen)
| | `Required` | -| [`test.stable_enum_attr`](stable_badges_expected.md) | string | ![Stable](https://img.shields.io/badge/-stable-lightgreen)
| `one` | `Recommended` | +| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | +|---|---|---|---|---|---| +| [`test.deprecated_experimental_attr`](stable_badges_expected.md) | boolean | | | `Required` | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Removed. | +| [`test.deprecated_stable_attr`](stable_badges_expected.md) | boolean | | | `Required` | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Removed. | +| [`test.exp_attr`](stable_badges_expected.md) | boolean | | | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`test.stable_attr`](stable_badges_expected.md) | boolean | | | `Required` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| [`test.stable_enum_attr`](stable_badges_expected.md) | string | | `one` | `Recommended` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `test.stable_enum_attr` MUST be one of the following: -| Value | Description | -|---|---| -| `one` | ![Stable](https://img.shields.io/badge/-stable-lightgreen)
member one | -| `two` | ![Experimental](https://img.shields.io/badge/-experimental-blue)
member two | -| `three` | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
member three | -| `four` | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
member four | +| Value | Description | Stability | +|---|---|---| +| `one` | member one | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| `two` | member two | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `three` | member three | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Removed. | +| `four` | member four | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Removed. | -| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | -|---|---|---|---|---| -| [`test.deprecated_experimental_attr`](stable_badges_expected.md) | boolean | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
| | `Required` | -| [`test.deprecated_stable_attr`](stable_badges_expected.md) | boolean | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
| | `Required` | -| [`test.exp_attr`](stable_badges_expected.md) | boolean | ![Experimental](https://img.shields.io/badge/-experimental-blue)
| | `Required` | -| [`test.stable_attr`](stable_badges_expected.md) | boolean | ![Stable](https://img.shields.io/badge/-stable-lightgreen)
| | `Required` | -| [`test.stable_enum_attr`](stable_badges_expected.md) | string | ![Stable](https://img.shields.io/badge/-stable-lightgreen)
| `one` | `Recommended` | +| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | +|---|---|---|---|---|---| +| [`test.deprecated_experimental_attr`](stable_badges_expected.md) | boolean | | | `Required` | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Removed. | +| [`test.deprecated_stable_attr`](stable_badges_expected.md) | boolean | | | `Required` | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Removed. | +| [`test.exp_attr`](stable_badges_expected.md) | boolean | | | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`test.stable_attr`](stable_badges_expected.md) | boolean | | | `Required` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| [`test.stable_enum_attr`](stable_badges_expected.md) | string | | `one` | `Recommended` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | -| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | -|---|---|---|---|---| -| [`test.deprecated_experimental_attr`](stable_badges_expected.md) | boolean | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
| | `Required` | -| [`test.deprecated_stable_attr`](stable_badges_expected.md) | boolean | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
| | `Required` | -| [`test.exp_attr`](stable_badges_expected.md) | boolean | ![Experimental](https://img.shields.io/badge/-experimental-blue)
| | `Required` | -| [`test.stable_attr`](stable_badges_expected.md) | boolean | ![Stable](https://img.shields.io/badge/-stable-lightgreen)
| | `Required` | -| [`test.stable_enum_attr`](stable_badges_expected.md) | string | ![Stable](https://img.shields.io/badge/-stable-lightgreen)
| `one` | `Recommended` | +| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | +|---|---|---|---|---|---| +| [`test.deprecated_experimental_attr`](stable_badges_expected.md) | boolean | | | `Required` | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Removed. | +| [`test.deprecated_stable_attr`](stable_badges_expected.md) | boolean | | | `Required` | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Removed. | +| [`test.exp_attr`](stable_badges_expected.md) | boolean | | | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`test.stable_attr`](stable_badges_expected.md) | boolean | | | `Required` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| [`test.stable_enum_attr`](stable_badges_expected.md) | string | | `one` | `Recommended` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `test.stable_enum_attr` MUST be one of the following: -| Value | Description | -|---|---| -| `one` | ![Stable](https://img.shields.io/badge/-stable-lightgreen)
member one | -| `two` | ![Experimental](https://img.shields.io/badge/-experimental-blue)
member two | -| `three` | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
member three | -| `four` | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
member four | +| Value | Description | Stability | +|---|---|---| +| `one` | member one | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| `two` | member two | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `three` | member three | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Removed. | +| `four` | member four | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Removed. | -| Name | Instrument Type | Unit (UCUM) | Description | -| -------- | --------------- | ----------- | -------------- | -| `stable_metric` | Histogram | `s` | ![Stable](https://img.shields.io/badge/-stable-lightgreen)
stable_metric | +| Name | Instrument Type | Unit (UCUM) | Description | Stability | +| -------- | --------------- | ----------- | -------------- | --------- | +| `stable_metric` | Histogram | `s` | stable_metric | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | -| Name | Instrument Type | Unit (UCUM) | Description | -| -------- | --------------- | ----------- | -------------- | -| `experimental_metric` | Counter | `{e}` | ![Experimental](https://img.shields.io/badge/-experimental-blue)
experimental_metric | +| Name | Instrument Type | Unit (UCUM) | Description | Stability | +| -------- | --------------- | ----------- | -------------- | --------- | +| `experimental_metric` | Counter | `{e}` | experimental_metric | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| Name | Instrument Type | Unit (UCUM) | Description | -| -------- | --------------- | ----------- | -------------- | -| `deprecated_metric` | UpDownCounter | `{d}` | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
deprecated_metric | +| Name | Instrument Type | Unit (UCUM) | Description | Stability | +| -------- | --------------- | ----------- | -------------- | --------- | +| `deprecated_metric` | UpDownCounter | `{d}` | deprecated_metric | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Removed. | \ No newline at end of file diff --git a/semantic-conventions/src/tests/data/markdown/stability/stable_badges_expected.md b/semantic-conventions/src/tests/data/markdown/stability/stable_badges_expected.md index 42717ce6..4ee1e6db 100644 --- a/semantic-conventions/src/tests/data/markdown/stability/stable_badges_expected.md +++ b/semantic-conventions/src/tests/data/markdown/stability/stable_badges_expected.md @@ -1,65 +1,65 @@ -| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | -|---|---|---|---|---| -| [`test.deprecated_experimental_attr`](stable_badges_expected.md) | boolean | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
| | `Required` | -| [`test.deprecated_stable_attr`](stable_badges_expected.md) | boolean | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
| | `Required` | -| [`test.exp_attr`](stable_badges_expected.md) | boolean | | | `Required` | -| [`test.stable_attr`](stable_badges_expected.md) | boolean | ![Stable](https://img.shields.io/badge/-stable-lightgreen)
| | `Required` | -| [`test.stable_enum_attr`](stable_badges_expected.md) | string | ![Stable](https://img.shields.io/badge/-stable-lightgreen)
| `one` | `Recommended` | +| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | +|---|---|---|---|---|---| +| [`test.deprecated_experimental_attr`](stable_badges_expected.md) | boolean | | | `Required` | Deprecated: Removed. | +| [`test.deprecated_stable_attr`](stable_badges_expected.md) | boolean | | | `Required` | Deprecated: Removed. | +| [`test.exp_attr`](stable_badges_expected.md) | boolean | | | `Required` | Experimental | +| [`test.stable_attr`](stable_badges_expected.md) | boolean | | | `Required` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| [`test.stable_enum_attr`](stable_badges_expected.md) | string | | `one` | `Recommended` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `test.stable_enum_attr` MUST be one of the following: -| Value | Description | -|---|---| -| `one` | ![Stable](https://img.shields.io/badge/-stable-lightgreen)
member one | -| `two` | member two | -| `three` | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
member three | -| `four` | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
member four | +| Value | Description | Stability | +|---|---|---| +| `one` | member one | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| `two` | member two | Experimental | +| `three` | member three | Deprecated: Removed. | +| `four` | member four | Deprecated: Removed. | -| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | -|---|---|---|---|---| -| [`test.deprecated_experimental_attr`](stable_badges_expected.md) | boolean | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
| | `Required` | -| [`test.deprecated_stable_attr`](stable_badges_expected.md) | boolean | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
| | `Required` | -| [`test.exp_attr`](stable_badges_expected.md) | boolean | | | `Required` | -| [`test.stable_attr`](stable_badges_expected.md) | boolean | ![Stable](https://img.shields.io/badge/-stable-lightgreen)
| | `Required` | -| [`test.stable_enum_attr`](stable_badges_expected.md) | string | ![Stable](https://img.shields.io/badge/-stable-lightgreen)
| `one` | `Recommended` | +| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | +|---|---|---|---|---|---| +| [`test.deprecated_experimental_attr`](stable_badges_expected.md) | boolean | | | `Required` | Deprecated: Removed. | +| [`test.deprecated_stable_attr`](stable_badges_expected.md) | boolean | | | `Required` | Deprecated: Removed. | +| [`test.exp_attr`](stable_badges_expected.md) | boolean | | | `Required` | Experimental | +| [`test.stable_attr`](stable_badges_expected.md) | boolean | | | `Required` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| [`test.stable_enum_attr`](stable_badges_expected.md) | string | | `one` | `Recommended` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | -| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | -|---|---|---|---|---| -| [`test.deprecated_experimental_attr`](stable_badges_expected.md) | boolean | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
| | `Required` | -| [`test.deprecated_stable_attr`](stable_badges_expected.md) | boolean | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
| | `Required` | -| [`test.exp_attr`](stable_badges_expected.md) | boolean | | | `Required` | -| [`test.stable_attr`](stable_badges_expected.md) | boolean | ![Stable](https://img.shields.io/badge/-stable-lightgreen)
| | `Required` | -| [`test.stable_enum_attr`](stable_badges_expected.md) | string | ![Stable](https://img.shields.io/badge/-stable-lightgreen)
| `one` | `Recommended` | +| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | +|---|---|---|---|---|---| +| [`test.deprecated_experimental_attr`](stable_badges_expected.md) | boolean | | | `Required` | Deprecated: Removed. | +| [`test.deprecated_stable_attr`](stable_badges_expected.md) | boolean | | | `Required` | Deprecated: Removed. | +| [`test.exp_attr`](stable_badges_expected.md) | boolean | | | `Required` | Experimental | +| [`test.stable_attr`](stable_badges_expected.md) | boolean | | | `Required` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| [`test.stable_enum_attr`](stable_badges_expected.md) | string | | `one` | `Recommended` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `test.stable_enum_attr` MUST be one of the following: -| Value | Description | -|---|---| -| `one` | ![Stable](https://img.shields.io/badge/-stable-lightgreen)
member one | -| `two` | member two | -| `three` | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
member three | -| `four` | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
member four | +| Value | Description | Stability | +|---|---|---| +| `one` | member one | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| `two` | member two | Experimental | +| `three` | member three | Deprecated: Removed. | +| `four` | member four | Deprecated: Removed. | -| Name | Instrument Type | Unit (UCUM) | Description | -| -------- | --------------- | ----------- | -------------- | -| `stable_metric` | Histogram | `s` | ![Stable](https://img.shields.io/badge/-stable-lightgreen)
stable_metric | +| Name | Instrument Type | Unit (UCUM) | Description | Stability | +| -------- | --------------- | ----------- | -------------- | --------- | +| `stable_metric` | Histogram | `s` | stable_metric | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | -| Name | Instrument Type | Unit (UCUM) | Description | -| -------- | --------------- | ----------- | -------------- | -| `experimental_metric` | Counter | `{e}` | experimental_metric | +| Name | Instrument Type | Unit (UCUM) | Description | Stability | +| -------- | --------------- | ----------- | -------------- | --------- | +| `experimental_metric` | Counter | `{e}` | experimental_metric | Experimental | -| Name | Instrument Type | Unit (UCUM) | Description | -| -------- | --------------- | ----------- | -------------- | -| `deprecated_metric` | UpDownCounter | `{d}` | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
deprecated_metric | +| Name | Instrument Type | Unit (UCUM) | Description | Stability | +| -------- | --------------- | ----------- | -------------- | --------- | +| `deprecated_metric` | UpDownCounter | `{d}` | deprecated_metric | Deprecated: Removed. | \ No newline at end of file diff --git a/semantic-conventions/src/tests/data/markdown/wrong_semconv_id/input.md b/semantic-conventions/src/tests/data/markdown/wrong_semconv_id/input.md index 30656e50..a5f2b958 100644 --- a/semantic-conventions/src/tests/data/markdown/wrong_semconv_id/input.md +++ b/semantic-conventions/src/tests/data/markdown/wrong_semconv_id/input.md @@ -5,15 +5,15 @@ | Attribute name | Notes and examples | `Required`? | | :------------- | :----------------------------------------------------------- | --------- | -| `http.method` | HTTP request method. E.g. `"GET"`. | `Required` | +| `http.method` | HTTP request method. E.g. `"GET"`. | `Required` | Experimental | | `http.url` | 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. | Defined later. | | `http.target` | The full request target as passed in a [HTTP request line][] or equivalent, e.g. `"/path/12314/?q=ddds#123"`. | Defined later. | | `http.host` | The value of the [HTTP host header][]. When the header is empty or not present, this attribute should be the same. | Defined later. | | `http.scheme` | The URI scheme identifying the used protocol: `"http"` or `"https"` | Defined later. | | `http.status_code` | [HTTP response status code][]. E.g. `200` (integer) | `Conditionally Required` if and only if one was received/sent. | -| `http.status_text` | [HTTP reason phrase][]. E.g. `"OK"` | `Recommended` | +| `http.status_text` | [HTTP reason phrase][]. E.g. `"OK"` | `Recommended` | Experimental | | `http.flavor` | Kind of HTTP protocol used: `"1.0"`, `"1.1"`, `"2"`, `"SPDY"` or `"QUIC"`. | No | -| `http.user_agent` | Value of the HTTP [User-Agent][] header sent by the client. | `Recommended` | +| `http.user_agent` | Value of the HTTP [User-Agent][] header sent by the client. | `Recommended` | Experimental | It is recommended to also use the general [network attributes][], especially `net.peer.ip`. If `net.transport` is not specified, it can be assumed to be `IP.TCP` except if `http.flavor` is `QUIC`, in which case `IP.UDP` is assumed. diff --git a/semantic-conventions/src/tests/semconv/templating/test_markdown.py b/semantic-conventions/src/tests/semconv/templating/test_markdown.py index 0fd047d9..5c84c440 100644 --- a/semantic-conventions/src/tests/semconv/templating/test_markdown.py +++ b/semantic-conventions/src/tests/semconv/templating/test_markdown.py @@ -40,19 +40,16 @@ def testDeprecated(self): def testStableBadges(self): self.check( "markdown/stability/", - MarkdownOptions(enable_stable=True, use_badge=True), + MarkdownOptions( + disable_deprecated_badge=True, disable_experimental_badge=True + ), expected_name="stable_badges_expected.md", ) def testExperimentalAndStableBadges(self): self.check( "markdown/stability/", - MarkdownOptions( - enable_stable=True, - enable_experimental=True, - enable_deprecated=True, - use_badge=True, - ), + MarkdownOptions(), expected_name="all_badges_expected.md", ) @@ -245,7 +242,11 @@ def testColoredVisualDiffer(self): def check( self, input_dir: str, - options=MarkdownOptions(), + options=MarkdownOptions( + disable_experimental_badge=True, + disable_deprecated_badge=True, + disable_stable_badge=True, + ), *, expected_name="expected.md", extra_yaml_dirs: Sequence[str] = (), @@ -287,6 +288,7 @@ def do_render(): return ex.exception do_render() result = output.getvalue() + print(result) assert result == (dirpath / expected_name).read_text(encoding="utf-8") return None