From 1d592b44a77311c1d66b8be0e12e5ac6feaec33a Mon Sep 17 00:00:00 2001 From: Joao Grassi <5938087+joaopgrassi@users.noreply.github.com> Date: Wed, 3 Apr 2024 17:16:14 +0200 Subject: [PATCH] [chore] Move telemetry sdk to the registry (#873) --- .github/ISSUE_TEMPLATE/bug_report.yaml | 1 + .github/ISSUE_TEMPLATE/change_proposal.yaml | 1 + .github/ISSUE_TEMPLATE/new-conventions.yaml | 1 + docs/attributes-registry/README.md | 1 + docs/attributes-registry/telemetry.md | 43 ++++++++++ docs/resource/README.md | 12 +-- model/registry/telemetry.yaml | 87 +++++++++++++++++++++ model/resource/telemetry.yaml | 66 +--------------- model/resource/telemetry_experimental.yaml | 20 +---- 9 files changed, 147 insertions(+), 85 deletions(-) create mode 100644 docs/attributes-registry/telemetry.md create mode 100644 model/registry/telemetry.yaml diff --git a/.github/ISSUE_TEMPLATE/bug_report.yaml b/.github/ISSUE_TEMPLATE/bug_report.yaml index 127f81c39b..42b552f8d0 100644 --- a/.github/ISSUE_TEMPLATE/bug_report.yaml +++ b/.github/ISSUE_TEMPLATE/bug_report.yaml @@ -55,6 +55,7 @@ body: - area:service - area:session - area:source + - area:telemetry - area:thread - area:tls - area:url diff --git a/.github/ISSUE_TEMPLATE/change_proposal.yaml b/.github/ISSUE_TEMPLATE/change_proposal.yaml index fd5350e62c..f44b30f260 100644 --- a/.github/ISSUE_TEMPLATE/change_proposal.yaml +++ b/.github/ISSUE_TEMPLATE/change_proposal.yaml @@ -48,6 +48,7 @@ body: - area:service - area:session - area:source + - area:telemetry - area:thread - area:tls - area:url diff --git a/.github/ISSUE_TEMPLATE/new-conventions.yaml b/.github/ISSUE_TEMPLATE/new-conventions.yaml index ad136536cc..e0d54225ca 100644 --- a/.github/ISSUE_TEMPLATE/new-conventions.yaml +++ b/.github/ISSUE_TEMPLATE/new-conventions.yaml @@ -57,6 +57,7 @@ body: - area:service - area:session - area:source + - area:telemetry - area:thread - area:tls - area:url diff --git a/docs/attributes-registry/README.md b/docs/attributes-registry/README.md index 97f3a63985..e2f068fc5a 100644 --- a/docs/attributes-registry/README.md +++ b/docs/attributes-registry/README.md @@ -61,6 +61,7 @@ Currently, the following namespaces exist: * [Service](service.md) * [Session](session.md) * [Source](source.md) +* [Telemetry](telemetry.md) * [Thread](thread.md) * [TLS](tls.md) * [URL](url.md) diff --git a/docs/attributes-registry/telemetry.md b/docs/attributes-registry/telemetry.md new file mode 100644 index 0000000000..1df6c8d1ff --- /dev/null +++ b/docs/attributes-registry/telemetry.md @@ -0,0 +1,43 @@ + + +# Telemetry SDK + +## Telemetry SDK Attributes + + +| Attribute | Type | Description | Examples | Stability | +|---|---|---|---|---| +| `telemetry.sdk.language` | string | The language of the telemetry SDK. | `cpp` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| `telemetry.sdk.name` | string | The name of the telemetry SDK as defined above. [1] | `opentelemetry` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| `telemetry.sdk.version` | string | The version string of the telemetry SDK. | `1.2.3` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| `telemetry.distro.name` | string | The name of the auto instrumentation agent or distribution, if used. [2] | `parts-unlimited-java` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `telemetry.distro.version` | string | The version string of the auto instrumentation agent or distribution, if used. | `1.2.3` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + +**[1]:** The OpenTelemetry SDK MUST set the `telemetry.sdk.name` attribute to `opentelemetry`. +If another SDK, like a fork or a vendor-provided implementation, is used, this SDK MUST set the +`telemetry.sdk.name` attribute to the fully-qualified class or module name of this SDK's main entry point +or another suitable identifier depending on the language. +The identifier `opentelemetry` is reserved and MUST NOT be used in this case. +All custom identifiers SHOULD be stable across different versions of an implementation. + +**[2]:** Official auto instrumentation agents and distributions SHOULD set the `telemetry.distro.name` attribute to +a string starting with `opentelemetry-`, e.g. `opentelemetry-java-instrumentation`. + +`telemetry.sdk.language` 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 | Stability | +|---|---|---| +| `cpp` | cpp | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| `dotnet` | dotnet | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| `erlang` | erlang | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| `go` | go | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| `java` | java | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| `nodejs` | nodejs | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| `php` | php | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| `python` | python | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| `ruby` | ruby | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| `rust` | rust | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| `swift` | swift | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| `webjs` | webjs | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | + diff --git a/docs/resource/README.md b/docs/resource/README.md index bcbaf2ed41..8dbdf78fbb 100644 --- a/docs/resource/README.md +++ b/docs/resource/README.md @@ -154,12 +154,12 @@ service.name = Shop.shoppingcart **Description:** The telemetry SDK used to capture data recorded by the instrumentation libraries. - + | Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | |---|---|---|---|---|---| -| `telemetry.sdk.language` | string | The language of the telemetry SDK. | `cpp` | `Required` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | -| `telemetry.sdk.name` | string | The name of the telemetry SDK as defined above. [1] | `opentelemetry` | `Required` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | -| `telemetry.sdk.version` | string | The version string of the telemetry SDK. | `1.2.3` | `Required` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| [`telemetry.sdk.language`](../attributes-registry/telemetry.md) | string | The language of the telemetry SDK. | `cpp` | `Required` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| [`telemetry.sdk.name`](../attributes-registry/telemetry.md) | string | The name of the telemetry SDK as defined above. [1] | `opentelemetry` | `Required` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| [`telemetry.sdk.version`](../attributes-registry/telemetry.md) | string | The version string of the telemetry SDK. | `1.2.3` | `Required` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | **[1]:** The OpenTelemetry SDK MUST set the `telemetry.sdk.name` attribute to `opentelemetry`. If another SDK, like a fork or a vendor-provided implementation, is used, this SDK MUST set the @@ -197,8 +197,8 @@ All custom identifiers SHOULD be stable across different versions of an implemen | Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | |---|---|---|---|---|---| -| `telemetry.distro.name` | string | The name of the auto instrumentation agent or distribution, if used. [1] | `parts-unlimited-java` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `telemetry.distro.version` | string | The version string of the auto instrumentation agent or distribution, if used. | `1.2.3` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`telemetry.distro.name`](../attributes-registry/telemetry.md) | string | The name of the auto instrumentation agent or distribution, if used. [1] | `parts-unlimited-java` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`telemetry.distro.version`](../attributes-registry/telemetry.md) | string | The version string of the auto instrumentation agent or distribution, if used. | `1.2.3` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | **[1]:** Official auto instrumentation agents and distributions SHOULD set the `telemetry.distro.name` attribute to a string starting with `opentelemetry-`, e.g. `opentelemetry-java-instrumentation`. diff --git a/model/registry/telemetry.yaml b/model/registry/telemetry.yaml new file mode 100644 index 0000000000..2179330323 --- /dev/null +++ b/model/registry/telemetry.yaml @@ -0,0 +1,87 @@ +groups: + - id: registry.telemetry + prefix: telemetry + type: attribute_group + brief: > + This document defines attributes for telemetry SDK. + attributes: + - id: sdk.name + type: string + stability: stable + requirement_level: required + brief: > + The name of the telemetry SDK as defined above. + note: | + The OpenTelemetry SDK MUST set the `telemetry.sdk.name` attribute to `opentelemetry`. + If another SDK, like a fork or a vendor-provided implementation, is used, this SDK MUST set the + `telemetry.sdk.name` attribute to the fully-qualified class or module name of this SDK's main entry point + or another suitable identifier depending on the language. + The identifier `opentelemetry` is reserved and MUST NOT be used in this case. + All custom identifiers SHOULD be stable across different versions of an implementation. + examples: ["opentelemetry"] + - id: sdk.language + type: + allow_custom_values: true + members: + - id: cpp + value: "cpp" + stability: stable + - id: dotnet + value: "dotnet" + stability: stable + - id: erlang + value: "erlang" + stability: stable + - id: go + value: "go" + stability: stable + - id: java + value: "java" + stability: stable + - id: nodejs + value: "nodejs" + stability: stable + - id: php + value: "php" + stability: stable + - id: python + value: "python" + stability: stable + - id: ruby + value: "ruby" + stability: stable + - id: rust + value: "rust" + stability: stable + - id: swift + value: "swift" + stability: stable + - id: webjs + value: "webjs" + stability: stable + stability: stable + requirement_level: required + brief: > + The language of the telemetry SDK. + - id: sdk.version + type: string + stability: stable + requirement_level: required + brief: > + The version string of the telemetry SDK. + examples: ["1.2.3"] + - id: distro.name + type: string + stability: experimental + brief: > + The name of the auto instrumentation agent or distribution, if used. + note: | + Official auto instrumentation agents and distributions SHOULD set the `telemetry.distro.name` attribute to + a string starting with `opentelemetry-`, e.g. `opentelemetry-java-instrumentation`. + examples: ["parts-unlimited-java"] + - id: distro.version + type: string + stability: experimental + brief: > + The version string of the auto instrumentation agent or distribution, if used. + examples: ["1.2.3"] diff --git a/model/resource/telemetry.yaml b/model/resource/telemetry.yaml index be016372b7..cbc82ce566 100644 --- a/model/resource/telemetry.yaml +++ b/model/resource/telemetry.yaml @@ -1,72 +1,12 @@ groups: - id: telemetry - prefix: telemetry type: resource brief: > The telemetry SDK used to capture data recorded by the instrumentation libraries. attributes: - - id: sdk.name - type: string - stability: stable + - ref: telemetry.sdk.name requirement_level: required - brief: > - The name of the telemetry SDK as defined above. - note: | - The OpenTelemetry SDK MUST set the `telemetry.sdk.name` attribute to `opentelemetry`. - If another SDK, like a fork or a vendor-provided implementation, is used, this SDK MUST set the - `telemetry.sdk.name` attribute to the fully-qualified class or module name of this SDK's main entry point - or another suitable identifier depending on the language. - The identifier `opentelemetry` is reserved and MUST NOT be used in this case. - All custom identifiers SHOULD be stable across different versions of an implementation. - examples: ["opentelemetry"] - - id: sdk.language - type: - allow_custom_values: true - members: - - id: cpp - value: "cpp" - stability: stable - - id: dotnet - value: "dotnet" - stability: stable - - id: erlang - value: "erlang" - stability: stable - - id: go - value: "go" - stability: stable - - id: java - value: "java" - stability: stable - - id: nodejs - value: "nodejs" - stability: stable - - id: php - value: "php" - stability: stable - - id: python - value: "python" - stability: stable - - id: ruby - value: "ruby" - stability: stable - - id: rust - value: "rust" - stability: stable - - id: swift - value: "swift" - stability: stable - - id: webjs - value: "webjs" - stability: stable - stability: stable + - ref: telemetry.sdk.language requirement_level: required - brief: > - The language of the telemetry SDK. - - id: sdk.version - type: string - stability: stable + - ref: telemetry.sdk.version requirement_level: required - brief: > - The version string of the telemetry SDK. - examples: ["1.2.3"] diff --git a/model/resource/telemetry_experimental.yaml b/model/resource/telemetry_experimental.yaml index 6569c8ff87..eb2c508b3a 100644 --- a/model/resource/telemetry_experimental.yaml +++ b/model/resource/telemetry_experimental.yaml @@ -1,22 +1,10 @@ groups: - id: telemetry_experimental - prefix: telemetry type: resource brief: > The telemetry SDK used to capture data recorded by the instrumentation libraries. attributes: - - id: distro.name - type: string - stability: experimental - brief: > - The name of the auto instrumentation agent or distribution, if used. - note: | - Official auto instrumentation agents and distributions SHOULD set the `telemetry.distro.name` attribute to - a string starting with `opentelemetry-`, e.g. `opentelemetry-java-instrumentation`. - examples: ["parts-unlimited-java"] - - id: distro.version - type: string - stability: experimental - brief: > - The version string of the auto instrumentation agent or distribution, if used. - examples: ["1.2.3"] + - ref: telemetry.distro.name + requirement_level: recommended + - ref: telemetry.distro.version + requirement_level: recommended