From 28d02cc310d9c789b5faac58f9939bf735adadb5 Mon Sep 17 00:00:00 2001 From: Joao Grassi Date: Fri, 30 Sep 2022 18:05:54 +0200 Subject: [PATCH 1/2] Make messaging context propagation requirements explicit (#2750) --- CHANGELOG.md | 2 + .../trace/semantic_conventions/messaging.md | 60 +++++++++++++++++++ 2 files changed, 62 insertions(+) diff --git a/CHANGELOG.md b/CHANGELOG.md index 66599ff02fb..f10490a9ae8 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -34,6 +34,8 @@ release. ([#2706](https://github.com/open-telemetry/opentelemetry-specification/pull/2706)) - Add exceptions to the logs semantic conventions ([#2819](https://github.com/open-telemetry/opentelemetry-specification/pull/2819)) +- Make context propagation requirements explicit for messaging semantic conventions + ([#2750](https://github.com/open-telemetry/opentelemetry-specification/pull/2750)). ### Compatibility diff --git a/specification/trace/semantic_conventions/messaging.md b/specification/trace/semantic_conventions/messaging.md index 831165d9859..0c7d8eec90f 100644 --- a/specification/trace/semantic_conventions/messaging.md +++ b/specification/trace/semantic_conventions/messaging.md @@ -7,11 +7,16 @@ - [Definitions](#definitions) + * [Message](#message) + * [Producer](#producer) + * [Consumer](#consumer) + * [Intermediary](#intermediary) * [Destinations](#destinations) * [Message consumption](#message-consumption) * [Conversations](#conversations) * [Temporary destinations](#temporary-destinations) - [Conventions](#conventions) + * [Context propagation](#context-propagation) * [Span name](#span-name) * [Span kind](#span-kind) * [Operation names](#operation-names) @@ -30,6 +35,8 @@ ## Definitions +### Message + Although messaging systems are not as standardized as, e.g., HTTP, it is assumed that the following definitions are applicable to most of them that have similar concepts at all (names borrowed mostly from JMS): A *message* is an envelope with a potentially empty payload. @@ -43,6 +50,27 @@ With Apache Kafka, the physical broker a message is written to depends on the nu Messages can be delivered to 0, 1, or multiple consumers depending on the dispatching semantic of the protocol. +### Producer + +The "producer" is a specific instance, process or device that creates and +publishes a message. "Publishing" is the process of sending a message or batch +of messages to the intermediary or consumer. + +### Consumer + +A "consumer" receives the message and acts upon it. It uses the context and +data to execute some logic, which might lead to the occurrence of new events. + +The consumer receives, processes, and settles a message. "Receiving" is the +process of obtaining a message from the intermediary, "processing" is the +process of acting on the information a message contains, "settling" is the +process of notifying an intermediary that a message was processed successfully. + +### Intermediary + +An "intermediary" receives a message to forward it to the next receiver, which +might be another intermediary or a consumer. + ### Destinations A destination is usually identified by some name unique within the messaging system instance, which might look like a URL or a simple one-word identifier. @@ -80,6 +108,38 @@ Often such destinations are unnamed or have an auto-generated name. Given these definitions, the remainder of this section describes the semantic conventions for Spans describing interactions with messaging systems. +### Context propagation + +A message may traverse many different components and layers in one or more intermediaries +when it is propagated from the producer to the consumer(s). To be able to correlate +consumer traces with producer traces using the existing context propagation mechanisms, +all components must propagate context down the chain. + +Messaging systems themselves may trace messages as the messages travels from +producers to consumers. Such tracing would cover the transport layer but would +not help in correlating producers with consumers. To be able to directly +correlate producers with consumers, another context that is propagated with +the message is required. + +A message *creation context* allows correlating producers with consumers +of a message and model the dependencies between them, +regardless of the underlying messaging transport mechanism and its instrumentation. + +The message creation context is created by the producer and should be propagated +to the consumer(s). Consumer traces cannot be directly correlated with producer +traces if the message creation context is not attached and propagated with the message. + +A producer SHOULD attach a message creation context to each message. +If possible, the message creation context SHOULD be attached +in such a way that it cannot be changed by intermediaries. + +> This document does not specify the exact mechanisms on how the creation context +> is attached/extracted to/from messages. Future versions of these conventions +> will give clear recommendations, following industry standards including, but not limited to +> [Trace Context: AMQP protocol](https://w3c.github.io/trace-context-amqp/) and +> [Trace Context: MQTT protocol](https://w3c.github.io/trace-context-mqtt/) +> once those standards reach a stable state. + ### Span name The span name SHOULD be set to the message destination name and the operation being performed in the following format: From ce32f948d2f6a78d95fd87f0d945513ee2a0d0aa Mon Sep 17 00:00:00 2001 From: jack-berg <34418638+jack-berg@users.noreply.github.com> Date: Mon, 3 Oct 2022 13:16:31 -0500 Subject: [PATCH 2/2] Fix inconsistent metric usage of http.target (#2818) --- CHANGELOG.md | 3 ++ .../semantic_conventions/http-metrics.md | 48 ++++++------------- 2 files changed, 17 insertions(+), 34 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index f10490a9ae8..4329675ca41 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -36,6 +36,9 @@ release. ([#2819](https://github.com/open-telemetry/opentelemetry-specification/pull/2819)) - Make context propagation requirements explicit for messaging semantic conventions ([#2750](https://github.com/open-telemetry/opentelemetry-specification/pull/2750)). +- Update http metrics to use `http.route` instead of `http.target` for servers, + drop `http.url` for clients + ([#2818](https://github.com/open-telemetry/opentelemetry-specification/pull/2818)). ### Compatibility diff --git a/specification/metrics/semantic_conventions/http-metrics.md b/specification/metrics/semantic_conventions/http-metrics.md index f9c9d8a6552..db636dc41c6 100644 --- a/specification/metrics/semantic_conventions/http-metrics.md +++ b/specification/metrics/semantic_conventions/http-metrics.md @@ -43,17 +43,20 @@ Below is a table of HTTP client metric instruments. Below is a table of the attributes that SHOULD be included on `duration` and `size` metric events and whether they should be on server, client, or both types of HTTP metric events: -| Name | Type | Requirement Level | Notes and examples | -|----------------------|---------------------|--------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| `http.method` | `client` & `server` | Required | The HTTP request method. E.g. `"GET"` | -| `http.scheme` | `server` | Required | The URI scheme identifying the used protocol in lowercase: `"http"` or `"https"` | -| `http.status_code` | `client` & `server` | Conditionally Required: if and only if one was received/sent. | [HTTP response status code][]. E.g. `200` (String) | -| `http.flavor` | `client` & `server` | Recommended | Kind of HTTP protocol used: `"1.0"`, `"1.1"`, `"2"`, `"SPDY"` or `"QUIC"`. | -| `net.peer.name` | `client` | Required | Host identifier of the ["URI origin"](https://www.rfc-editor.org/rfc/rfc9110.html#name-uri-origin) HTTP request is sent to. | -| `net.peer.port` | `client` | Conditionally Required: If not default (`80` for `http`, `443` for `https`). | Port identifier of the ["URI origin"](https://www.rfc-editor.org/rfc/rfc9110.html#name-uri-origin) HTTP request is sent to. | -| `net.sock.peer.addr` | `client` | Recommended | See [general network connection attributes](../../trace/semantic_conventions/span-general.md#general-network-connection-attributes) | -| `net.host.name` | `server` | Required | Host of the local HTTP server that received the request. | -| `net.host.port` | `server` | Conditionally Required: If not default (`80` for `http`, `443` for `https`). | Port of the local HTTP server that received the request. | +| Name | Type | Requirement Level | Notes and examples | +|----------------------|---------------------|------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------| +| `http.method` | `client` & `server` | Required | The HTTP request method. E.g. `"GET"` | +| `http.scheme` | `server` | Required | The URI scheme identifying the used protocol in lowercase: `"http"` or `"https"` | +| `http.route` | `server` | Conditionally Required: If and only if it's available | The matched route (path template in the format used by the respective server framework). See note below [1]. E.g. `"/path/{id}/?q={}"`. | +| `http.status_code` | `client` & `server` | Conditionally Required: if and only if one was received/sent. | [HTTP response status code][]. E.g. `200` (String) | +| `http.flavor` | `client` & `server` | Recommended | Kind of HTTP protocol used: `"1.0"`, `"1.1"`, `"2"`, `"SPDY"` or `"QUIC"`. | +| `net.peer.name` | `client` | Required | Host identifier of the ["URI origin"](https://www.rfc-editor.org/rfc/rfc9110.html#name-uri-origin) HTTP request is sent to. | +| `net.peer.port` | `client` | Conditionally Required: If not default (`80` for `http`, `443` for `https`). | Port identifier of the ["URI origin"](https://www.rfc-editor.org/rfc/rfc9110.html#name-uri-origin) HTTP request is sent to. | +| `net.sock.peer.addr` | `client` | Recommended | See [general network connection attributes](../../trace/semantic_conventions/span-general.md#general-network-connection-attributes) | +| `net.host.name` | `server` | Required | Host of the local HTTP server that received the request. | +| `net.host.port` | `server` | Conditionally Required: If not default (`80` for `http`, `443` for `https`). | Port of the local HTTP server that received the request. | + +**[1]:** '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. The following attributes SHOULD be included in the `http.server.active_requests` observation: @@ -67,26 +70,3 @@ The following attributes SHOULD be included in the `http.server.active_requests` [HTTP host header]: https://www.rfc-editor.org/rfc/rfc9110.html#name-host-and-authority [HTTP response status code]: https://www.rfc-editor.org/rfc/rfc9110.html#name-status-codes [HTTP reason phrase]: https://www.rfc-editor.org/rfc/rfc9110.html#section-15.1 - -### Parameterized attributes - -To avoid high cardinality the following attributes SHOULD substitute any parameters when added as attributes to http metric events as described below: - -| Attribute name | Type | Requirement Level | Notes and examples | -|----------------|---------|-------------------|--------------------------------------------------------------------------------------------------------| -| `http.url` | `client` | Required | The originally requested URL | -| `http.target` | `server` | Required | The full request target as passed in a [HTTP request target][] or equivalent, e.g. `"/path/{id}/?q={}"`. | - -[Http request target]: https://www.rfc-editor.org/rfc/rfc9110.html#name-determining-the-target-reso - -Many REST APIs encode parameters into the URI path, e.g. `/api/users/123` where `123` -is a user id, which creates high cardinality value space not suitable for attributes on metric events. -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 attribute values. However, the same approach usually -does not work for HTTP client attributes, 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 attributes SHOULD be using conservative, low -cardinality names formed from the available parameters of an HTTP request, -such as `"HTTP {METHOD_NAME}"`. These attributes MUST NOT default to using URI -path.