Skip to content

Commit

Permalink
Merge branch 'main' into add-process-disk-operations-metric
Browse files Browse the repository at this point in the history
  • Loading branch information
@andrzej-stencel
andrzej-stencel committed Oct 4, 2022
2 parents 84d7490 + ce32f94 commit f6ba2ae
Show file tree
Hide file tree
Showing 3 changed files with 79 additions and 34 deletions.
5 changes: 5 additions & 0 deletions CHANGELOG.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -34,6 +34,11 @@ 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)).
- 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)).
- Add `process.disk.operations` metric to semantic conventions
([#2845](https://github.com/open-telemetry/opentelemetry-specification/pull/2845))

Expand Down
48 changes: 14 additions & 34 deletions specification/metrics/semantic_conventions/http-metrics.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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:

Expand All @@ -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.
60 changes: 60 additions & 0 deletions specification/trace/semantic_conventions/messaging.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -7,11 +7,16 @@
<!-- toc -->

- [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)
Expand All @@ -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.
Expand All @@ -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.
Expand Down Expand Up @@ -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:
Expand Down

0 comments on commit f6ba2ae

Please sign in to comment.