diff --git a/docs/README.md b/docs/README.md index c3c5ef9..a4b2bf3 100644 --- a/docs/README.md +++ b/docs/README.md @@ -11,11 +11,20 @@ scheme that can be standardized across a codebase, libraries, and platforms. This allows easier correlation and consumption of data. Contrast standardizes on otel metrics and extend from them. See -[OTel Semantic Conventions](https://github.com/open-telemetry/semantic-conventions/tree/v1.22.0/docs) -for a foundational understanding of what we build on top of. +[OTel Semantic Conventions v1.22.0](https://github.com/open-telemetry/semantic-conventions/tree/v1.22.0/docs) +for a foundational understanding of what we build on top of. As newer versions of the OTel Semantic Conventions are released +this document will be updated as needed to try and conform for maximum portability and usability of the data our sensors +produce. + +While the OTel Semantic Conventions encompass a lot of technologies, and is growing, we will try to capture and replicate from +the specification what is important for Contrast's sensors. Semantic Conventions by signals: - [Resource](resource/README.md): Semantic Conventions for resources. - [Trace](general/trace.md): Semantic Conventions for traces and spans. - [Metrics](general/metrics.md): Semantic Conventions for metrics. + +Semantic Conventions by technology: + +- [Actions](actions/README.md): Semantic Conventions for Contrast Actions. diff --git a/docs/actions/action-metrics.md b/docs/actions/action-metrics.md index a9b1190..48f0bd0 100644 --- a/docs/actions/action-metrics.md +++ b/docs/actions/action-metrics.md @@ -99,10 +99,10 @@ of `[ 0.005, 0.01, 0.025, 0.05, 0.075, 0.1, 0.25, 0.5, 0.75, 1, 2.5, 5, 7.5, 10 | `http.request.method` | string | HTTP request method. [2] | `GET`; `POST`; `HEAD` | Required | | `http.response.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.route` | string | The matched route (path template in the format used by the respective server framework). See note below [3] | `/users/:userID?`; `{controller}/{action}/{id?}` | Conditionally Required: If and only if it's available | -| `network.protocol.name` | string | [OSI application layer](https://osi-model.com/application-layer/) or non-OSI equivalent. [4] | `http`; `spdy` | Recommended: if not default (`http`). | -| `network.protocol.version` | string | Version of the protocol specified in `network.protocol.name`. [5] | `1.0`; `1.1`; `2`; `3` | Recommended | -| [`server.address`](outbound-service-call.md) | string | Name of the local HTTP server that received the request. [6] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | Opt-In | -| [`server.port`](outbound-service-call.md) | int | Port of the local HTTP server that received the request. [7] | `80`; `8080`; `443` | Opt-In | +| [`network.protocol.name`](../general/attributes.md) | string | [OSI application layer](https://osi-model.com/application-layer/) or non-OSI equivalent. [4] | `http`; `spdy` | Recommended: if not default (`http`). | +| [`network.protocol.version`](../general/attributes.md) | string | Version of the protocol specified in `network.protocol.name`. [5] | `1.0`; `1.1`; `2`; `3` | Recommended | +| [`server.address`](../general/attributes.md) | string | Name of the local HTTP server that received the request. [6] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | Opt-In | +| [`server.port`](../general/attributes.md) | int | Port of the local HTTP server that received the request. [7] | `80`; `8080`; `443` | Opt-In | | `url.scheme` | string | The [URI scheme](https://www.rfc-editor.org/rfc/rfc3986#section-3.1) component identifying the used protocol. | `http`; `https` | Required | **[1]:** If the request fails with an error before response status code was sent or received, diff --git a/docs/actions/outbound-service-call.md b/docs/actions/outbound-service-call.md index c2db3a6..103e04f 100644 --- a/docs/actions/outbound-service-call.md +++ b/docs/actions/outbound-service-call.md @@ -24,54 +24,37 @@ This span type represents an outbound HTTP request. There are two ways this can | Attribute | Type | Description | Examples | Requirement Level | |---|---|---|---|---| -| `http.request.method` | string | HTTP request method. [1] | `GET`; `POST`; `HEAD` | Recommended | -| `http.response.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. | -| `network.peer.address` | string | Peer address of the network connection - IP address or Unix domain socket name. | `10.1.2.80`; `/tmp/my.sock` | Recommended | -| `network.peer.port` | int | Peer port number of the network connection. | `65123` | Recommended | -| `network.protocol.version` | string | Version of the protocol specified in `network.protocol.name`. [2] | `3.1.1` | Recommended | -| `server.address` | string | Name of the remotely connected host. [3] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | Required | -| `server.port` | int | Port identifier of the [“URI origin”](https://www.rfc-editor.org/rfc/rfc9110.html#name-uri-origin) HTTP request is sent to. [4] | `80`; `8080`; `443` | Required | +| `http.resend_count` | int | The ordinal number of request resending attempt (for any reason, including redirects). [1] | `3` | Recommended: if and only if request was retried. | +| [`network.peer.address`](../general/attributes.md) | string | Peer address of the network connection - IP address or Unix domain socket name. | `10.1.2.80`; `/tmp/my.sock` | Recommended: If different than `server.address`. | +| [`network.peer.port`](../general/attributes.md) | int | Peer port number of the network connection. | `65123` | Recommended: If `network.peer.address` is set. | +| [`server.address`](../general/attributes.md) | string | Host identifier of the ["URI origin"](https://www.rfc-editor.org/rfc/rfc9110.html#name-uri-origin) HTTP request is sent to. [2] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | Required | +| [`server.port`](../general/attributes.md) | int | Port identifier of the ["URI origin"](https://www.rfc-editor.org/rfc/rfc9110.html#name-uri-origin) HTTP request is sent to. [3] | `80`; `8080`; `443` | Conditionally Required: [4] | | `url.full` | string | Absolute URL describing a network resource according to [RFC3986](https://www.rfc-editor.org/rfc/rfc3986) [5] | `https://www.foo.bar/search?q=OpenTelemetry#SemConv`; `//localhost` | Required | -**[1]:** HTTP request method value SHOULD be "known" to the instrumentation. -By default, this convention defines "known" methods as the ones listed in [RFC9110](https://www.rfc-editor.org/rfc/rfc9110.html#name-methods) -and the PATCH method defined in [RFC5789](https://www.rfc-editor.org/rfc/rfc5789.html). +**[1]:** The resend count SHOULD be updated each time an HTTP request gets resent by the client, regardless of what was the cause of the resending (e.g. redirection, authorization failure, 503 Server Unavailable, network issues, or any other). -If the HTTP request method is not known to instrumentation, it MUST set the `http.request.method` attribute to `_OTHER`. +**[2]:** Determined by using the first of the following that applies -If the HTTP instrumentation could end up converting valid HTTP request methods to `_OTHER`, then it MUST provide a way to override -the list of known HTTP methods. If this override is done via environment variable, then the environment variable MUST be named -OTEL_INSTRUMENTATION_HTTP_KNOWN_METHODS and support a comma-separated list of case-sensitive known HTTP methods -(this list MUST be a full override of the default known method, it is not a list of known methods in addition to the defaults). +- Host identifier of the [request target](https://www.rfc-editor.org/rfc/rfc9110.html#target.resource) + if it's sent in absolute-form +- Host identifier of the `Host` header -HTTP method names are case-sensitive and `http.request.method` attribute value MUST match a known HTTP method name exactly. -Instrumentations for specific web frameworks that consider HTTP methods to be case insensitive, SHOULD populate a canonical equivalent. -Tracing instrumentations that do so, MUST also set `http.request.method_original` to the original value. +If an HTTP client request is explicitly made to an IP address, e.g. `http://x.x.x.x:8080`, then +`server.address` SHOULD be the IP address `x.x.x.x`. A DNS lookup SHOULD NOT be used. -**[2]:** `network.protocol.version` refers to the version of the protocol used and might be different from the protocol client's version. If the HTTP client used has a version of `0.27.2`, but sends HTTP version `1.1`, this attribute should be set to `1.1`. +**[3]:** When [request target](https://www.rfc-editor.org/rfc/rfc9110.html#target.resource) is absolute URI, `server.port` MUST match URI port identifier, otherwise it MUST match `Host` header port identifier. -**[3]:** If an HTTP client request is explicitly made to an IP address, e.g. `http://x.x.x.x:8080`, then server.address SHOULD be the IP address x.x.x.x. A DNS lookup SHOULD NOT be used. - -**[4]:** When observed from the client side, and when communicating through an intermediary, `server.port`` SHOULD represent the server port behind any intermediaries, for example proxies, if it’s available. +**[4]:** If not default (`80` for `http` scheme, `443` for `https`). **[5]:** For network calls, URL usually has `scheme://host[:port][path][?query][#fragment]` format, where the fragment is not transmitted over HTTP, but if it is known, it should be included nevertheless. `url.full` MUST NOT contain credentials passed via URL in form of `https://username:password@www.example.com/`. In such case username and password should be redacted and attribute's value should be `https://REDACTED:REDACTED@www.example.com/`. `url.full` SHOULD capture the absolute URL when it is available (or can be reconstructed) and SHOULD NOT be validated or modified except for sanitizing purposes. -`http.request.method` 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 | -|---|---| -| `CONNECT` | CONNECT method. | -| `DELETE` | DELETE method. | -| `GET` | GET method. | -| `HEAD` | HEAD method. | -| `OPTIONS` | OPTIONS method. | -| `PATCH` | PATCH method. | -| `POST` | POST method. | -| `PUT` | PUT method. | -| `TRACE` | TRACE method. | -| `_OTHER` | Any HTTP method that the instrumentation has no prior knowledge of. | +Following attributes MUST be provided **at span creation time** (when provided at all), so they can be considered for sampling decisions: + +* [`server.address`](../general/attributes.md) +* [`server.port`](../general/attributes.md) +* `url.full` ## outbound-service-call (http client) span duration diff --git a/docs/general/README.md b/docs/general/README.md new file mode 100644 index 0000000..b7b1b46 --- /dev/null +++ b/docs/general/README.md @@ -0,0 +1,9 @@ +# General Semantic Conventions + +This document defines general Semantic Conventions for spans and metrics. + +The following general Semantic Conventions are defined: + +* **[General attributes](attributes.md): General semantic attributes**. +* [Metrics](metrics.md): General Semantic Conventions for metrics. +* [Spans](trace.md): General Semantic Conventions for traces / spans. diff --git a/docs/general/attributes.md b/docs/general/attributes.md new file mode 100644 index 0000000..b1aaa86 --- /dev/null +++ b/docs/general/attributes.md @@ -0,0 +1,254 @@ +# General Attributes + +The attributes described in this section are not specific to a particular operation but rather generic. +They may be used in any Span they apply to. +Particular operations may refer to or require some of these attributes. + + + + + +- [Server, client and shared network attributes](#server-client-and-shared-network-attributes) + * [Address and port attributes](#address-and-port-attributes) + * [Server attributes](#server-attributes) + + [`server.address`](#serveraddress) + * [Client attributes](#client-attributes) + * [Source and destination attributes](#source-and-destination-attributes) + + [Source](#source) + + [Destination](#destination) + * [Other network attributes](#other-network-attributes) + + [`network.peer.*` and `network.local.*` attributes](#networkpeer-and-networklocal-attributes) + - [Client/server examples using `network.peer.*`](#clientserver-examples-using--networkpeer) + * [Simple client/server example](#simple-clientserver-example) + * [Client/server example with reverse proxy](#clientserver-example-with-reverse-proxy) + * [Client/server example with forward proxy](#clientserver-example-with-forward-proxy) +- [General remote service attributes](#general-remote-service-attributes) +- [Source Code Attributes](#source-code-attributes) + + + + + + +## Server, client and shared network attributes + +These attributes may be used to describe the client and server in a connection-based network interaction +where there is one side that initiates the connection (the client is the side that initiates the connection). +This covers all TCP network interactions since TCP is connection-based and one side initiates the +connection (an exception is made for peer-to-peer communication over TCP where the "user-facing" surface of the +protocol / API does not expose a clear notion of client and server). +This also covers UDP network interactions where one side initiates the interaction, e.g. QUIC (HTTP/3) and DNS. + +In an ideal situation, not accounting for proxies, multiple IP addresses or host names, +the `server.*` attributes are the same on the client and server. + +### Address and port attributes + +For all IP-based protocols, the "address" should be just the IP-level address. +Protocol-specific parts of an address are split into other attributes (when applicable) such as "port" attributes for +TCP and UDP. If such transport-specific information is collected and the attribute name does not already uniquely +identify the transport, then setting [`network.transport`](#other-network-attributes) is especially encouraged. + +### Server attributes + + +| Attribute | Type | Description | Examples | Requirement Level | +|---|---|---|---|---| +| `server.address` | string | Server address - domain name if available without reverse DNS lookup, otherwise IP address or Unix domain socket name. [1] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | Recommended | +| `server.port` | int | Server port number. [2] | `80`; `8080`; `443` | Recommended | + +**[1]:** When observed from the client side, and when communicating through an intermediary, `server.address` SHOULD represent +the server address behind any intermediaries (e.g. proxies) if it's available. + +**[2]:** When observed from the client side, and when communicating through an intermediary, `server.port` SHOULD represent the server port behind any intermediaries (e.g. proxies) if it's available. + + +`server.address` and `server.port` represent logical server name and port. Semantic conventions that refer to these attributes SHOULD +specify what these attributes mean in their context. + +#### `server.address` + +For IP-based communication, the name should be a DNS host name of the service. On client side it matches remote service name, on server side, it represents local service name as seen externally on clients. + +When connecting to an URL `https://example.com/foo`, `server.address` matches `"example.com"` on both client and server side. + +On client side, it's usually passed in form of URL, connection string, host name, etc. Sometimes host name is only available to instrumentation as a string which may contain DNS name or IP address. `server.address` SHOULD be set to the available known hostname (e.g., `"127.0.0.1"` if connecting to an URL `https://127.0.0.1/foo`). + +If only IP address is available, it should be populated on `server.address`. Reverse DNS lookup SHOULD NOT be used to obtain DNS name. + +If `network.transport` is `"pipe"`, the absolute path to the file representing it should be used as `server.address`. +If there is no such file (e.g., anonymous pipe), +the name should explicitly be set to the empty string to distinguish it from the case where the name is just unknown or not covered by the instrumentation. + +For Unix domain socket, `server.address` attribute represents remote endpoint address on the client side and local endpoint address on the server side. + +### Client attributes + + +| Attribute | Type | Description | Examples | Requirement Level | +|---|---|---|---|---| +| `client.address` | string | Client address - domain name if available without reverse DNS lookup, otherwise IP address or Unix domain socket name. [1] | `client.example.com`; `10.1.2.80`; `/tmp/my.sock` | Recommended | +| `client.port` | int | Client port number. [2] | `65123` | Recommended | + +**[1]:** When observed from the server side, and when communicating through an intermediary, `client.address` SHOULD represent the client address behind any intermediaries (e.g. proxies) if it's available. + +**[2]:** When observed from the server side, and when communicating through an intermediary, `client.port` SHOULD represent the client port behind any intermediaries (e.g. proxies) if it's available. + + +### Source and destination attributes + +These attributes may be used to describe the sender and receiver of a network exchange/packet. These should be used +when there is no client/server relationship between the two sides, or when that relationship is unknown. +This covers low-level network interactions (e.g. packet tracing) where you don't know if +there was a connection or which side initiated it. +This also covers unidirectional UDP flows and peer-to-peer communication where the +"user-facing" surface of the protocol / API does not expose a clear notion of client and server. + +#### Source + + +| Attribute | Type | Description | Examples | Requirement Level | +|---|---|---|---|---| +| `source.address` | string | Source address - domain name if available without reverse DNS lookup, otherwise IP address or Unix domain socket name. [1] | `source.example.com`; `10.1.2.80`; `/tmp/my.sock` | Recommended | +| `source.port` | int | Source port number | `3389`; `2888` | Recommended | + +**[1]:** When observed from the destination side, and when communicating through an intermediary, `source.address` SHOULD represent the source address behind any intermediaries (e.g. proxies) if it's available. + + +#### Destination + +Destination fields capture details about the receiver of a network exchange/packet. + + +| Attribute | Type | Description | Examples | Requirement Level | +|---|---|---|---|---| +| `destination.address` | string | Destination address - domain name if available without reverse DNS lookup, otherwise IP address or Unix domain socket name. [1] | `destination.example.com`; `10.1.2.80`; `/tmp/my.sock` | Recommended | +| `destination.port` | int | Destination port number | `3389`; `2888` | Recommended | + +**[1]:** When observed from the source side, and when communicating through an intermediary, `destination.address` SHOULD represent the destination address behind any intermediaries (e.g. proxies) if it's available. + + + + +### Other network attributes + +> **Warning** +> Attributes in this section are in use by the HTTP semantic conventions. +Once the HTTP semantic conventions are declared stable, changes to the attributes in this section will only be allowed +if they do not cause breaking changes to HTTP semantic conventions. + + +| Attribute | Type | Description | Examples | Requirement Level | +|---|---|---|---|---| +| `network.local.address` | string | Local address of the network connection - IP address or Unix domain socket name. | `10.1.2.80`; `/tmp/my.sock` | Recommended | +| `network.local.port` | int | Local port number of the network connection. | `65123` | Recommended | +| `network.peer.address` | string | Peer address of the network connection - IP address or Unix domain socket name. | `10.1.2.80`; `/tmp/my.sock` | Recommended | +| `network.peer.port` | int | Peer port number of the network connection. | `65123` | Recommended | +| `network.protocol.name` | string | [OSI application layer](https://osi-model.com/application-layer/) or non-OSI equivalent. [1] | `amqp`; `http`; `mqtt` | Recommended | +| `network.protocol.version` | string | Version of the protocol specified in `network.protocol.name`. [2] | `3.1.1` | Recommended | +| `network.transport` | string | [OSI transport layer](https://osi-model.com/transport-layer/) or [inter-process communication method](https://en.wikipedia.org/wiki/Inter-process_communication). [3] | `tcp`; `udp` | Recommended | +| `network.type` | string | [OSI network layer](https://osi-model.com/network-layer/) or non-OSI equivalent. [4] | `ipv4`; `ipv6` | Recommended | + +**[1]:** The value SHOULD be normalized to lowercase. + +**[2]:** `network.protocol.version` refers to the version of the protocol used and might be different from the protocol client's version. If the HTTP client used has a version of `0.27.2`, but sends HTTP version `1.1`, this attribute should be set to `1.1`. + +**[3]:** The value SHOULD be normalized to lowercase. + +Consider always setting the transport when setting a port number, since +a port number is ambiguous without knowing the transport, for example +different processes could be listening on TCP port 12345 and UDP port 12345. + +**[4]:** The value SHOULD be normalized to lowercase. + +`network.transport` 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 | +|---|---| +| `tcp` | TCP | +| `udp` | UDP | +| `pipe` | Named or anonymous pipe. See note below. | +| `unix` | Unix domain socket | + +`network.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 | +|---|---| +| `ipv4` | IPv4 | +| `ipv6` | IPv6 | + + +#### `network.peer.*` and `network.local.*` attributes + +These attributes identify network peers that are directly connected to each other. + +`network.peer.address` and `network.local.address` should be IP addresses, Unix domain socket names, or other addresses specific to network type. + +_Note: Specific structures and methods to obtain socket-level attributes are mentioned here only as examples. Instrumentations would usually use Socket API provided by their environment or sockets implementations._ + +When connecting using `connect(2)` ([Linux or other POSIX systems](https://man7.org/linux/man-pages/man2/connect.2.html) / +[Windows](https://docs.microsoft.com/windows/win32/api/winsock2/nf-winsock2-connect)) +or `bind(2)`([Linux or other POSIX systems](https://man7.org/linux/man-pages/man2/bind.2.html) / +[Windows](https://docs.microsoft.com/windows/win32/api/winsock2/nf-winsock2-bind)) +with `AF_INET` address family, `network.peer.address` and `network.peer.port` represent `sin_addr` and `sin_port` fields +of `sockaddr_in` structure. + +`network.peer.address` and `network.peer.port` can be obtained by calling `getpeername` method +([Linux or other POSIX systems](https://man7.org/linux/man-pages/man2/getpeername.2.html) / +[Windows](https://docs.microsoft.com/windows/win32/api/winsock2/nf-winsock2-getpeername)). + +`network.local.address` and `network.local.port` can be obtained by calling `getsockname` method +([Linux or other POSIX systems](https://man7.org/linux/man-pages/man2/getsockname.2.html) / +[Windows](https://docs.microsoft.com/windows/win32/api/winsock2/nf-winsock2-getsockname)). + +##### Client/server examples using `network.peer.*` + +Note that `network.local.*` attributes are not included in these examples since they are typically Opt-In. + +###### Simple client/server example + +![simple.png](simple.png) + +###### Client/server example with reverse proxy + +![reverse-proxy.png](reverse-proxy.png) + +###### Client/server example with forward proxy + +![forward-proxy.png](forward-proxy.png) + +## General remote service attributes + +This attribute may be used for any operation that accesses some remote service. +Users can define what the name of a service is based on their particular semantics in their distributed system. +Instrumentations SHOULD provide a way for users to configure this name. + + +| Attribute | Type | Description | Examples | Requirement Level | +|---|---|---|---|---| +| `peer.service` | string | The [`service.name`](/docs/resource/README.md#service) of the remote service. SHOULD be equal to the actual `service.name` resource attribute of the remote service if any. | `AuthTokenCache` | Recommended | + + +Examples of `peer.service` that users may specify: + +- A Redis cache of auth tokens as `peer.service="AuthTokenCache"`. +- A gRPC service `rpc.service="io.opentelemetry.AuthService"` may be hosted in both a gateway, `peer.service="ExternalApiService"` and a backend, `peer.service="AuthService"`. + +## Source Code Attributes + +Often a span is closely tied to a certain unit of code that is logically responsible for handling +the operation that the span describes (usually the method that starts the span). +For an HTTP server span, this would be the function that handles the incoming request, for example. +The attributes listed below allow to report this unit of code and therefore to provide more context +about the span. + + +| Attribute | Type | Description | Examples | Requirement Level | +|---|---|---|---|---| +| `code.column` | int | The column number in `code.filepath` best representing the operation. It SHOULD point within the code unit named in `code.function`. | `16` | Recommended | +| `code.filepath` | string | The source code file name that identifies the code unit as uniquely as possible (preferably an absolute file path). | `/usr/local/MyApplication/content_root/app/index.php` | Recommended | +| `code.function` | string | The method or function name, or equivalent (usually rightmost part of the code unit's name). | `serveRequest` | Recommended | +| `code.lineno` | int | The line number in `code.filepath` best representing the operation. It SHOULD point within the code unit named in `code.function`. | `42` | Recommended | +| `code.namespace` | string | The "namespace" within which `code.function` is defined. Usually the qualified class or module name, such that `code.namespace` + some separator + `code.function` form a unique identifier for the code unit. | `com.example.MyHttpService` | Recommended | +| `code.stacktrace` | string | A stacktrace as a string in the natural representation for the language runtime. The representation is to be determined and documented by each language SIG. | `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)` | Opt-In | + diff --git a/docs/general/forward-proxy.png b/docs/general/forward-proxy.png new file mode 100644 index 0000000..0badc46 Binary files /dev/null and b/docs/general/forward-proxy.png differ diff --git a/docs/general/reverse-proxy.png b/docs/general/reverse-proxy.png new file mode 100644 index 0000000..2f21f81 Binary files /dev/null and b/docs/general/reverse-proxy.png differ diff --git a/docs/general/simple.png b/docs/general/simple.png new file mode 100644 index 0000000..b8c48b0 Binary files /dev/null and b/docs/general/simple.png differ diff --git a/docs/http/http-spans.md b/docs/http/http-spans.md index a645b5b..d0b8b94 100644 --- a/docs/http/http-spans.md +++ b/docs/http/http-spans.md @@ -92,10 +92,10 @@ sections below. | `http.response.body.size` | int | The size of the response payload body in bytes. This is the number of bytes transferred excluding headers and is often, but not always, present as the [Content-Length](https://www.rfc-editor.org/rfc/rfc9110.html#field.content-length) header. For requests using transport encoding, this should be the compressed size. | `3495` | Recommended | | `http.response.header.` | string[] | HTTP response headers, `` being the normalized HTTP Header name (lowercase, with `-` characters replaced by `_`), the value being the header values. [5] | `http.response.header.content_type=["application/json"]`; `http.response.header.my_custom_header=["abc", "def"]` | Opt-In | | `http.response.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. | -| `network.protocol.name` | string | [OSI application layer](https://osi-model.com/application-layer/) or non-OSI equivalent. [6] | `http`; `spdy` | Recommended: if not default (`http`). | -| `network.protocol.version` | string | Version of the protocol specified in `network.protocol.name`. [7] | `1.0`; `1.1`; `2`; `3` | Recommended | -| `network.transport` | string | [OSI transport layer](https://osi-model.com/transport-layer/) or [inter-process communication method](https://en.wikipedia.org/wiki/Inter-process_communication). [8] | `tcp`; `udp` | Conditionally Required: [9] | -| `network.type` | string | [OSI network layer](https://osi-model.com/network-layer/) or non-OSI equivalent. [10] | `ipv4`; `ipv6` | Recommended | +| [`network.protocol.name`](../general/attributes.md) | string | [OSI application layer](https://osi-model.com/application-layer/) or non-OSI equivalent. [6] | `http`; `spdy` | Recommended: if not default (`http`). | +| [`network.protocol.version`](../general/attributes.md) | string | Version of the protocol specified in `network.protocol.name`. [7] | `1.0`; `1.1`; `2`; `3` | Recommended | +| [`network.transport`](../general/attributes.md) | string | [OSI transport layer](https://osi-model.com/transport-layer/) or [inter-process communication method](https://en.wikipedia.org/wiki/Inter-process_communication). [8] | `tcp`; `udp` | Conditionally Required: [9] | +| [`network.type`](../general/attributes.md) | string | [OSI network layer](https://osi-model.com/network-layer/) or non-OSI equivalent. [10] | `ipv4`; `ipv6` | Recommended | | `user_agent.original` | string | Value of the [HTTP User-Agent](https://www.rfc-editor.org/rfc/rfc9110.html#field.user-agent) header sent by the client. | `CERN-LineMode/2.15 libwww/2.17b3` | Recommended | **[1]:** If the request fails with an error before response status code was sent or received, @@ -213,10 +213,10 @@ For an HTTP client span, `SpanKind` MUST be `Client`. | Attribute | Type | Description | Examples | Requirement Level | |---|---|---|---|---| | `http.resend_count` | int | The ordinal number of request resending attempt (for any reason, including redirects). [1] | `3` | Recommended: if and only if request was retried. | -| `network.peer.address` | string | Peer address of the network connection - IP address or Unix domain socket name. | `10.1.2.80`; `/tmp/my.sock` | Recommended: If different than `server.address`. | -| `network.peer.port` | int | Peer port number of the network connection. | `65123` | Recommended: If `network.peer.address` is set. | -| [`server.address`](../actions/outbound-service-call.md) | string | Host identifier of the ["URI origin"](https://www.rfc-editor.org/rfc/rfc9110.html#name-uri-origin) HTTP request is sent to. [2] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | Required | -| [`server.port`](../actions/outbound-service-call.md) | int | Port identifier of the ["URI origin"](https://www.rfc-editor.org/rfc/rfc9110.html#name-uri-origin) HTTP request is sent to. [3] | `80`; `8080`; `443` | Conditionally Required: [4] | +| [`network.peer.address`](../general/attributes.md) | string | Peer address of the network connection - IP address or Unix domain socket name. | `10.1.2.80`; `/tmp/my.sock` | Recommended: If different than `server.address`. | +| [`network.peer.port`](../general/attributes.md) | int | Peer port number of the network connection. | `65123` | Recommended: If `network.peer.address` is set. | +| [`server.address`](../general/attributes.md) | string | Host identifier of the ["URI origin"](https://www.rfc-editor.org/rfc/rfc9110.html#name-uri-origin) HTTP request is sent to. [2] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | Required | +| [`server.port`](../general/attributes.md) | int | Port identifier of the ["URI origin"](https://www.rfc-editor.org/rfc/rfc9110.html#name-uri-origin) HTTP request is sent to. [3] | `80`; `8080`; `443` | Conditionally Required: [4] | | `url.full` | string | Absolute URL describing a network resource according to [RFC3986](https://www.rfc-editor.org/rfc/rfc3986) [5] | `https://www.foo.bar/search?q=OpenTelemetry#SemConv`; `//localhost` | Required | **[1]:** The resend count SHOULD be updated each time an HTTP request gets resent by the client, regardless of what was the cause of the resending (e.g. redirection, authorization failure, 503 Server Unavailable, network issues, or any other). @@ -240,8 +240,8 @@ If an HTTP client request is explicitly made to an IP address, e.g. `http://x.x. Following attributes MUST be provided **at span creation time** (when provided at all), so they can be considered for sampling decisions: -* [`server.address`](../actions/outbound-service-call.md) -* [`server.port`](../actions/outbound-service-call.md) +* [`server.address`](../general/attributes.md) +* [`server.port`](../general/attributes.md) * `url.full` @@ -335,15 +335,15 @@ For an HTTP server span, `SpanKind` MUST be `Server`. | Attribute | Type | Description | Examples | Requirement Level | |---|---|---|---|---| -| `client.address` | string | Client address - domain name if available without reverse DNS lookup, otherwise IP address or Unix domain socket name. [1] | `83.164.160.102` | Recommended | -| `client.port` | int | The port of the original client behind all proxies, if known (e.g. from [Forwarded](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Forwarded) or a similar header). Otherwise, the immediate client peer port. [2] | `65123` | Recommended | +| [`client.address`](../general/attributes.md) | string | Client address - domain name if available without reverse DNS lookup, otherwise IP address or Unix domain socket name. [1] | `83.164.160.102` | Recommended | +| [`client.port`](../general/attributes.md) | int | The port of the original client behind all proxies, if known (e.g. from [Forwarded](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Forwarded) or a similar header). Otherwise, the immediate client peer port. [2] | `65123` | Recommended | | `http.route` | string | The matched route (path template in the format used by the respective server framework). See note below [3] | `/users/:userID?`; `{controller}/{action}/{id?}` | Conditionally Required: If and only if it's available | -| `network.local.address` | string | Local socket address. Useful in case of a multi-IP host. | `10.1.2.80`; `/tmp/my.sock` | Opt-In | -| `network.local.port` | int | Local socket port. Useful in case of a multi-port host. | `65123` | Opt-In | -| `network.peer.address` | string | Peer address of the network connection - IP address or Unix domain socket name. | `10.1.2.80`; `/tmp/my.sock` | Recommended | -| `network.peer.port` | int | Peer port number of the network connection. | `65123` | Recommended | -| [`server.address`](../actions/outbound-service-call.md) | string | Name of the local HTTP server that received the request. [4] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | Required | -| [`server.port`](../actions/outbound-service-call.md) | int | Port of the local HTTP server that received the request. [5] | `80`; `8080`; `443` | Recommended: [6] | +| [`network.local.address`](../general/attributes.md) | string | Local socket address. Useful in case of a multi-IP host. | `10.1.2.80`; `/tmp/my.sock` | Opt-In | +| [`network.local.port`](../general/attributes.md) | int | Local socket port. Useful in case of a multi-port host. | `65123` | Opt-In | +| [`network.peer.address`](../general/attributes.md) | string | Peer address of the network connection - IP address or Unix domain socket name. | `10.1.2.80`; `/tmp/my.sock` | Recommended | +| [`network.peer.port`](../general/attributes.md) | int | Peer port number of the network connection. | `65123` | Recommended | +| [`server.address`](../general/attributes.md) | string | Name of the local HTTP server that received the request. [4] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | Recommended | +| [`server.port`](../general/attributes.md) | int | Port of the local HTTP server that received the request. [5] | `80`; `8080`; `443` | Recommended: [6] | | `url.path` | string | The [URI path](https://www.rfc-editor.org/rfc/rfc3986#section-3.3) component [7] | `/search` | Required | | `url.query` | string | The [URI query](https://www.rfc-editor.org/rfc/rfc3986#section-3.4) component [8] | `q=OpenTelemetry` | Conditionally Required: If and only if one was received/sent. | | `url.scheme` | string | The [URI scheme](https://www.rfc-editor.org/rfc/rfc3986#section-3.1) component identifying the used protocol. | `http`; `https` | Required | @@ -380,8 +380,8 @@ SHOULD NOT be set if only IP address is available and capturing name would requi Following attributes MUST be provided **at span creation time** (when provided at all), so they can be considered for sampling decisions: -* [`server.address`](../actions/outbound-service-call.md) -* [`server.port`](../actions/outbound-service-call.md) +* [`server.address`](../general/attributes.md) +* [`server.port`](../general/attributes.md) * `url.path` * `url.query` * `url.scheme` diff --git a/model/destination.yaml b/model/destination.yaml new file mode 100644 index 0000000..bad57d5 --- /dev/null +++ b/model/destination.yaml @@ -0,0 +1,22 @@ +groups: + - id: destination + prefix: destination + type: attribute_group + brief: These attributes may be used to describe the receiver of a network exchange/packet. These should be used + when there is no client/server relationship between the two sides, or when that relationship is unknown. + This covers low-level network interactions (e.g. packet tracing) where you don't know if + there was a connection or which side initiated it. + This also covers unidirectional UDP flows and peer-to-peer communication where the + "user-facing" surface of the protocol / API does not expose a clear notion of client and server. + attributes: + - id: address + type: string + brief: Destination address - domain name if available without reverse DNS lookup, otherwise IP address or Unix domain socket name. + note: > + When observed from the source side, and when communicating through an intermediary, `destination.address` SHOULD represent + the destination address behind any intermediaries (e.g. proxies) if it's available. + examples: ['destination.example.com', '10.1.2.80', '/tmp/my.sock'] + - id: port + type: int + brief: 'Destination port number' + examples: [3389, 2888] diff --git a/model/general.yaml b/model/general.yaml new file mode 100644 index 0000000..be45d72 --- /dev/null +++ b/model/general.yaml @@ -0,0 +1,54 @@ +groups: + - id: general.client + type: attribute_group + brief: > + General client attributes. + attributes: + - ref: client.address + - ref: client.port + - id: general.server + type: attribute_group + brief: > + General server attributes. + attributes: + - ref: server.address + - ref: server.port + - id: general.source + type: attribute_group + brief: > + General source attributes. + attributes: + - ref: source.address + - ref: source.port + - id: general.destination + type: attribute_group + brief: > + General destination attributes. + attributes: + - ref: destination.address + - ref: destination.port + - id: peer + prefix: peer + type: span + brief: "Operations that access some remote service." + attributes: + - id: service + type: string + stability: experimental + brief: > + The [`service.name`](/docs/resource/README.md#service) + of the remote service. SHOULD be equal to the actual `service.name` + resource attribute of the remote service if any. + examples: "AuthTokenCache" + - id: code + type: span + brief: > + These attributes allow to report this unit of code and therefore to provide more context about the span. + attributes: + - ref: code.function + - ref: code.namespace + - ref: code.filepath + - ref: code.lineno + - ref: code.column + - ref: code.stacktrace + requirement_level: opt_in diff --git a/model/registry/code.yaml b/model/registry/code.yaml new file mode 100644 index 0000000..5848b4f --- /dev/null +++ b/model/registry/code.yaml @@ -0,0 +1,47 @@ +groups: + - id: registry.code + prefix: code + type: span + brief: > + These attributes allow to report this unit of code and therefore to provide more context about the span. + attributes: + - id: function + type: string + stability: experimental + brief: > + The method or function name, or equivalent (usually rightmost part of the code unit's name). + examples: serveRequest + - id: namespace + type: string + stability: experimental + brief: > + The "namespace" within which `code.function` is defined. Usually the qualified class or module name, + such that `code.namespace` + some separator + `code.function` form a unique identifier for the code unit. + examples: com.example.MyHttpService + - id: filepath + type: string + stability: experimental + brief: > + The source code file name that identifies the code unit as uniquely as possible (preferably an absolute file path). + examples: /usr/local/MyApplication/content_root/app/index.php + - id: lineno + type: int + stability: experimental + brief: > + The line number in `code.filepath` best representing the operation. It SHOULD point within the code unit named in `code.function`. + examples: 42 + - id: column + type: int + stability: experimental + brief: > + The column number in `code.filepath` best representing the operation. It SHOULD point within the code unit named in `code.function`. + examples: 16 + - id: stacktrace + type: string + stability: experimental + brief: > + A stacktrace as a string in the natural representation for the language runtime. + The representation is to be determined and documented by each language SIG. + examples: '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)' diff --git a/model/server.yaml b/model/server.yaml new file mode 100644 index 0000000..8f10470 --- /dev/null +++ b/model/server.yaml @@ -0,0 +1,26 @@ +groups: + - id: server + prefix: server + type: attribute_group + brief: > + These attributes may be used to describe the server in a connection-based network interaction + where there is one side that initiates the connection (the client is the side that initiates the connection). + This covers all TCP network interactions since TCP is connection-based and one side initiates the + connection (an exception is made for peer-to-peer communication over TCP where the "user-facing" surface of the + protocol / API does not expose a clear notion of client and server). + This also covers UDP network interactions where one side initiates the interaction, e.g. QUIC (HTTP/3) and DNS. + attributes: + - id: address + type: string + brief: Server address - domain name if available without reverse DNS lookup, otherwise IP address or Unix domain socket name. + note: | + When observed from the client side, and when communicating through an intermediary, `server.address` SHOULD represent + the server address behind any intermediaries (e.g. proxies) if it's available. + examples: ['example.com', '10.1.2.80', '/tmp/my.sock'] + - id: port + type: int + brief: Server port number. + note: > + When observed from the client side, and when communicating through an intermediary, `server.port` SHOULD represent + the server port behind any intermediaries (e.g. proxies) if it's available. + examples: [80, 8080, 443] diff --git a/model/source.yaml b/model/source.yaml new file mode 100644 index 0000000..9c0aa30 --- /dev/null +++ b/model/source.yaml @@ -0,0 +1,22 @@ +groups: + - id: source + prefix: source + type: attribute_group + brief: These attributes may be used to describe the sender of a network exchange/packet. These should be used + when there is no client/server relationship between the two sides, or when that relationship is unknown. + This covers low-level network interactions (e.g. packet tracing) where you don't know if + there was a connection or which side initiated it. + This also covers unidirectional UDP flows and peer-to-peer communication where the + "user-facing" surface of the protocol / API does not expose a clear notion of client and server. + attributes: + - id: address + type: string + brief: Source address - domain name if available without reverse DNS lookup, otherwise IP address or Unix domain socket name. + note: > + When observed from the destination side, and when communicating through an intermediary, `source.address` SHOULD represent + the source address behind any intermediaries (e.g. proxies) if it's available. + examples: ['source.example.com', '10.1.2.80', '/tmp/my.sock'] + - id: port + type: int + brief: 'Source port number' + examples: [3389, 2888] diff --git a/model/trace/contrast-actions.yml b/model/trace/contrast-actions.yml index 9d66353..5c1c27e 100644 --- a/model/trace/contrast-actions.yml +++ b/model/trace/contrast-actions.yml @@ -173,39 +173,10 @@ groups: - id: contrast.action.span.outbound-service-call type: span + extends: trace.http.client brief: > Describes attributes for Contrast Action span of type outbound-service-call. These actions are always using the http protocol. - attributes: - - ref: http.request.method - - ref: http.response.status_code - requirement_level: - conditionally_required: if and only if one was received. - - ref: network.protocol.version - - ref: network.peer.address - - ref: network.peer.port - - id: server.address - brief: > - Name of the remotely connected host. - requirement_level: required - examples: [example.com, "10.1.2.80", /tmp/my.sock] - type: string - note: > - If an HTTP client request is explicitly made to an IP address, - e.g. `http://x.x.x.x:8080`, then server.address SHOULD be the IP - address x.x.x.x. A DNS lookup SHOULD NOT be used. - - id: server.port - brief: > - Port identifier of the [“URI origin”](https://www.rfc-editor.org/rfc/rfc9110.html#name-uri-origin) HTTP request is sent to. - requirement_level: required - examples: [80, 8080, 443] - type: int - note: > - When observed from the client side, and when communicating through an - intermediary, `server.port`` SHOULD represent the server port behind - any intermediaries, for example proxies, if it’s available. - - ref: url.full - requirement_level: required - id: attributes.contrast.code-exec type: attribute_group