From f7ad5dd28293f44e4198608c37c4cbff9043aaed Mon Sep 17 00:00:00 2001 From: Johannes Tax Date: Fri, 20 May 2022 14:09:41 -0700 Subject: [PATCH 1/5] Add trace semantic conventions attributes for application layer protocols --- semantic_conventions/trace/general.yaml | 8 ++++++++ specification/trace/semantic_conventions/span-general.md | 2 ++ 2 files changed, 10 insertions(+) diff --git a/semantic_conventions/trace/general.yaml b/semantic_conventions/trace/general.yaml index b8274e3fdc4..aafa0b130e1 100644 --- a/semantic_conventions/trace/general.yaml +++ b/semantic_conventions/trace/general.yaml @@ -33,6 +33,14 @@ groups: brief: 'Something else (non IP-based).' brief: > Transport protocol used. See note below. + - id: protocol.name + type: string + brief: 'Application layer protocol used. The value SHOULD be normalized to lowercase.' + examples: ['amqp', 'http', 'nntp'] + - id: protocol.version + type: string + brief: 'Version of the application layer protocol used.' + examples: '0.9.1' - id: peer.ip type: string brief: > diff --git a/specification/trace/semantic_conventions/span-general.md b/specification/trace/semantic_conventions/span-general.md index 639d468dd53..ddb965d399c 100644 --- a/specification/trace/semantic_conventions/span-general.md +++ b/specification/trace/semantic_conventions/span-general.md @@ -35,6 +35,8 @@ the `net.peer.*` properties of a client are equal to the `net.host.*` properties | Attribute | Type | Description | Examples | Required | |---|---|---|---|---| | `net.transport` | string | Transport protocol used. See note below. | `ip_tcp` | No | +| `net.protocol.name` | string | Application layer protocol used. The value SHOULD be normalized to lowercase. | `amqp`; `http`; `nntp` | No | +| `net.protocol.version` | string | Version of the application layer protocol used. | `0.9.1` | No | | `net.peer.ip` | string | Remote address of the peer (dotted decimal for IPv4 or [RFC5952](https://tools.ietf.org/html/rfc5952) for IPv6) | `127.0.0.1` | No | | `net.peer.port` | int | Remote port number. | `80`; `8080`; `443` | No | | `net.peer.name` | string | Remote hostname or similar, see note below. [1] | `example.com` | No | From 9070d7eff79956f5629cef44b38ee5d3770df115 Mon Sep 17 00:00:00 2001 From: Johannes Tax Date: Thu, 2 Jun 2022 13:09:12 -0700 Subject: [PATCH 2/5] Move net.protocol to net.app.protocol --- semantic_conventions/trace/general.yaml | 8 ++++---- specification/trace/semantic_conventions/span-general.md | 4 ++-- 2 files changed, 6 insertions(+), 6 deletions(-) diff --git a/semantic_conventions/trace/general.yaml b/semantic_conventions/trace/general.yaml index aafa0b130e1..e2715299b88 100644 --- a/semantic_conventions/trace/general.yaml +++ b/semantic_conventions/trace/general.yaml @@ -33,14 +33,14 @@ groups: brief: 'Something else (non IP-based).' brief: > Transport protocol used. See note below. - - id: protocol.name + - id: app.protocol.name type: string brief: 'Application layer protocol used. The value SHOULD be normalized to lowercase.' - examples: ['amqp', 'http', 'nntp'] - - id: protocol.version + examples: ['amqp', 'http', 'mqtt'] + - id: app.protocol.version type: string brief: 'Version of the application layer protocol used.' - examples: '0.9.1' + examples: '3.1.1' - id: peer.ip type: string brief: > diff --git a/specification/trace/semantic_conventions/span-general.md b/specification/trace/semantic_conventions/span-general.md index ddb965d399c..213b5e1aebe 100644 --- a/specification/trace/semantic_conventions/span-general.md +++ b/specification/trace/semantic_conventions/span-general.md @@ -35,8 +35,8 @@ the `net.peer.*` properties of a client are equal to the `net.host.*` properties | Attribute | Type | Description | Examples | Required | |---|---|---|---|---| | `net.transport` | string | Transport protocol used. See note below. | `ip_tcp` | No | -| `net.protocol.name` | string | Application layer protocol used. The value SHOULD be normalized to lowercase. | `amqp`; `http`; `nntp` | No | -| `net.protocol.version` | string | Version of the application layer protocol used. | `0.9.1` | No | +| `net.app.protocol.name` | string | Application layer protocol used. The value SHOULD be normalized to lowercase. | `amqp`; `http`; `mqtt` | No | +| `net.app.protocol.version` | string | Version of the application layer protocol used. | `3.1.1` | No | | `net.peer.ip` | string | Remote address of the peer (dotted decimal for IPv4 or [RFC5952](https://tools.ietf.org/html/rfc5952) for IPv6) | `127.0.0.1` | No | | `net.peer.port` | int | Remote port number. | `80`; `8080`; `443` | No | | `net.peer.name` | string | Remote hostname or similar, see note below. [1] | `example.com` | No | From fa276a472d2cd059b7562e2e6479ba134d67e568 Mon Sep 17 00:00:00 2001 From: Johannes Tax Date: Fri, 10 Jun 2022 11:04:20 -0700 Subject: [PATCH 3/5] PR comments --- semantic_conventions/trace/general.yaml | 6 +++++- specification/trace/semantic_conventions/span-general.md | 8 +++++--- 2 files changed, 10 insertions(+), 4 deletions(-) diff --git a/semantic_conventions/trace/general.yaml b/semantic_conventions/trace/general.yaml index e2715299b88..a172ac79023 100644 --- a/semantic_conventions/trace/general.yaml +++ b/semantic_conventions/trace/general.yaml @@ -39,8 +39,12 @@ groups: examples: ['amqp', 'http', 'mqtt'] - id: app.protocol.version type: string - brief: 'Version of the application layer protocol used.' + brief: 'Version of the application layer protocol used. See note below.' examples: '3.1.1' + note: > + `net.app.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`. - id: peer.ip type: string brief: > diff --git a/specification/trace/semantic_conventions/span-general.md b/specification/trace/semantic_conventions/span-general.md index 213b5e1aebe..885d3921c62 100644 --- a/specification/trace/semantic_conventions/span-general.md +++ b/specification/trace/semantic_conventions/span-general.md @@ -36,10 +36,10 @@ the `net.peer.*` properties of a client are equal to the `net.host.*` properties |---|---|---|---|---| | `net.transport` | string | Transport protocol used. See note below. | `ip_tcp` | No | | `net.app.protocol.name` | string | Application layer protocol used. The value SHOULD be normalized to lowercase. | `amqp`; `http`; `mqtt` | No | -| `net.app.protocol.version` | string | Version of the application layer protocol used. | `3.1.1` | No | +| `net.app.protocol.version` | string | Version of the application layer protocol used. See note below. [1] | `3.1.1` | No | | `net.peer.ip` | string | Remote address of the peer (dotted decimal for IPv4 or [RFC5952](https://tools.ietf.org/html/rfc5952) for IPv6) | `127.0.0.1` | No | | `net.peer.port` | int | Remote port number. | `80`; `8080`; `443` | No | -| `net.peer.name` | string | Remote hostname or similar, see note below. [1] | `example.com` | No | +| `net.peer.name` | string | Remote hostname or similar, see note below. [2] | `example.com` | No | | `net.host.ip` | string | Like `net.peer.ip` but for the host IP. Useful in case of a multi-IP host. | `192.168.0.1` | No | | `net.host.port` | int | Like `net.peer.port` but for the host port. | `35555` | No | | `net.host.name` | string | Local hostname or similar, see note below. | `localhost` | No | @@ -50,7 +50,9 @@ the `net.peer.*` properties of a client are equal to the `net.host.*` properties | `net.host.carrier.mnc` | string | The mobile carrier network code. | `001` | No | | `net.host.carrier.icc` | string | The ISO 3166-1 alpha-2 2-character country code associated with the mobile carrier network. | `DE` | No | -**[1]:** `net.peer.name` SHOULD NOT be set if capturing it would require an extra DNS lookup. +**[1]:** `net.app.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]:** `net.peer.name` SHOULD NOT be set if capturing it would require an extra DNS lookup. `net.transport` MUST be one of the following: From b28c337de263791ae338864edc9550337de96370 Mon Sep 17 00:00:00 2001 From: Johannes Tax Date: Fri, 10 Jun 2022 11:06:00 -0700 Subject: [PATCH 4/5] Add Changelog entry --- CHANGELOG.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/CHANGELOG.md b/CHANGELOG.md index 5a49d1c6ad7..aead0269d91 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -87,6 +87,8 @@ release. - Change JVM runtime metric `process.runtime.jvm.memory.max` to `process.runtime.jvm.memory.limit` - ([#2605](https://github.com/open-telemetry/opentelemetry-specification/pull/2605)). +- Add `net.app.protocol.*` attributes + ([#2602](https://github.com/open-telemetry/opentelemetry-specification/pull/2602)). ### Compatibility From 519664825e14d851cea253a8221e8b88bc44f637 Mon Sep 17 00:00:00 2001 From: Johannes Tax Date: Fri, 10 Jun 2022 15:52:57 -0700 Subject: [PATCH 5/5] Fix Changelog --- CHANGELOG.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index aead0269d91..d4184a4e9e4 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -19,6 +19,9 @@ release. ### Semantic Conventions +- Add `net.app.protocol.*` attributes + ([#2602](https://github.com/open-telemetry/opentelemetry-specification/pull/2602)). + ### Compatibility ### OpenTelemetry Protocol @@ -87,8 +90,6 @@ release. - Change JVM runtime metric `process.runtime.jvm.memory.max` to `process.runtime.jvm.memory.limit` - ([#2605](https://github.com/open-telemetry/opentelemetry-specification/pull/2605)). -- Add `net.app.protocol.*` attributes - ([#2602](https://github.com/open-telemetry/opentelemetry-specification/pull/2602)). ### Compatibility