From 981b8a6fd5e913648c581199510b6707a38aa2cd Mon Sep 17 00:00:00 2001 From: Liudmila Molkova Date: Thu, 17 Aug 2023 09:59:36 -0700 Subject: [PATCH 1/9] use original method as HTTP span name --- docs/http/http-spans.md | 17 ++++++++++++----- 1 file changed, 12 insertions(+), 5 deletions(-) diff --git a/docs/http/http-spans.md b/docs/http/http-spans.md index 7ea7529359..4fe5590c77 100644 --- a/docs/http/http-spans.md +++ b/docs/http/http-spans.md @@ -62,13 +62,20 @@ and various HTTP versions like 1.1, 2 and SPDY. ## Name HTTP spans MUST follow the overall [guidelines for span names](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.22.0/specification/trace/api.md#span). -HTTP server span names SHOULD be `{http.request.method} {http.route}` if there is a + +HTTP server span names SHOULD be `{method} {http.route}` if there is a (low-cardinality) `http.route` available. -HTTP server span names SHOULD be `{http.request.method}` if there is no (low-cardinality) -`http.route` available. + +If there is no (low-cardinality) `http.route` available, HTTP server span names +SHOULD match `{method}` + HTTP client spans have no `http.route` attribute since client-side instrumentation -is not generally aware of the "route", and therefore HTTP client spans SHOULD use -`{http.request.method}`. +is not generally aware of the "route", and therefore HTTP client spans SHOULD be +`{method}`. + +The `{method}` in all cases SHOULD be `{http.request.method_original}` when the original method +is available and `{http.request.method}` otherwise. + 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. From 0502f44b2bbe7386a723511201a8202ef1c1f2f3 Mon Sep 17 00:00:00 2001 From: Liudmila Molkova Date: Tue, 22 Aug 2023 13:19:44 -0700 Subject: [PATCH 2/9] fallback to HTTP instead of _OTHER --- docs/http/http-spans.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/http/http-spans.md b/docs/http/http-spans.md index 4fe5590c77..2706ce6cb9 100644 --- a/docs/http/http-spans.md +++ b/docs/http/http-spans.md @@ -64,7 +64,7 @@ and various HTTP versions like 1.1, 2 and SPDY. HTTP spans MUST follow the overall [guidelines for span names](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.22.0/specification/trace/api.md#span). HTTP server span names SHOULD be `{method} {http.route}` if there is a -(low-cardinality) `http.route` available. +(low-cardinality) `http.route` available, If there is no (low-cardinality) `http.route` available, HTTP server span names SHOULD match `{method}` @@ -73,8 +73,8 @@ HTTP client spans have no `http.route` attribute since client-side instrumentati is not generally aware of the "route", and therefore HTTP client spans SHOULD be `{method}`. -The `{method}` in all cases SHOULD be `{http.request.method_original}` when the original method -is available and `{http.request.method}` otherwise. +The `{method}` SHOULD be `{http.request.method}` if method represents original method known to the instrumentation. +In other cases (when `{http.request.method}` is set to `OTHER`), `{method}` SHOULD match `HTTP`. Instrumentation MUST NOT default to using URI path as span name, but MAY provide hooks to allow custom logic to override the From 1f229c79692a71288e49f7920b50e2587b50e9e5 Mon Sep 17 00:00:00 2001 From: Liudmila Molkova Date: Tue, 22 Aug 2023 13:26:03 -0700 Subject: [PATCH 3/9] changelog --- CHANGELOG.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/CHANGELOG.md b/CHANGELOG.md index 6faafa19c4..a28bde0de4 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -59,6 +59,8 @@ release. ([#252](https://github.com/open-telemetry/semantic-conventions/pull/252)) - Simplify HTTP metric briefs. ([#276](https://github.com/open-telemetry/semantic-conventions/pull/276)) +- BREAKING: Change HTTP span name when method is unknown (use `HTTP` instead of `_OTHER`) + ([#270](https://github.com/open-telemetry/semantic-conventions/pull/270)) ## v1.21.0 (2023-07-13) From 52a588cdb96ec5f2b7de03fe08aad3a47766deec Mon Sep 17 00:00:00 2001 From: Liudmila Molkova Date: Wed, 23 Aug 2023 12:21:55 -0700 Subject: [PATCH 4/9] Update docs/http/http-spans.md Co-authored-by: Trask Stalnaker --- docs/http/http-spans.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/http/http-spans.md b/docs/http/http-spans.md index 2706ce6cb9..29e1e9aa51 100644 --- a/docs/http/http-spans.md +++ b/docs/http/http-spans.md @@ -74,7 +74,7 @@ is not generally aware of the "route", and therefore HTTP client spans SHOULD be `{method}`. The `{method}` SHOULD be `{http.request.method}` if method represents original method known to the instrumentation. -In other cases (when `{http.request.method}` is set to `OTHER`), `{method}` SHOULD match `HTTP`. +In other cases (when `{http.request.method}` is set to `_OTHER`), `{method}` SHOULD match `HTTP`. Instrumentation MUST NOT default to using URI path as span name, but MAY provide hooks to allow custom logic to override the From 3356830323393ed4ccbf1a49fc94d1f49311df13 Mon Sep 17 00:00:00 2001 From: Liudmila Molkova Date: Wed, 23 Aug 2023 12:23:08 -0700 Subject: [PATCH 5/9] Update docs/http/http-spans.md Co-authored-by: Joao Grassi --- docs/http/http-spans.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/http/http-spans.md b/docs/http/http-spans.md index 29e1e9aa51..74cf05a82c 100644 --- a/docs/http/http-spans.md +++ b/docs/http/http-spans.md @@ -73,7 +73,7 @@ HTTP client spans have no `http.route` attribute since client-side instrumentati is not generally aware of the "route", and therefore HTTP client spans SHOULD be `{method}`. -The `{method}` SHOULD be `{http.request.method}` if method represents original method known to the instrumentation. +The `{method}` SHOULD be `{http.request.method}` if the method represents the original method known to the instrumentation. In other cases (when `{http.request.method}` is set to `_OTHER`), `{method}` SHOULD match `HTTP`. Instrumentation MUST NOT default to using URI From b4740ef9f207194b584611bec7d7aa72f79abbe3 Mon Sep 17 00:00:00 2001 From: Liudmila Molkova Date: Thu, 24 Aug 2023 13:57:39 -0700 Subject: [PATCH 6/9] Apply suggestions from code review MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Christian Neumüller --- docs/http/http-spans.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/http/http-spans.md b/docs/http/http-spans.md index 74cf05a82c..98a29b6170 100644 --- a/docs/http/http-spans.md +++ b/docs/http/http-spans.md @@ -63,11 +63,11 @@ and various HTTP versions like 1.1, 2 and SPDY. HTTP spans MUST follow the overall [guidelines for span names](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.22.0/specification/trace/api.md#span). -HTTP server span names SHOULD be `{method} {http.route}` if there is a +HTTP server span names SHOULD be `{method} {http.route}` (see below for the exact definition of the method placeholder) if there is a (low-cardinality) `http.route` available, If there is no (low-cardinality) `http.route` available, HTTP server span names -SHOULD match `{method}` +SHOULD be `{method}` (see below for the exact definition of the method placeholder) HTTP client spans have no `http.route` attribute since client-side instrumentation is not generally aware of the "route", and therefore HTTP client spans SHOULD be From a1f681feff2b5f49b3094b888968a068c67798ab Mon Sep 17 00:00:00 2001 From: Liudmila Molkova Date: Thu, 24 Aug 2023 14:00:04 -0700 Subject: [PATCH 7/9] more review comments --- docs/http/http-spans.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/http/http-spans.md b/docs/http/http-spans.md index 98a29b6170..d3abf48a99 100644 --- a/docs/http/http-spans.md +++ b/docs/http/http-spans.md @@ -63,18 +63,18 @@ and various HTTP versions like 1.1, 2 and SPDY. HTTP spans MUST follow the overall [guidelines for span names](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.22.0/specification/trace/api.md#span). -HTTP server span names SHOULD be `{method} {http.route}` (see below for the exact definition of the method placeholder) if there is a +HTTP server span names SHOULD be `{method} {http.route}` (see below for the exact definition of the `{method}` placeholder) if there is a (low-cardinality) `http.route` available, If there is no (low-cardinality) `http.route` available, HTTP server span names -SHOULD be `{method}` (see below for the exact definition of the method placeholder) +SHOULD be `{method}` (see below for the exact definition of the `{method}` placeholder) HTTP client spans have no `http.route` attribute since client-side instrumentation is not generally aware of the "route", and therefore HTTP client spans SHOULD be `{method}`. -The `{method}` SHOULD be `{http.request.method}` if the method represents the original method known to the instrumentation. -In other cases (when `{http.request.method}` is set to `_OTHER`), `{method}` SHOULD match `HTTP`. +The `{method}` MUST be `{http.request.method}` if the method represents the original method known to the instrumentation. +In other cases (when `{http.request.method}` is set to `_OTHER`), `{method}` MUST be `HTTP`. Instrumentation MUST NOT default to using URI path as span name, but MAY provide hooks to allow custom logic to override the From 88737ae2fe3f54acb3c5ee7c605f0c3d69e75d18 Mon Sep 17 00:00:00 2001 From: Liudmila Molkova Date: Tue, 5 Sep 2023 14:36:46 -0700 Subject: [PATCH 8/9] clean up --- docs/http/http-spans.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/http/http-spans.md b/docs/http/http-spans.md index d3abf48a99..9c490edbd4 100644 --- a/docs/http/http-spans.md +++ b/docs/http/http-spans.md @@ -63,17 +63,17 @@ and various HTTP versions like 1.1, 2 and SPDY. HTTP spans MUST follow the overall [guidelines for span names](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.22.0/specification/trace/api.md#span). -HTTP server span names SHOULD be `{method} {http.route}` (see below for the exact definition of the `{method}` placeholder) if there is a -(low-cardinality) `http.route` available, +HTTP server span names SHOULD be `{method} {http.route}` if there is a +(low-cardinality) `http.route` available (see below for the exact definition of the [`{method}`](#method-placeholder) placeholder). If there is no (low-cardinality) `http.route` available, HTTP server span names -SHOULD be `{method}` (see below for the exact definition of the `{method}` placeholder) +SHOULD be [`{method}`](#method-placeholder). HTTP client spans have no `http.route` attribute since client-side instrumentation is not generally aware of the "route", and therefore HTTP client spans SHOULD be -`{method}`. +[`{method}`](#method-placeholder). -The `{method}` MUST be `{http.request.method}` if the method represents the original method known to the instrumentation. +The `{method}` MUST be `{http.request.method}` if the method represents the original method known to the instrumentation. In other cases (when `{http.request.method}` is set to `_OTHER`), `{method}` MUST be `HTTP`. Instrumentation MUST NOT default to using URI From aaa4c89d7a1a59717f4197b337087bafb420ded4 Mon Sep 17 00:00:00 2001 From: Liudmila Molkova Date: Wed, 6 Sep 2023 14:33:02 -0700 Subject: [PATCH 9/9] update markdown link check version and disable local anchor link check --- docs/http/http-spans.md | 3 +++ package.json | 2 +- 2 files changed, 4 insertions(+), 1 deletion(-) diff --git a/docs/http/http-spans.md b/docs/http/http-spans.md index 9c490edbd4..b5d828c9e6 100644 --- a/docs/http/http-spans.md +++ b/docs/http/http-spans.md @@ -63,6 +63,8 @@ and various HTTP versions like 1.1, 2 and SPDY. HTTP spans MUST follow the overall [guidelines for span names](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.22.0/specification/trace/api.md#span). + + HTTP server span names SHOULD be `{method} {http.route}` if there is a (low-cardinality) `http.route` available (see below for the exact definition of the [`{method}`](#method-placeholder) placeholder). @@ -72,6 +74,7 @@ SHOULD be [`{method}`](#method-placeholder). HTTP client spans have no `http.route` attribute since client-side instrumentation is not generally aware of the "route", and therefore HTTP client spans SHOULD be [`{method}`](#method-placeholder). + The `{method}` MUST be `{http.request.method}` if the method represents the original method known to the instrumentation. In other cases (when `{http.request.method}` is set to `_OTHER`), `{method}` MUST be `HTTP`. diff --git a/package.json b/package.json index d51304272a..90d26767c2 100644 --- a/package.json +++ b/package.json @@ -11,7 +11,7 @@ "devDependencies": { "gulp": "^4.0.2", "js-yaml": "^4.1.0", - "markdown-link-check": "3.10.3", + "markdown-link-check": "^3.11.2", "markdown-toc": "^1.2.0", "markdownlint": "^0.29.0", "markdownlint-cli": "0.31.0",