From f83682351b00c0ea269bbdcafff4aa2c7e55f3f9 Mon Sep 17 00:00:00 2001 From: Liudmila Molkova Date: Thu, 28 Apr 2022 10:26:14 -0700 Subject: [PATCH] linters --- semantic_conventions/README.md | 2 +- semantic_conventions/trace/http.yaml | 16 +++++----------- specification/common/README.md | 2 ++ .../common/attribute-requirement-level.md | 3 +-- .../trace/semantic_conventions/http.md | 17 ++++++++++++++++- 5 files changed, 25 insertions(+), 15 deletions(-) diff --git a/semantic_conventions/README.md b/semantic_conventions/README.md index 1afd7e98724..24d4ab045b1 100644 --- a/semantic_conventions/README.md +++ b/semantic_conventions/README.md @@ -15,7 +15,7 @@ i.e.: ## Writing semantic conventions Semantic conventions for the spec MUST adhere to the -[attribute naming conventions](../specification/common/attribute-naming.md). +[attribute naming](../specification/common/attribute-naming.md) and [requirement level](../specification/common/attribute-requirement-level.md) conventions. Refer to the [syntax](https://github.com/open-telemetry/build-tools/tree/v0.11.0/semantic-conventions/syntax.md) for how to write the YAML files for semantic conventions and what the YAML properties mean. diff --git a/semantic_conventions/trace/http.yaml b/semantic_conventions/trace/http.yaml index 54d891330c3..ddc41c16110 100644 --- a/semantic_conventions/trace/http.yaml +++ b/semantic_conventions/trace/http.yaml @@ -88,19 +88,16 @@ groups: - ref: net.peer.name required: always sampling_relevant: true - note: > + note: | Best known HTTP remote hostname is identified according with the following order: - - Host header - - Host component of the absolute [Request-URL](https://www.w3.org/Protocols/rfc2616/rfc2616-sec5.html) - MUST NOT be set if capturing it would require an extra DNS lookup. - ref: net.peer.port required: - conditional: if not default (`80` for `http`` scheme, `443` for `https`). + conditional: if not default (`80` for `http` scheme, `443` for `https`). sampling_relevant: true - id: retry_count type: int @@ -126,14 +123,11 @@ groups: required: always sampling_relevant: true brief: The best known HTTP server name, see note below - note: > + note: | Best known HTTP server name is identified according with the following order: - - The primary server name of the matched virtual host. This should be obtained via configuration. - - `Host` header - - Host component of the absolute [Request-URL](https://www.w3.org/Protocols/rfc2616/rfc2616-sec5.html) - ref: net.host.port required: @@ -152,7 +146,7 @@ groups: brief: > The matched route (path template in the format used by the respective server framework). See note below examples: ['/users/:userID?', '{controller}/{action}/{id?}'] - note: > + note: > 'http.route' MUST NOT be populated when this is not supported by the HTTP server framework as the route attribute should have low-cardinality and the URI path can NOT substitute it. - id: client_ip type: string @@ -174,4 +168,4 @@ groups: examples: '83.164.160.102' - ref: net.peer.port - ref: net.host.ip - required: opt-in \ No newline at end of file + required: opt-in diff --git a/specification/common/README.md b/specification/common/README.md index 6c3e80a527c..18d46fe00c3 100644 --- a/specification/common/README.md +++ b/specification/common/README.md @@ -51,6 +51,8 @@ both containing an array of strings to represent a mapping See [Attribute Naming](attribute-naming.md) for naming guidelines. +See [Requirement Level](attribute-requirement-level.md) for requirement levels guidelines. + See [this document](attribute-type-mapping.md) to find out how to map values obtained outside OpenTelemetry into OpenTelemetry attribute values. diff --git a/specification/common/attribute-requirement-level.md b/specification/common/attribute-requirement-level.md index bb349b84ad3..b735daeab22 100644 --- a/specification/common/attribute-requirement-level.md +++ b/specification/common/attribute-requirement-level.md @@ -6,8 +6,7 @@ Table of Contents -- [Attribute Requirement Level](#attribute-requirement-level) - - [Performance considerations](#performance-considerations) +- [Performance considerations](#performance-considerations) diff --git a/specification/trace/semantic_conventions/http.md b/specification/trace/semantic_conventions/http.md index 09a7c323553..406b4cc3064 100644 --- a/specification/trace/semantic_conventions/http.md +++ b/specification/trace/semantic_conventions/http.md @@ -10,6 +10,19 @@ and various HTTP versions like 1.1, 2 and SPDY. +- [Name](#name) +- [Status](#status) +- [Common Attributes](#common-attributes) + * [HTTP request and response headers](#http-request-and-response-headers) +- [HTTP client](#http-client) + * [HTTP request retries and redirects](#http-request-retries-and-redirects) +- [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) +- [HTTP retries examples](#http-retries-examples) +- [HTTP redirects examples](#http-redirects-examples) + ## Name @@ -106,7 +119,7 @@ before any HTTP-redirects that may happen when executing the request. | `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. [1] | `https://www.foo.bar/search?q=OpenTelemetry#SemConv` | Yes | | `http.retry_count` | int | The ordinal number of request re-sending attempt. | `3` | Recommended if and only if request was retried. | | [`net.peer.name`](span-general.md) | string | Remote hostname or similar, see note below. [2] | `example.com` | Yes | -| [`net.peer.port`](span-general.md) | int | Remote port number. | `80`; `8080`; `443` | Required if not default. | +| [`net.peer.port`](span-general.md) | int | Remote port number. | `80`; `8080`; `443` | Required conditionally [3] | **[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/`. @@ -117,6 +130,8 @@ before any HTTP-redirects that may happen when executing the request. MUST NOT be set if capturing it would require an extra DNS lookup. +**[3]:** if not default (`80` for `http` scheme, `443` for `https`). + Following attributes MUST be provided **at span creation time** (when provided at all), so they can be considered for sampling decisions: * `http.url`