open-telemetry
/
semantic-conventions
mirror of https://github.com/open-telemetry/semantic-conventions.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

BREAKING: Rename remaining network attributes from `net.*` to `network.*` and align definitions with ECS (#3426)

This commit is contained in:
Trask Stalnaker 2023-05-08 17:46:55 -07:00 committed by GitHub
parent 5b8861e8c5
commit 9e3e528ccc
16 changed files with 216 additions and 170 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

11
schemas/1.21.0
View File

@ -25,6 +25,17 @@ versions:
net.sock.host.addr: server.socket.address net.sock.host.addr: server.socket.address
net.sock.host.port: server.socket.port net.sock.host.port: server.socket.port
http.client_ip: client.address http.client_ip: client.address
# https://github.com/open-telemetry/opentelemetry-specification/pull/3426
- rename_attributes:
attribute_map:
net.protocol.name: network.protocol.name
net.protocol.version: network.protocol.version
net.host.connection.type: network.connection.type
net.host.connection.subtype: network.connection.subtype
net.host.carrier.name: network.carrier.name
net.host.carrier.mcc: network.carrier.mcc
net.host.carrier.mnc: network.carrier.mnc
net.host.carrier.icc: network.carrier.icc
1.20.0: 1.20.0:
spans: spans:
changes: changes:

48
semantic_conventions/deprecated/network.yaml
View File

@ -51,3 +51,51 @@ groups:
stability: deprecated stability: deprecated
brief: Deprecated, use `server.socket.port`. brief: Deprecated, use `server.socket.port`.
examples: [8080] examples: [8080]
- id: transport
type:
allow_custom_values: true
members:
- id: ip_tcp
value: "ip_tcp"
- id: ip_udp
value: "ip_udp"
- id: pipe
value: "pipe"
brief: 'Named or anonymous pipe.'
- id: inproc
value: "inproc"
brief: 'In-process communication.'
note: >
Signals that there is only in-process communication not using a "real" network protocol
in cases where network attributes would normally be expected. Usually all other network
attributes can be left out in that case.
- id: other
value: "other"
brief: 'Something else (non IP-based).'
stability: deprecated
brief: Deprecated, use `network.transport`.
- id: protocol.name
type: string
stability: deprecated
brief: Deprecated, use `network.protocol.name`.
examples: ['amqp', 'http', 'mqtt']
- id: protocol.version
type: string
stability: deprecated
brief: Deprecated, use `network.protocol.version`.
examples: '3.1.1'
- id: sock.family
type:
allow_custom_values: true
members:
- id: inet
value: 'inet'
brief: "IPv4 address"
- id: inet6
value: 'inet6'
brief: "IPv6 address"
- id: unix
value: 'unix'
brief: "Unix domain socket path"
stability: deprecated
brief: Deprecated, use `network.transport` and `network.type`.

4
semantic_conventions/http-common.yaml
View File

@ -15,11 +15,11 @@ groups:
conditionally_required: If and only if one was received/sent. conditionally_required: If and only if one was received/sent.
brief: '[HTTP response status code](https://tools.ietf.org/html/rfc7231#section-6).' brief: '[HTTP response status code](https://tools.ietf.org/html/rfc7231#section-6).'
examples: [200] examples: [200]
- ref: net.protocol.name - ref: network.protocol.name
examples: ['http', 'spdy'] examples: ['http', 'spdy']
requirement_level: requirement_level:
recommended: if not default (`http`). recommended: if not default (`http`).
- ref: net.protocol.version - ref: network.protocol.version
examples: ['1.0', '1.1', '2.0'] examples: ['1.0', '1.1', '2.0']
- id: attributes.http.client - id: attributes.http.client

24
semantic_conventions/metrics/http.yaml
View File

@ -10,8 +10,8 @@ groups:
# todo (lmolkova) build tools don't populate grandparent attributes # todo (lmolkova) build tools don't populate grandparent attributes
- ref: http.method - ref: http.method
- ref: http.status_code - ref: http.status_code
- ref: net.protocol.name - ref: network.protocol.name
- ref: net.protocol.version - ref: network.protocol.version
- id: metric.http.server.active_requests - id: metric.http.server.active_requests
type: metric type: metric
@ -62,8 +62,8 @@ groups:
# todo (lmolkova) build tools don't populate grandparent attributes # todo (lmolkova) build tools don't populate grandparent attributes
- ref: http.method - ref: http.method
- ref: http.status_code - ref: http.status_code
- ref: net.protocol.name - ref: network.protocol.name
- ref: net.protocol.version - ref: network.protocol.version
- id: metric.http.server.response.size - id: metric.http.server.response.size
type: metric type: metric
@ -76,8 +76,8 @@ groups:
attributes: attributes:
- ref: http.method - ref: http.method
- ref: http.status_code - ref: http.status_code
- ref: net.protocol.name - ref: network.protocol.name
- ref: net.protocol.version - ref: network.protocol.version
- id: metric.http.client.duration - id: metric.http.client.duration
type: metric type: metric
@ -89,8 +89,8 @@ groups:
attributes: attributes:
- ref: http.method - ref: http.method
- ref: http.status_code - ref: http.status_code
- ref: net.protocol.name - ref: network.protocol.name
- ref: net.protocol.version - ref: network.protocol.version
- ref: server.socket.address - ref: server.socket.address
- id: metric.http.client.request.size - id: metric.http.client.request.size
@ -104,8 +104,8 @@ groups:
attributes: attributes:
- ref: http.method - ref: http.method
- ref: http.status_code - ref: http.status_code
- ref: net.protocol.name - ref: network.protocol.name
- ref: net.protocol.version - ref: network.protocol.version
- ref: server.socket.address - ref: server.socket.address
- id: metric.http.client.response.size - id: metric.http.client.response.size
@ -119,6 +119,6 @@ groups:
attributes: attributes:
- ref: http.method - ref: http.method
- ref: http.status_code - ref: http.status_code
- ref: net.protocol.name - ref: network.protocol.name
- ref: net.protocol.version - ref: network.protocol.version
- ref: server.socket.address - ref: server.socket.address

8
semantic_conventions/trace/database.yaml
View File

@ -242,15 +242,13 @@ groups:
tag: connection-level tag: connection-level
- ref: server.socket.port - ref: server.socket.port
tag: connection-level tag: connection-level
- ref: net.sock.family - ref: network.transport
tag: connection-level
- ref: network.type
tag: connection-level tag: connection-level
- ref: server.socket.domain - ref: server.socket.domain
requirement_level: requirement_level:
recommended: If different than `server.address` and if `server.socket.address` is set. recommended: If different than `server.address` and if `server.socket.address` is set.
- ref: net.transport
tag: connection-level
requirement_level:
conditionally_required: If database type is in-process (`"inproc"`), recommended for other database types.
constraints: constraints:
- any_of: - any_of:
- 'server.address' - 'server.address'

88
semantic_conventions/trace/general.yaml
View File

@ -1,6 +1,6 @@
groups: groups:
- id: network-core - id: network-core
prefix: net prefix: network
type: attribute_group type: attribute_group
brief: > brief: >
These attributes may be used for any network related operation. These attributes may be used for any network related operation.
@ -9,67 +9,59 @@ groups:
type: type:
allow_custom_values: true allow_custom_values: true
members: members:
- id: ip_tcp - id: tcp
value: "ip_tcp" value: 'tcp'
- id: ip_udp brief: "TCP"
value: "ip_udp" - id: udp
value: 'udp'
brief: "UDP"
- id: pipe - id: pipe
value: "pipe" value: "pipe"
brief: 'Named or anonymous pipe. See note below.' brief: 'Named or anonymous pipe. See note below.'
- id: inproc - id: unix
value: "inproc" value: 'unix'
brief: 'In-process communication.' brief: "Unix domain socket"
note: >
Signals that there is only in-process communication not using a "real" network protocol
in cases where network attributes would normally be expected. Usually all other network
attributes can be left out in that case.
- id: other
value: "other"
brief: 'Something else (non IP-based).'
brief: > brief: >
Transport protocol used. See note below. [OSI Transport Layer](https://osi-model.com/transport-layer/) or
[Inter-process Communication method](https://en.wikipedia.org/wiki/Inter-process_communication).
The value SHOULD be normalized to lowercase.
examples: ['tcp', 'udp']
- id: type
type:
allow_custom_values: true
members:
- id: ipv4
value: 'ipv4'
brief: "IPv4"
- id: ipv6
value: 'ipv6'
brief: "IPv6"
brief: >
[OSI Network Layer](https://osi-model.com/network-layer/) or non-OSI equivalent.
The value SHOULD be normalized to lowercase.
examples: ['ipv4', 'ipv6']
- id: protocol.name - id: protocol.name
type: string type: string
brief: 'Application layer protocol used. The value SHOULD be normalized to lowercase.' brief: >
[OSI Application Layer](https://osi-model.com/application-layer/) or non-OSI equivalent.
The value SHOULD be normalized to lowercase.
examples: ['amqp', 'http', 'mqtt'] examples: ['amqp', 'http', 'mqtt']
- id: protocol.version - id: protocol.version
type: string type: string
brief: 'Version of the application layer protocol used. See note below.' brief: 'Version of the application layer protocol used. See note below.'
examples: '3.1.1' examples: '3.1.1'
note: > note: >
`net.protocol.version` refers to the version of the protocol used and might be `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 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`. of `0.27.2`, but sends HTTP version `1.1`, this attribute should be set to `1.1`.
- id: sock.family
type:
allow_custom_values: true
members:
- id: inet
value: 'inet'
brief: "IPv4 address"
- id: inet6
value: 'inet6'
brief: "IPv6 address"
- id: unix
value: 'unix'
brief: "Unix domain socket path"
requirement_level:
conditionally_required: >
If different than `inet` and if any of `server.socket.address` or `client.socket.address` are set.
Consumers of telemetry SHOULD accept both IPv4 and IPv6 formats for the address in `server.socket.address` and `client.socket.address`
if `net.sock.family` is not set. This is to support instrumentations that follow previous versions
of this document.
brief: >
Protocol [address family](https://man7.org/linux/man-pages/man7/address_families.7.html) which is used for communication.
examples: ['inet6', 'bluetooth']
- id: network-connection-and-carrier - id: network-connection-and-carrier
prefix: net prefix: network
type: attribute_group type: attribute_group
brief: > brief: >
These attributes may be used for any network related operation. These attributes may be used for any network related operation.
attributes: attributes:
- id: host.connection.type - id: connection.type
type: type:
allow_custom_values: true allow_custom_values: true
members: members:
@ -83,9 +75,9 @@ groups:
value: "unavailable" value: "unavailable"
- id: unknown - id: unknown
value: "unknown" value: "unknown"
brief: 'The internet connection type currently being used by the host.' brief: 'The internet connection type.'
examples: 'wifi' examples: 'wifi'
- id: host.connection.subtype - id: connection.subtype
type: type:
allow_custom_values: true allow_custom_values: true
members: members:
@ -154,19 +146,19 @@ groups:
value: "lte_ca" value: "lte_ca"
brief: 'This describes more details regarding the connection.type. It may be the type of cell technology connection, but it could be used for describing details about a wifi connection.' brief: 'This describes more details regarding the connection.type. It may be the type of cell technology connection, but it could be used for describing details about a wifi connection.'
examples: 'LTE' examples: 'LTE'
- id: host.carrier.name - id: carrier.name
type: string type: string
brief: "The name of the mobile carrier." brief: "The name of the mobile carrier."
examples: "sprint" examples: "sprint"
- id: host.carrier.mcc - id: carrier.mcc
type: string type: string
brief: "The mobile carrier country code." brief: "The mobile carrier country code."
examples: "310" examples: "310"
- id: host.carrier.mnc - id: carrier.mnc
type: string type: string
brief: "The mobile carrier network code." brief: "The mobile carrier network code."
examples: "001" examples: "001"
- id: host.carrier.icc - id: carrier.icc
type: string type: string
brief: "The ISO 3166-1 alpha-2 2-character country code associated with the mobile carrier network." brief: "The ISO 3166-1 alpha-2 2-character country code associated with the mobile carrier network."
examples: "DE" examples: "DE"

6
semantic_conventions/trace/http.yaml
View File

@ -24,8 +24,10 @@ groups:
examples: 3495 examples: 3495
- ref: http.method - ref: http.method
sampling_relevant: true sampling_relevant: true
- ref: net.sock.family - ref: network.transport
examples: ['inet', 'inet6'] requirement_level:
conditionally_required: If not default (`tcp` for `HTTP/1.1` and `HTTP/2`, `udp` for `HTTP/3`).
- ref: network.type
- ref: user_agent.original - ref: user_agent.original
- id: trace.http.client - id: trace.http.client

8
semantic_conventions/trace/messaging.yaml
View File

@ -150,15 +150,17 @@ groups:
tag: connection-level tag: connection-level
- ref: server.socket.port - ref: server.socket.port
tag: connection-level tag: connection-level
- ref: net.sock.family - ref: network.transport
tag: connection-level
- ref: network.type
tag: connection-level tag: connection-level
- ref: server.socket.domain - ref: server.socket.domain
tag: connection-level tag: connection-level
requirement_level: requirement_level:
recommended: If different than `server.address` and if `server.socket.address` is set. recommended: If different than `server.address` and if `server.socket.address` is set.
- ref: net.protocol.name - ref: network.protocol.name
examples: ['amqp', 'mqtt'] examples: ['amqp', 'mqtt']
- ref: net.protocol.version - ref: network.protocol.version
- id: messaging.producer - id: messaging.producer
prefix: messaging prefix: messaging

10
semantic_conventions/trace/rpc.yaml
View File

@ -53,9 +53,8 @@ groups:
- ref: server.socket.port - ref: server.socket.port
requirement_level: requirement_level:
recommended: If different than `server.port` and if `server.socket.address` is set. recommended: If different than `server.port` and if `server.socket.address` is set.
- ref: net.sock.family - ref: network.transport
requirement_level: - ref: network.type
conditionally_required: If and only if `server.socket.address` is set.
- ref: server.address - ref: server.address
requirement_level: required requirement_level: required
brief: > brief: >
@ -67,9 +66,6 @@ groups:
- ref: server.port - ref: server.port
requirement_level: requirement_level:
conditionally_required: See below conditionally_required: See below
- ref: net.transport
requirement_level:
conditionally_required: See below
constraints: constraints:
- any_of: - any_of:
- server.socket.address - server.socket.address
@ -95,6 +91,8 @@ groups:
- ref: client.port - ref: client.port
- ref: client.socket.address - ref: client.socket.address
- ref: client.socket.port - ref: client.socket.port
- ref: network.transport
- ref: network.type
- id: rpc.grpc - id: rpc.grpc
prefix: rpc.grpc prefix: rpc.grpc

36
specification/metrics/semantic_conventions/http-metrics.md
View File

@ -73,15 +73,15 @@ of `[ 0, 0.005, 0.01, 0.025, 0.05, 0.075, 0.1, 0.25, 0.5, 0.75, 1, 2.5, 5, 7.5,
| `http.route` | string | The matched route (path template in the format used by the respective server framework). See note below [1] | `/users/:userID?`; `{controller}/{action}/{id?}` | Conditionally Required: If and only if it's available | | `http.route` | string | The matched route (path template in the format used by the respective server framework). See note below [1] | `/users/:userID?`; `{controller}/{action}/{id?}` | Conditionally Required: If and only if it's available |
| `http.method` | string | HTTP request method. | `GET`; `POST`; `HEAD` | Required | | `http.method` | string | HTTP request method. | `GET`; `POST`; `HEAD` | Required |
| `http.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.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. |
| [`net.protocol.name`](../../trace/semantic_conventions/span-general.md) | string | Application layer protocol used. The value SHOULD be normalized to lowercase. | `amqp`; `http`; `mqtt` | Recommended | | [`network.protocol.name`](../../trace/semantic_conventions/span-general.md) | string | [OSI Application Layer](https://osi-model.com/application-layer/) or non-OSI equivalent. The value SHOULD be normalized to lowercase. | `amqp`; `http`; `mqtt` | Recommended |
| [`net.protocol.version`](../../trace/semantic_conventions/span-general.md) | string | Version of the application layer protocol used. See note below. [2] | `3.1.1` | Recommended | | [`network.protocol.version`](../../trace/semantic_conventions/span-general.md) | string | Version of the application layer protocol used. See note below. [2] | `3.1.1` | Recommended |
| [`server.address`](../../trace/semantic_conventions/span-general.md) | string | Name of the local HTTP server that received the request. [3] | `example.com` | Required | | [`server.address`](../../trace/semantic_conventions/span-general.md) | string | Name of the local HTTP server that received the request. [3] | `example.com` | Required |
| [`server.port`](../../trace/semantic_conventions/span-general.md) | int | Port of the local HTTP server that received the request. [4] | `80`; `8080`; `443` | Conditionally Required: [5] | | [`server.port`](../../trace/semantic_conventions/span-general.md) | int | Port of the local HTTP server that received the request. [4] | `80`; `8080`; `443` | Conditionally Required: [5] |
**[1]:** 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. **[1]:** 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.
SHOULD include the [application root](/specification/trace/semantic_conventions/http.md#http-server-definitions) if there is one. SHOULD include the [application root](/specification/trace/semantic_conventions/http.md#http-server-definitions) if there is one.
**[2]:** `net.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`. **[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]:** Determined by using the first of the following that applies **[3]:** Determined by using the first of the following that applies
@ -158,15 +158,15 @@ This metric is optional.
| `http.route` | string | The matched route (path template in the format used by the respective server framework). See note below [1] | `/users/:userID?`; `{controller}/{action}/{id?}` | Conditionally Required: If and only if it's available | | `http.route` | string | The matched route (path template in the format used by the respective server framework). See note below [1] | `/users/:userID?`; `{controller}/{action}/{id?}` | Conditionally Required: If and only if it's available |
| `http.method` | string | HTTP request method. | `GET`; `POST`; `HEAD` | Required | | `http.method` | string | HTTP request method. | `GET`; `POST`; `HEAD` | Required |
| `http.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.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. |
| [`net.protocol.name`](../../trace/semantic_conventions/span-general.md) | string | Application layer protocol used. The value SHOULD be normalized to lowercase. | `amqp`; `http`; `mqtt` | Recommended | | [`network.protocol.name`](../../trace/semantic_conventions/span-general.md) | string | [OSI Application Layer](https://osi-model.com/application-layer/) or non-OSI equivalent. The value SHOULD be normalized to lowercase. | `amqp`; `http`; `mqtt` | Recommended |
| [`net.protocol.version`](../../trace/semantic_conventions/span-general.md) | string | Version of the application layer protocol used. See note below. [2] | `3.1.1` | Recommended | | [`network.protocol.version`](../../trace/semantic_conventions/span-general.md) | string | Version of the application layer protocol used. See note below. [2] | `3.1.1` | Recommended |
| [`server.address`](../../trace/semantic_conventions/span-general.md) | string | Name of the local HTTP server that received the request. [3] | `example.com` | Required | | [`server.address`](../../trace/semantic_conventions/span-general.md) | string | Name of the local HTTP server that received the request. [3] | `example.com` | Required |
| [`server.port`](../../trace/semantic_conventions/span-general.md) | int | Port of the local HTTP server that received the request. [4] | `80`; `8080`; `443` | Conditionally Required: [5] | | [`server.port`](../../trace/semantic_conventions/span-general.md) | int | Port of the local HTTP server that received the request. [4] | `80`; `8080`; `443` | Conditionally Required: [5] |
**[1]:** 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. **[1]:** 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.
SHOULD include the [application root](/specification/trace/semantic_conventions/http.md#http-server-definitions) if there is one. SHOULD include the [application root](/specification/trace/semantic_conventions/http.md#http-server-definitions) if there is one.
**[2]:** `net.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`. **[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]:** Determined by using the first of the following that applies **[3]:** Determined by using the first of the following that applies
@ -205,15 +205,15 @@ This metric is optional.
| `http.route` | string | The matched route (path template in the format used by the respective server framework). See note below [1] | `/users/:userID?`; `{controller}/{action}/{id?}` | Conditionally Required: If and only if it's available | | `http.route` | string | The matched route (path template in the format used by the respective server framework). See note below [1] | `/users/:userID?`; `{controller}/{action}/{id?}` | Conditionally Required: If and only if it's available |
| `http.method` | string | HTTP request method. | `GET`; `POST`; `HEAD` | Required | | `http.method` | string | HTTP request method. | `GET`; `POST`; `HEAD` | Required |
| `http.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.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. |
| [`net.protocol.name`](../../trace/semantic_conventions/span-general.md) | string | Application layer protocol used. The value SHOULD be normalized to lowercase. | `amqp`; `http`; `mqtt` | Recommended | | [`network.protocol.name`](../../trace/semantic_conventions/span-general.md) | string | [OSI Application Layer](https://osi-model.com/application-layer/) or non-OSI equivalent. The value SHOULD be normalized to lowercase. | `amqp`; `http`; `mqtt` | Recommended |
| [`net.protocol.version`](../../trace/semantic_conventions/span-general.md) | string | Version of the application layer protocol used. See note below. [2] | `3.1.1` | Recommended | | [`network.protocol.version`](../../trace/semantic_conventions/span-general.md) | string | Version of the application layer protocol used. See note below. [2] | `3.1.1` | Recommended |
| [`server.address`](../../trace/semantic_conventions/span-general.md) | string | Name of the local HTTP server that received the request. [3] | `example.com` | Required | | [`server.address`](../../trace/semantic_conventions/span-general.md) | string | Name of the local HTTP server that received the request. [3] | `example.com` | Required |
| [`server.port`](../../trace/semantic_conventions/span-general.md) | int | Port of the local HTTP server that received the request. [4] | `80`; `8080`; `443` | Conditionally Required: [5] | | [`server.port`](../../trace/semantic_conventions/span-general.md) | int | Port of the local HTTP server that received the request. [4] | `80`; `8080`; `443` | Conditionally Required: [5] |
**[1]:** 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. **[1]:** 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.
SHOULD include the [application root](/specification/trace/semantic_conventions/http.md#http-server-definitions) if there is one. SHOULD include the [application root](/specification/trace/semantic_conventions/http.md#http-server-definitions) if there is one.
**[2]:** `net.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`. **[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]:** Determined by using the first of the following that applies **[3]:** Determined by using the first of the following that applies
@ -256,13 +256,13 @@ of `[ 0, 0.005, 0.01, 0.025, 0.05, 0.075, 0.1, 0.25, 0.5, 0.75, 1, 2.5, 5, 7.5,
|---|---|---|---|---| |---|---|---|---|---|
| `http.method` | string | HTTP request method. | `GET`; `POST`; `HEAD` | Required | | `http.method` | string | HTTP request method. | `GET`; `POST`; `HEAD` | Required |
| `http.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.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. |
| [`net.protocol.name`](../../trace/semantic_conventions/span-general.md) | string | Application layer protocol used. The value SHOULD be normalized to lowercase. | `amqp`; `http`; `mqtt` | Recommended | | [`network.protocol.name`](../../trace/semantic_conventions/span-general.md) | string | [OSI Application Layer](https://osi-model.com/application-layer/) or non-OSI equivalent. The value SHOULD be normalized to lowercase. | `amqp`; `http`; `mqtt` | Recommended |
| [`net.protocol.version`](../../trace/semantic_conventions/span-general.md) | string | Version of the application layer protocol used. See note below. [1] | `3.1.1` | Recommended | | [`network.protocol.version`](../../trace/semantic_conventions/span-general.md) | string | Version of the application layer protocol used. See note below. [1] | `3.1.1` | Recommended |
| [`server.address`](../../trace/semantic_conventions/span-general.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` | Required | | [`server.address`](../../trace/semantic_conventions/span-general.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` | Required |
| [`server.port`](../../trace/semantic_conventions/span-general.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] | | [`server.port`](../../trace/semantic_conventions/span-general.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] |
| [`server.socket.address`](../../trace/semantic_conventions/span-general.md) | string | Physical server IP address or Unix socket address. | `10.5.3.2` | Recommended: If different than `server.address`. | | [`server.socket.address`](../../trace/semantic_conventions/span-general.md) | string | Physical server IP address or Unix socket address. | `10.5.3.2` | Recommended: If different than `server.address`. |
**[1]:** `net.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`. **[1]:** `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`.
**[2]:** Determined by using the first of the following that applies **[2]:** Determined by using the first of the following that applies
@ -292,13 +292,13 @@ This metric is optional.
|---|---|---|---|---| |---|---|---|---|---|
| `http.method` | string | HTTP request method. | `GET`; `POST`; `HEAD` | Required | | `http.method` | string | HTTP request method. | `GET`; `POST`; `HEAD` | Required |
| `http.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.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. |
| [`net.protocol.name`](../../trace/semantic_conventions/span-general.md) | string | Application layer protocol used. The value SHOULD be normalized to lowercase. | `amqp`; `http`; `mqtt` | Recommended | | [`network.protocol.name`](../../trace/semantic_conventions/span-general.md) | string | [OSI Application Layer](https://osi-model.com/application-layer/) or non-OSI equivalent. The value SHOULD be normalized to lowercase. | `amqp`; `http`; `mqtt` | Recommended |
| [`net.protocol.version`](../../trace/semantic_conventions/span-general.md) | string | Version of the application layer protocol used. See note below. [1] | `3.1.1` | Recommended | | [`network.protocol.version`](../../trace/semantic_conventions/span-general.md) | string | Version of the application layer protocol used. See note below. [1] | `3.1.1` | Recommended |
| [`server.address`](../../trace/semantic_conventions/span-general.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` | Required | | [`server.address`](../../trace/semantic_conventions/span-general.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` | Required |
| [`server.port`](../../trace/semantic_conventions/span-general.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] | | [`server.port`](../../trace/semantic_conventions/span-general.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] |
| [`server.socket.address`](../../trace/semantic_conventions/span-general.md) | string | Physical server IP address or Unix socket address. | `10.5.3.2` | Recommended: If different than `server.address`. | | [`server.socket.address`](../../trace/semantic_conventions/span-general.md) | string | Physical server IP address or Unix socket address. | `10.5.3.2` | Recommended: If different than `server.address`. |
**[1]:** `net.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`. **[1]:** `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`.
**[2]:** Determined by using the first of the following that applies **[2]:** Determined by using the first of the following that applies
@ -328,13 +328,13 @@ This metric is optional.
|---|---|---|---|---| |---|---|---|---|---|
| `http.method` | string | HTTP request method. | `GET`; `POST`; `HEAD` | Required | | `http.method` | string | HTTP request method. | `GET`; `POST`; `HEAD` | Required |
| `http.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.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. |
| [`net.protocol.name`](../../trace/semantic_conventions/span-general.md) | string | Application layer protocol used. The value SHOULD be normalized to lowercase. | `amqp`; `http`; `mqtt` | Recommended | | [`network.protocol.name`](../../trace/semantic_conventions/span-general.md) | string | [OSI Application Layer](https://osi-model.com/application-layer/) or non-OSI equivalent. The value SHOULD be normalized to lowercase. | `amqp`; `http`; `mqtt` | Recommended |
| [`net.protocol.version`](../../trace/semantic_conventions/span-general.md) | string | Version of the application layer protocol used. See note below. [1] | `3.1.1` | Recommended | | [`network.protocol.version`](../../trace/semantic_conventions/span-general.md) | string | Version of the application layer protocol used. See note below. [1] | `3.1.1` | Recommended |
| [`server.address`](../../trace/semantic_conventions/span-general.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` | Required | | [`server.address`](../../trace/semantic_conventions/span-general.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` | Required |
| [`server.port`](../../trace/semantic_conventions/span-general.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] | | [`server.port`](../../trace/semantic_conventions/span-general.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] |
| [`server.socket.address`](../../trace/semantic_conventions/span-general.md) | string | Physical server IP address or Unix socket address. | `10.5.3.2` | Recommended: If different than `server.address`. | | [`server.socket.address`](../../trace/semantic_conventions/span-general.md) | string | Physical server IP address or Unix socket address. | `10.5.3.2` | Recommended: If different than `server.address`. |
**[1]:** `net.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`. **[1]:** `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`.
**[2]:** Determined by using the first of the following that applies **[2]:** Determined by using the first of the following that applies

7
specification/metrics/semantic_conventions/rpc-metrics.md
View File

@ -95,8 +95,8 @@ measurements.
| [`rpc.system`](../../trace/semantic_conventions/rpc.md) | string | A string identifying the remoting system. See below for a list of well-known identifiers. | `grpc` | Required | | [`rpc.system`](../../trace/semantic_conventions/rpc.md) | string | A string identifying the remoting system. See below for a list of well-known identifiers. | `grpc` | Required |
| [`rpc.service`](../../trace/semantic_conventions/rpc.md) | string | The full (logical) name of the service being called, including its package name, if applicable. [1] | `myservice.EchoService` | Recommended | | [`rpc.service`](../../trace/semantic_conventions/rpc.md) | string | The full (logical) name of the service being called, including its package name, if applicable. [1] | `myservice.EchoService` | Recommended |
| [`rpc.method`](../../trace/semantic_conventions/rpc.md) | string | The name of the (logical) method being called, must be equal to the $method part in the span name. [2] | `exampleMethod` | Recommended | | [`rpc.method`](../../trace/semantic_conventions/rpc.md) | string | The name of the (logical) method being called, must be equal to the $method part in the span name. [2] | `exampleMethod` | Recommended |
| [`net.sock.family`](../../trace/semantic_conventions/span-general.md) | string | Protocol [address family](https://man7.org/linux/man-pages/man7/address_families.7.html) which is used for communication. | `inet6`; `bluetooth` | Conditionally Required: If and only if `server.socket.address` is set. | | [`network.transport`](../../trace/semantic_conventions/span-general.md) | string | [OSI Transport Layer](https://osi-model.com/transport-layer/) or [Inter-process Communication method](https://en.wikipedia.org/wiki/Inter-process_communication). The value SHOULD be normalized to lowercase. | `tcp`; `udp` | Recommended |
| [`net.transport`](../../trace/semantic_conventions/span-general.md) | string | Transport protocol used. See note below. | `ip_tcp` | Conditionally Required: See below | | [`network.type`](../../trace/semantic_conventions/span-general.md) | string | [OSI Network Layer](https://osi-model.com/network-layer/) or non-OSI equivalent. The value SHOULD be normalized to lowercase. | `ipv4`; `ipv6` | Recommended |
| [`server.address`](../../trace/semantic_conventions/span-general.md) | string | RPC server [host name](https://grpc.github.io/grpc/core/md_doc_naming.html). [3] | `example.com` | Required | | [`server.address`](../../trace/semantic_conventions/span-general.md) | string | RPC server [host name](https://grpc.github.io/grpc/core/md_doc_naming.html). [3] | `example.com` | Required |
| [`server.port`](../../trace/semantic_conventions/span-general.md) | int | Logical server port number | `80`; `8080`; `443` | Conditionally Required: See below | | [`server.port`](../../trace/semantic_conventions/span-general.md) | int | Logical server port number | `80`; `8080`; `443` | Conditionally Required: See below |
| [`server.socket.address`](../../trace/semantic_conventions/span-general.md) | string | Physical server IP address or Unix socket address. | `10.5.3.2` | See below | | [`server.socket.address`](../../trace/semantic_conventions/span-general.md) | string | Physical server IP address or Unix socket address. | `10.5.3.2` | See below |
@ -132,9 +132,8 @@ To avoid high cardinality, implementations should prefer the most stable of `ser
For client-side metrics `server.port` is required if the connection is IP-based and the port is available (it describes the server port they are connecting to). For client-side metrics `server.port` is required if the connection is IP-based and the port is available (it describes the server port they are connecting to).
For server-side spans `server.port` is optional (it describes the port the client is connecting from). For server-side spans `server.port` is optional (it describes the port the client is connecting from).
Furthermore, setting [net.transport][] is required for non-IP connection like named pipe bindings.
[net.transport]: ../../trace/semantic_conventions/span-general.md#network-attributes [network.transport]: ../../trace/semantic_conventions/span-general.md#network-attributes
### Service name ### Service name

26
specification/trace/semantic_conventions/database.md
View File

@ -68,18 +68,14 @@ Some database systems may allow a connection to switch to a different `db.user`,
| `db.system` | string | An identifier for the database management system (DBMS) product being used. See below for a list of well-known identifiers. | `other_sql` | Required | | `db.system` | string | An identifier for the database management system (DBMS) product being used. See below for a list of well-known identifiers. | `other_sql` | Required |
| `db.connection_string` | string | The connection string used to connect to the database. It is recommended to remove embedded credentials. | `Server=(localdb)\v11.0;Integrated Security=true;` | Recommended | | `db.connection_string` | string | The connection string used to connect to the database. It is recommended to remove embedded credentials. | `Server=(localdb)\v11.0;Integrated Security=true;` | Recommended |
| `db.user` | string | Username for accessing the database. | `readonly_user`; `reporting_user` | Recommended | | `db.user` | string | Username for accessing the database. | `readonly_user`; `reporting_user` | Recommended |
| [`net.sock.family`](span-general.md) | string | Protocol [address family](https://man7.org/linux/man-pages/man7/address_families.7.html) which is used for communication. | `inet6`; `bluetooth` | Conditionally Required: [1] | | [`network.transport`](span-general.md) | string | [OSI Transport Layer](https://osi-model.com/transport-layer/) or [Inter-process Communication method](https://en.wikipedia.org/wiki/Inter-process_communication). The value SHOULD be normalized to lowercase. | `tcp`; `udp` | Recommended |
| [`net.transport`](span-general.md) | string | Transport protocol used. See note below. | `ip_tcp` | Conditionally Required: [2] | | [`network.type`](span-general.md) | string | [OSI Network Layer](https://osi-model.com/network-layer/) or non-OSI equivalent. The value SHOULD be normalized to lowercase. | `ipv4`; `ipv6` | Recommended |
| [`server.address`](span-general.md) | string | Name of the database host. | `example.com` | Conditionally Required: See alternative attributes below. | | [`server.address`](span-general.md) | string | Name of the database host. | `example.com` | Conditionally Required: See alternative attributes below. |
| [`server.port`](span-general.md) | int | Logical server port number | `80`; `8080`; `443` | Conditionally Required: [3] | | [`server.port`](span-general.md) | int | Logical server port number | `80`; `8080`; `443` | Conditionally Required: [1] |
| [`server.socket.address`](span-general.md) | string | Physical server IP address or Unix socket address. | `10.5.3.2` | See below | | [`server.socket.address`](span-general.md) | string | Physical server IP address or Unix socket address. | `10.5.3.2` | See below |
| [`server.socket.port`](span-general.md) | int | Physical server port. | `16456` | Recommended: If different than `server.port`. | | [`server.socket.port`](span-general.md) | int | Physical server port. | `16456` | Recommended: If different than `server.port`. |
**[1]:** If different than `inet` and if any of `server.socket.address` or `client.socket.address` are set. Consumers of telemetry SHOULD accept both IPv4 and IPv6 formats for the address in `server.socket.address` and `client.socket.address` if `net.sock.family` is not set. This is to support instrumentations that follow previous versions of this document. **[1]:** If using a port other than the default port for this DBMS and if `server.address` is set.
**[2]:** If database type is in-process (`"inproc"`), recommended for other database types.
**[3]:** If using a port other than the default port for this DBMS and if `server.address` is set.
**Additional attribute requirements:** At least one of the following sets of attributes is required: **Additional attribute requirements:** At least one of the following sets of attributes is required:
@ -296,8 +292,8 @@ In addition to Cosmos DB attributes, all spans include
### MySQL ### MySQL
| Key | Value | | Key | Value |
| :---------------------- | :----------------------------------------------------------- | |:------------------------| :----------------------------------------------------------- |
| Span name | `"SELECT ShopDb.orders"` | | Span name | `"SELECT ShopDb.orders"` |
| `db.system` | `"mysql"` | | `db.system` | `"mysql"` |
| `db.connection_string` | `"Server=shopdb.example.com;Database=ShopDb;Uid=billing_user;TableCache=true;UseCompression=True;MinimumPoolSize=10;MaximumPoolSize=50;"` | | `db.connection_string` | `"Server=shopdb.example.com;Database=ShopDb;Uid=billing_user;TableCache=true;UseCompression=True;MinimumPoolSize=10;MaximumPoolSize=50;"` |
@ -305,7 +301,7 @@ In addition to Cosmos DB attributes, all spans include
| `server.address` | `"shopdb.example.com"` | | `server.address` | `"shopdb.example.com"` |
| `server.socket.address` | `"192.0.2.12"` | | `server.socket.address` | `"192.0.2.12"` |
| `server.port` | `3306` | | `server.port` | `3306` |
| `net.transport` | `"IP.TCP"` | | `network.transport` | `"IP.TCP"` |
| `db.name` | `"ShopDb"` | | `db.name` | `"ShopDb"` |
| `db.statement` | `"SELECT * FROM orders WHERE order_id = 'o4711'"` | | `db.statement` | `"SELECT * FROM orders WHERE order_id = 'o4711'"` |
| `db.operation` | `"SELECT"` | | `db.operation` | `"SELECT"` |
@ -316,14 +312,14 @@ In addition to Cosmos DB attributes, all spans include
In this example, Redis is connected using a unix domain socket and therefore the connection string and `server.address` are left out. In this example, Redis is connected using a unix domain socket and therefore the connection string and `server.address` are left out.
Furthermore, `db.name` is not specified as there is no database name in Redis and `db.redis.database_index` is set instead. Furthermore, `db.name` is not specified as there is no database name in Redis and `db.redis.database_index` is set instead.
| Key | Value | | Key | Value |
| :------------------------ | :-------------------------------------------- | |:--------------------------| :-------------------------------------------- |
| Span name | `"HMSET myhash"` | | Span name | `"HMSET myhash"` |
| `db.system` | `"redis"` | | `db.system` | `"redis"` |
| `db.connection_string` | not set | | `db.connection_string` | not set |
| `db.user` | not set | | `db.user` | not set |
| `server.socket.address` | `"/tmp/redis.sock"` | | `server.socket.address` | `"/tmp/redis.sock"` |
| `net.transport` | `"Unix"` | | `network.transport` | `"Unix"` |
| `db.name` | not set | | `db.name` | not set |
| `db.statement` | `"HMSET myhash field1 'Hello' field2 'World"` | | `db.statement` | `"HMSET myhash field1 'Hello' field2 'World"` |
| `db.operation` | not set | | `db.operation` | not set |
@ -340,7 +336,7 @@ Furthermore, `db.name` is not specified as there is no database name in Redis an
| `server.address` | `"mongodb0.example.com"` | | `server.address` | `"mongodb0.example.com"` |
| `server.socket.address` | `"192.0.2.14"` | | `server.socket.address` | `"192.0.2.14"` |
| `server.port` | `27017` | | `server.port` | `27017` |
| `net.transport` | `"IP.TCP"` | | `network.transport` | `"IP.TCP"` |
| `db.name` | `"shopDb"` | | `db.name` | `"shopDb"` |
| `db.statement` | not set | | `db.statement` | not set |
| `db.operation` | `"findAndModify"` | | `db.operation` | `"findAndModify"` |

27
specification/trace/semantic_conventions/http.md
View File

@ -93,26 +93,35 @@ sections below.
| `http.request_content_length` | int | The size of the request 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.request_content_length` | int | The size of the request 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_content_length` | 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_content_length` | 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.method` | string | HTTP request method. | `GET`; `POST`; `HEAD` | Required | | `http.method` | string | HTTP request method. | `GET`; `POST`; `HEAD` | Required |
| [`net.protocol.name`](span-general.md) | string | Application layer protocol used. The value SHOULD be normalized to lowercase. | `http`; `spdy` | Recommended: if not default (`http`). | | [`network.protocol.name`](span-general.md) | string | [OSI Application Layer](https://osi-model.com/application-layer/) or non-OSI equivalent. The value SHOULD be normalized to lowercase. | `http`; `spdy` | Recommended: if not default (`http`). |
| [`net.protocol.version`](span-general.md) | string | Version of the application layer protocol used. See note below. [1] | `1.0`; `1.1`; `2.0` | Recommended | | [`network.protocol.version`](span-general.md) | string | Version of the application layer protocol used. See note below. [1] | `1.0`; `1.1`; `2.0` | Recommended |
| [`net.sock.family`](span-general.md) | string | Protocol [address family](https://man7.org/linux/man-pages/man7/address_families.7.html) which is used for communication. | `inet`; `inet6` | Conditionally Required: [2] | | [`network.transport`](span-general.md) | string | [OSI Transport Layer](https://osi-model.com/transport-layer/) or [Inter-process Communication method](https://en.wikipedia.org/wiki/Inter-process_communication). The value SHOULD be normalized to lowercase. | `tcp`; `udp` | Conditionally Required: [2] |
| [`network.type`](span-general.md) | string | [OSI Network Layer](https://osi-model.com/network-layer/) or non-OSI equivalent. The value SHOULD be normalized to lowercase. | `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 | | `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]:** `net.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`. **[1]:** `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`.
**[2]:** If different than `inet` and if any of `server.socket.address` or `client.socket.address` are set. Consumers of telemetry SHOULD accept both IPv4 and IPv6 formats for the address in `server.socket.address` and `client.socket.address` if `net.sock.family` is not set. This is to support instrumentations that follow previous versions of this document. **[2]:** If not default (`tcp` for `HTTP/1.1` and `HTTP/2`, `udp` for `HTTP/3`).
Following attributes MUST be provided **at span creation time** (when provided at all), so they can be considered for sampling decisions: Following attributes MUST be provided **at span creation time** (when provided at all), so they can be considered for sampling decisions:
* `http.method` * `http.method`
`net.sock.family` 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. `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 | | Value | Description |
|---|---| |---|---|
| `inet` | IPv4 address | | `tcp` | TCP |
| `inet6` | IPv6 address | | `udp` | UDP |
| `unix` | Unix domain socket path | | `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 |
<!-- endsemconv --> <!-- endsemconv -->
### HTTP request and response headers ### HTTP request and response headers

25
specification/trace/semantic_conventions/messaging.md
View File

@ -218,12 +218,13 @@ The following operations related to messages are defined for these semantic conv
| `messaging.message.id` | string | A value used by the messaging system as an identifier for the message, represented as a string. | `452a7c7c7c7048c2f887f61572b18fc2` | Recommended: [5] | | `messaging.message.id` | string | A value used by the messaging system as an identifier for the message, represented as a string. | `452a7c7c7c7048c2f887f61572b18fc2` | Recommended: [5] |
| `messaging.message.payload_compressed_size_bytes` | int | The compressed size of the message payload in bytes. | `2048` | Recommended: [6] | | `messaging.message.payload_compressed_size_bytes` | int | The compressed size of the message payload in bytes. | `2048` | Recommended: [6] |
| `messaging.message.payload_size_bytes` | int | The (uncompressed) size of the message payload in bytes. Also use this attribute if it is unknown whether the compressed or uncompressed payload size is reported. | `2738` | Recommended: [7] | | `messaging.message.payload_size_bytes` | int | The (uncompressed) size of the message payload in bytes. Also use this attribute if it is unknown whether the compressed or uncompressed payload size is reported. | `2738` | Recommended: [7] |
| [`net.protocol.name`](span-general.md) | string | Application layer protocol used. The value SHOULD be normalized to lowercase. | `amqp`; `mqtt` | Recommended | | [`network.protocol.name`](span-general.md) | string | [OSI Application Layer](https://osi-model.com/application-layer/) or non-OSI equivalent. The value SHOULD be normalized to lowercase. | `amqp`; `mqtt` | Recommended |
| [`net.protocol.version`](span-general.md) | string | Version of the application layer protocol used. See note below. [8] | `3.1.1` | Recommended | | [`network.protocol.version`](span-general.md) | string | Version of the application layer protocol used. See note below. [8] | `3.1.1` | Recommended |
| [`net.sock.family`](span-general.md) | string | Protocol [address family](https://man7.org/linux/man-pages/man7/address_families.7.html) which is used for communication. | `inet6`; `bluetooth` | Conditionally Required: [9] | | [`network.transport`](span-general.md) | string | [OSI Transport Layer](https://osi-model.com/transport-layer/) or [Inter-process Communication method](https://en.wikipedia.org/wiki/Inter-process_communication). The value SHOULD be normalized to lowercase. | `tcp`; `udp` | Recommended |
| [`server.address`](span-general.md) | string | Logical server hostname, matches server FQDN if available, and IP or socket address if FQDN is not known. [10] | `example.com` | Conditionally Required: If available. | | [`network.type`](span-general.md) | string | [OSI Network Layer](https://osi-model.com/network-layer/) or non-OSI equivalent. The value SHOULD be normalized to lowercase. | `ipv4`; `ipv6` | Recommended |
| [`server.address`](span-general.md) | string | Logical server hostname, matches server FQDN if available, and IP or socket address if FQDN is not known. [9] | `example.com` | Conditionally Required: If available. |
| [`server.socket.address`](span-general.md) | string | Physical server IP address or Unix socket address. | `10.5.3.2` | Recommended: If different than `server.address`. | | [`server.socket.address`](span-general.md) | string | Physical server IP address or Unix socket address. | `10.5.3.2` | Recommended: If different than `server.address`. |
| [`server.socket.domain`](span-general.md) | string | The domain name of an immediate peer. [11] | `proxy.example.com` | Recommended: [12] | | [`server.socket.domain`](span-general.md) | string | The domain name of an immediate peer. [10] | `proxy.example.com` | Recommended: [11] |
| [`server.socket.port`](span-general.md) | int | Physical server port. | `16456` | Recommended: If different than `server.port`. | | [`server.socket.port`](span-general.md) | int | Physical server port. | `16456` | Recommended: If different than `server.port`. |
**[1]:** If a custom value is used, it MUST be of low cardinality. **[1]:** If a custom value is used, it MUST be of low cardinality.
@ -240,15 +241,13 @@ The following operations related to messages are defined for these semantic conv
**[7]:** Only if span represents operation on a single message. **[7]:** Only if span represents operation on a single message.
**[8]:** `net.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`. **[8]:** `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`.
**[9]:** If different than `inet` and if any of `server.socket.address` or `client.socket.address` are set. Consumers of telemetry SHOULD accept both IPv4 and IPv6 formats for the address in `server.socket.address` and `client.socket.address` if `net.sock.family` is not set. This is to support instrumentations that follow previous versions of this document. **[9]:** This should be the IP/hostname of the broker (or other network-level peer) this specific message is sent to/received from.
**[10]:** This should be the IP/hostname of the broker (or other network-level peer) this specific message is sent to/received from. **[10]:** Typically observed from the client side, and represents a proxy or other intermediary domain name.
**[11]:** Typically observed from the client side, and represents a proxy or other intermediary domain name. **[11]:** If different than `server.address` and if `server.socket.address` is set.
**[12]:** If different than `server.address` and if `server.socket.address` is set.
`messaging.operation` 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. `messaging.operation` 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.
@ -260,7 +259,7 @@ The following operations related to messages are defined for these semantic conv
<!-- endsemconv --> <!-- endsemconv -->
Additionally `server.port` from the [network attributes][] is recommended. Additionally `server.port` from the [network attributes][] is recommended.
Furthermore, it is strongly recommended to add the [`net.transport`][] attribute and follow its guidelines, especially for in-process queueing systems (like [Hangfire][], for example). Furthermore, it is strongly recommended to add the [`network.transport`][] attribute and follow its guidelines, especially for in-process queueing systems (like [Hangfire][], for example).
These attributes should be set to the broker to which the message is sent/from which it is received. These attributes should be set to the broker to which the message is sent/from which it is received.
### Attribute namespaces ### Attribute namespaces
@ -278,7 +277,7 @@ Messaging system-specific attributes MUST be defined in the corresponding `messa
as described in [Attributes specific to certain messaging systems](#attributes-specific-to-certain-messaging-systems). as described in [Attributes specific to certain messaging systems](#attributes-specific-to-certain-messaging-systems).
[network attributes]: span-general.md#server-and-client-attributes [network attributes]: span-general.md#server-and-client-attributes
[`net.transport`]: span-general.md#network-attributes [`network.transport`]: span-general.md#network-attributes
[Hangfire]: https://www.hangfire.io/ [Hangfire]: https://www.hangfire.io/
### Producer attributes ### Producer attributes

8
specification/trace/semantic_conventions/rpc.md
View File

@ -90,8 +90,8 @@ Examples of span names:
| `rpc.system` | string | A string identifying the remoting system. See below for a list of well-known identifiers. | `grpc` | Required | | `rpc.system` | string | A string identifying the remoting system. See below for a list of well-known identifiers. | `grpc` | Required |
| `rpc.service` | string | The full (logical) name of the service being called, including its package name, if applicable. [1] | `myservice.EchoService` | Recommended | | `rpc.service` | string | The full (logical) name of the service being called, including its package name, if applicable. [1] | `myservice.EchoService` | Recommended |
| `rpc.method` | string | The name of the (logical) method being called, must be equal to the $method part in the span name. [2] | `exampleMethod` | Recommended | | `rpc.method` | string | The name of the (logical) method being called, must be equal to the $method part in the span name. [2] | `exampleMethod` | Recommended |
| [`net.sock.family`](span-general.md) | string | Protocol [address family](https://man7.org/linux/man-pages/man7/address_families.7.html) which is used for communication. | `inet6`; `bluetooth` | Conditionally Required: If and only if `server.socket.address` is set. | | [`network.transport`](span-general.md) | string | [OSI Transport Layer](https://osi-model.com/transport-layer/) or [Inter-process Communication method](https://en.wikipedia.org/wiki/Inter-process_communication). The value SHOULD be normalized to lowercase. | `tcp`; `udp` | Recommended |
| [`net.transport`](span-general.md) | string | Transport protocol used. See note below. | `ip_tcp` | Conditionally Required: See below | | [`network.type`](span-general.md) | string | [OSI Network Layer](https://osi-model.com/network-layer/) or non-OSI equivalent. The value SHOULD be normalized to lowercase. | `ipv4`; `ipv6` | Recommended |
| [`server.address`](span-general.md) | string | RPC server [host name](https://grpc.github.io/grpc/core/md_doc_naming.html). [3] | `example.com` | Required | | [`server.address`](span-general.md) | string | RPC server [host name](https://grpc.github.io/grpc/core/md_doc_naming.html). [3] | `example.com` | Required |
| [`server.port`](span-general.md) | int | Logical server port number | `80`; `8080`; `443` | Conditionally Required: See below | | [`server.port`](span-general.md) | int | Logical server port number | `80`; `8080`; `443` | Conditionally Required: See below |
| [`server.socket.address`](span-general.md) | string | Physical server IP address or Unix socket address. | `10.5.3.2` | See below | | [`server.socket.address`](span-general.md) | string | Physical server IP address or Unix socket address. | `10.5.3.2` | See below |
@ -123,7 +123,6 @@ Examples of span names:
For client-side spans `server.port` is required if the connection is IP-based and the port is available (it describes the server port they are connecting to). For client-side spans `server.port` is required if the connection is IP-based and the port is available (it describes the server port they are connecting to).
For server-side spans `client.socket.port` is optional (it describes the port the client is connecting from). For server-side spans `client.socket.port` is optional (it describes the port the client is connecting from).
Furthermore, setting [net.transport][] is required for non-IP connection like named pipe bindings.
#### Service name #### Service name
@ -137,7 +136,6 @@ In this example, spans representing client request should have their `peer.servi
Generally, a user SHOULD NOT set `peer.service` to a fully qualified RPC service name. Generally, a user SHOULD NOT set `peer.service` to a fully qualified RPC service name.
[network attributes]: span-general.md#server-and-client-attributes [network attributes]: span-general.md#server-and-client-attributes
[net.transport]: span-general.md#network-attributes
[`service.name`]: ../../resource/semantic_conventions/README.md#service [`service.name`]: ../../resource/semantic_conventions/README.md#service
[`peer.service`]: span-general.md#general-remote-service-attributes [`peer.service`]: span-general.md#general-remote-service-attributes
@ -162,6 +160,8 @@ Generally, a user SHOULD NOT set `peer.service` to a fully qualified RPC service
| [`client.port`](span-general.md) | int | Client port number [2] | `65123` | Recommended | | [`client.port`](span-general.md) | int | Client port number [2] | `65123` | Recommended |
| [`client.socket.address`](span-general.md) | string | Immediate client peer address - unix domain socket name, IPv4 or IPv6 address. | `/tmp/my.sock`; `127.0.0.1` | Recommended: If different than `client.address`. | | [`client.socket.address`](span-general.md) | string | Immediate client peer address - unix domain socket name, IPv4 or IPv6 address. | `/tmp/my.sock`; `127.0.0.1` | Recommended: If different than `client.address`. |
| [`client.socket.port`](span-general.md) | int | Immediate client peer port number | `35555` | Recommended: If different than `client.port`. | | [`client.socket.port`](span-general.md) | int | Immediate client peer port number | `35555` | Recommended: If different than `client.port`. |
| [`network.transport`](span-general.md) | string | [OSI Transport Layer](https://osi-model.com/transport-layer/) or [Inter-process Communication method](https://en.wikipedia.org/wiki/Inter-process_communication). The value SHOULD be normalized to lowercase. | `tcp`; `udp` | Recommended |
| [`network.type`](span-general.md) | string | [OSI Network Layer](https://osi-model.com/network-layer/) or non-OSI equivalent. The value SHOULD be normalized to lowercase. | `ipv4`; `ipv6` | Recommended |
**[1]:** When observed from the server side, and when communicating through an intermediary, `client.address` SHOULD represent client address behind any intermediaries (e.g. proxies) if it's available. **[1]:** When observed from the server side, and when communicating through an intermediary, `client.address` SHOULD represent client address behind any intermediaries (e.g. proxies) if it's available.

50
specification/trace/semantic_conventions/span-general.md
View File

@ -74,7 +74,7 @@ On client side, it's usually passed in form of URL, connection string, host name
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 only IP address is available, it should be populated on `server.address`. Reverse DNS lookup SHOULD NOT be used to obtain DNS name.
If `net.transport` is `"pipe"`, the absolute path to the file representing it should be used as `server.address`. 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), 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. 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.
@ -86,8 +86,6 @@ _Note: this section applies to socket connections visible to instrumentations. I
Socket-level attributes identify peer and host that are directly connected to each other. Since instrumentations may have limited knowledge on network information, instrumentations SHOULD populate such attributes to the best of their knowledge when populate them at all. Socket-level attributes identify peer and host that are directly connected to each other. Since instrumentations may have limited knowledge on network information, instrumentations SHOULD populate such attributes to the best of their knowledge when populate them at all.
`net.sock.family` identifies address family specified when connecting to the socket. For example, it matches `sa_family` field of `sockaddr` structure on [Linux](https://man7.org/linux/man-pages/man0/sys_socket.h.0p.html) and [Windows](https://docs.microsoft.com/windows/win32/api/winsock/ns-winsock-sockaddr).
_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._ _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._
For IP-based communication, `server.socket.domain` represents either fully qualified domain name of immediate peer and `server.socket.address` to the IP address (or one specific to network family). For IP-based communication, `server.socket.domain` represents either fully qualified domain name of immediate peer and `server.socket.address` to the IP address (or one specific to network family).
@ -165,34 +163,28 @@ if they do not cause breaking changes to HTTP semantic conventions.
<!-- semconv network-core --> <!-- semconv network-core -->
| Attribute | Type | Description | Examples | Requirement Level | | Attribute | Type | Description | Examples | Requirement Level |
|---|---|---|---|---| |---|---|---|---|---|
| `net.transport` | string | Transport protocol used. See note below. | `ip_tcp` | 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). The value SHOULD be normalized to lowercase. | `tcp`; `udp` | Recommended |
| `net.protocol.name` | string | Application layer protocol used. The value SHOULD be normalized to lowercase. | `amqp`; `http`; `mqtt` | Recommended | | `network.type` | string | [OSI Network Layer](https://osi-model.com/network-layer/) or non-OSI equivalent. The value SHOULD be normalized to lowercase. | `ipv4`; `ipv6` | Recommended |
| `net.protocol.version` | string | Version of the application layer protocol used. See note below. [1] | `3.1.1` | Recommended | | `network.protocol.name` | string | [OSI Application Layer](https://osi-model.com/application-layer/) or non-OSI equivalent. The value SHOULD be normalized to lowercase. | `amqp`; `http`; `mqtt` | Recommended |
| `net.sock.family` | string | Protocol [address family](https://man7.org/linux/man-pages/man7/address_families.7.html) which is used for communication. | `inet6`; `bluetooth` | Conditionally Required: [2] | | `network.protocol.version` | string | Version of the application layer protocol used. See note below. [1] | `3.1.1` | Recommended |
**[1]:** `net.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`. **[1]:** `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`.
**[2]:** If different than `inet` and if any of `server.socket.address` or `client.socket.address` are set. Consumers of telemetry SHOULD accept both IPv4 and IPv6 formats for the address in `server.socket.address` and `client.socket.address` if `net.sock.family` is not set. This is to support instrumentations that follow previous versions of this document. `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.
`net.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 | | Value | Description |
|---|---| |---|---|
| `ip_tcp` | ip_tcp | | `tcp` | TCP |
| `ip_udp` | ip_udp | | `udp` | UDP |
| `pipe` | Named or anonymous pipe. See note below. | | `pipe` | Named or anonymous pipe. See note below. |
| `inproc` | In-process communication. [1] | | `unix` | Unix domain socket |
| `other` | Something else (non IP-based). |
**[1]:** Signals that there is only in-process communication not using a "real" network protocol in cases where network attributes would normally be expected. Usually all other network attributes can be left out in that case. `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.
`net.sock.family` 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 | | Value | Description |
|---|---| |---|---|
| `inet` | IPv4 address | | `ipv4` | IPv4 |
| `inet6` | IPv6 address | | `ipv6` | IPv6 |
| `unix` | Unix domain socket path |
<!-- endsemconv --> <!-- endsemconv -->
### Source and destination attributes ### Source and destination attributes
@ -235,14 +227,14 @@ Destination fields capture details about the receiver of a network exchange/pack
<!-- semconv network-connection-and-carrier --> <!-- semconv network-connection-and-carrier -->
| Attribute | Type | Description | Examples | Requirement Level | | Attribute | Type | Description | Examples | Requirement Level |
|---|---|---|---|---| |---|---|---|---|---|
| `net.host.connection.type` | string | The internet connection type currently being used by the host. | `wifi` | Recommended | | `network.connection.type` | string | The internet connection type. | `wifi` | Recommended |
| `net.host.connection.subtype` | string | This describes more details regarding the connection.type. It may be the type of cell technology connection, but it could be used for describing details about a wifi connection. | `LTE` | Recommended | | `network.connection.subtype` | string | This describes more details regarding the connection.type. It may be the type of cell technology connection, but it could be used for describing details about a wifi connection. | `LTE` | Recommended |
| `net.host.carrier.name` | string | The name of the mobile carrier. | `sprint` | Recommended | | `network.carrier.name` | string | The name of the mobile carrier. | `sprint` | Recommended |
| `net.host.carrier.mcc` | string | The mobile carrier country code. | `310` | Recommended | | `network.carrier.mcc` | string | The mobile carrier country code. | `310` | Recommended |
| `net.host.carrier.mnc` | string | The mobile carrier network code. | `001` | Recommended | | `network.carrier.mnc` | string | The mobile carrier network code. | `001` | Recommended |
| `net.host.carrier.icc` | string | The ISO 3166-1 alpha-2 2-character country code associated with the mobile carrier network. | `DE` | Recommended | | `network.carrier.icc` | string | The ISO 3166-1 alpha-2 2-character country code associated with the mobile carrier network. | `DE` | Recommended |
`net.host.connection.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. `network.connection.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 | | Value | Description |
|---|---| |---|---|
@ -252,7 +244,7 @@ Destination fields capture details about the receiver of a network exchange/pack
| `unavailable` | unavailable | | `unavailable` | unavailable |
| `unknown` | unknown | | `unknown` | unknown |
`net.host.connection.subtype` 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. `network.connection.subtype` 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 | | Value | Description |
|---|---| |---|---|