diff --git a/.chloggen/1423.yaml b/.chloggen/1423.yaml new file mode 100644 index 000000000..ec61d6449 --- /dev/null +++ b/.chloggen/1423.yaml @@ -0,0 +1,23 @@ +# Use this changelog template to create an entry for release notes. +# +# If your change doesn't affect end users you should instead start +# your pull request title with [chore] or use the "Skip Changelog" label. + +# One of 'breaking', 'deprecation', 'new_component', 'enhancement', 'bug_fix' +change_type: bug_fix + +# The name of the area of concern in the attributes-registry, (e.g. http, cloud, db) +component: service + +# A brief description of the change. Surround your text with quotes ("") if it needs to start with a backtick (`). +note: "Merge `resource` experimental and stable groups for service and telemetry.sdk" + +# Mandatory: One or more tracking issues related to the change. You can use the PR number here if no issue exists. +# The values here must be integers. +issues: [1423] + +# (Optional) One or more lines of additional information to render under the primary note. +# These lines will be padded with 2 spaces and then inserted directly into the document. +# Use pipe (|) for multiline entries. +subtext: | + Discovered when fixing [weaver#306](https://github.com/open-telemetry/weaver/issues/306#issue-2458430277) diff --git a/docs/resource/README.md b/docs/resource/README.md index 3ea6a9c66..dcf089400 100644 --- a/docs/resource/README.md +++ b/docs/resource/README.md @@ -22,9 +22,8 @@ This document defines standard attributes for resources. These attributes are ty - [Semantic Attributes with Dedicated Environment Variable](#semantic-attributes-with-dedicated-environment-variable) - [Semantic Attributes with SDK-provided Default Value](#semantic-attributes-with-sdk-provided-default-value) - [Service](#service) -- [Service (Experimental)](#service-experimental) - [Telemetry SDK](#telemetry-sdk) -- [Telemetry Distribution (Experimental)](#telemetry-distribution-experimental) +- [Telemetry Distro](#telemetry-distro) - [Compute Unit](#compute-unit) - [Compute Instance](#compute-instance) - [Environment](#environment) @@ -81,7 +80,7 @@ as specified in the [Resource SDK specification](https://github.com/open-telemet -**Status:** ![Stable](https://img.shields.io/badge/-stable-lightgreen) +**Status:** ![Mixed](https://img.shields.io/badge/-mixed-yellow) **type:** `service` @@ -90,37 +89,13 @@ as specified in the [Resource SDK specification](https://github.com/open-telemet | Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | |---|---|---|---|---|---| | [`service.name`](/docs/attributes-registry/service.md) | string | Logical name of the service. [1] | `shoppingcart` | `Required` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| [`service.instance.id`](/docs/attributes-registry/service.md) | string | The string ID of the service instance. [2] | `627cc493-f310-47de-96bd-71410b7dec09` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`service.namespace`](/docs/attributes-registry/service.md) | string | A namespace for `service.name`. [3] | `Shop` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`service.version`](/docs/attributes-registry/service.md) | string | The version string of the service API or implementation. The format is not defined by these conventions. | `2.0.0`; `a01dbef8a` | `Recommended` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | **[1]:** MUST be the same for all instances of horizontally scaled services. If the value was not specified, SDKs MUST fallback to `unknown_service:` concatenated with [`process.executable.name`](process.md), e.g. `unknown_service:bash`. If `process.executable.name` is not available, the value MUST be set to `unknown_service`. - - - - - -## Service (Experimental) - - - - - - - - - -**Status:** ![Experimental](https://img.shields.io/badge/-experimental-blue) - -**type:** `service` - -**Description:** A service instance. - -| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | -|---|---|---|---|---|---| -| [`service.instance.id`](/docs/attributes-registry/service.md) | string | The string ID of the service instance. [1] | `627cc493-f310-47de-96bd-71410b7dec09` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| [`service.namespace`](/docs/attributes-registry/service.md) | string | A namespace for `service.name`. [2] | `Shop` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | - -**[1]:** MUST be unique for each instance of the same `service.namespace,service.name` pair (in other words +**[2]:** MUST be unique for each instance of the same `service.namespace,service.name` pair (in other words `service.namespace,service.name,service.instance.id` triplet MUST be globally unique). The ID helps to distinguish instances of the same service that exist at the same time (e.g. instances of a horizontally scaled service). @@ -147,7 +122,7 @@ However, Collectors can set the `service.instance.id` if they can unambiguously for that telemetry. This is typically the case for scraping receivers, as they know the target address and port. -**[2]:** A string value having a meaning that helps to distinguish a group of services, for example the team name that owns a group of services. `service.name` is expected to be unique within the same namespace. If `service.namespace` is not specified in the Resource then `service.name` is expected to be unique for all services that have no explicit namespace defined (so the empty/unspecified namespace is simply one more valid namespace). Zero-length namespace string is assumed equal to unspecified namespace. +**[3]:** A string value having a meaning that helps to distinguish a group of services, for example the team name that owns a group of services. `service.name` is expected to be unique within the same namespace. If `service.namespace` is not specified in the Resource then `service.name` is expected to be unique for all services that have no explicit namespace defined (so the empty/unspecified namespace is simply one more valid namespace). Zero-length namespace string is assumed equal to unspecified namespace. @@ -219,9 +194,9 @@ All custom identifiers SHOULD be stable across different versions of an implemen -## Telemetry Distribution (Experimental) +## Telemetry Distro - + @@ -231,9 +206,9 @@ All custom identifiers SHOULD be stable across different versions of an implemen **Status:** ![Experimental](https://img.shields.io/badge/-experimental-blue) -**type:** `telemetry.sdk` +**type:** `telemetry.distro` -**Description:** The telemetry SDK used to capture data recorded by the instrumentation libraries. +**Description:** The distribution of 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 | |---|---|---|---|---|---| diff --git a/docs/resource/browser.md b/docs/resource/browser.md index 718e49b7b..4264df66e 100644 --- a/docs/resource/browser.md +++ b/docs/resource/browser.md @@ -8,7 +8,7 @@ -**Status:** ![Experimental](https://img.shields.io/badge/-experimental-blue) +**Status:** ![Mixed](https://img.shields.io/badge/-mixed-yellow) **type:** `browser` diff --git a/model/service/resources-experimental.yaml b/model/service/resources-experimental.yaml deleted file mode 100644 index 861f26862..000000000 --- a/model/service/resources-experimental.yaml +++ /dev/null @@ -1,9 +0,0 @@ -groups: - - id: service_experimental - type: resource - name: 'service' - brief: > - A service instance. - attributes: - - ref: service.namespace - - ref: service.instance.id diff --git a/model/service/resources.yaml b/model/service/resources.yaml index b5a3d27f0..5e24e377c 100644 --- a/model/service/resources.yaml +++ b/model/service/resources.yaml @@ -9,3 +9,5 @@ groups: - ref: service.name requirement_level: required - ref: service.version + - ref: service.namespace + - ref: service.instance.id diff --git a/model/telemetry/resources-experimental.yaml b/model/telemetry/resources-experimental.yaml deleted file mode 100644 index 6a660cc84..000000000 --- a/model/telemetry/resources-experimental.yaml +++ /dev/null @@ -1,11 +0,0 @@ -groups: - - id: telemetry.sdk_experimental - type: resource - name: 'telemetry.sdk' - brief: > - The telemetry SDK used to capture data recorded by the instrumentation libraries. - attributes: - - ref: telemetry.distro.name - requirement_level: recommended - - ref: telemetry.distro.version - requirement_level: recommended diff --git a/model/telemetry/resources.yaml b/model/telemetry/resources.yaml index bdd4350b7..42511f5ce 100644 --- a/model/telemetry/resources.yaml +++ b/model/telemetry/resources.yaml @@ -12,3 +12,14 @@ groups: requirement_level: required - ref: telemetry.sdk.version requirement_level: required + - id: telemetry.distro + name: 'telemetry.distro' + type: resource + stability: experimental + brief: > + The distribution of telemetry SDK used to capture data recorded by the instrumentation libraries. + attributes: + - ref: telemetry.distro.name + requirement_level: recommended + - ref: telemetry.distro.version + requirement_level: recommended diff --git a/policies/group_stability.rego b/policies/group_stability.rego index ada9d7baa..c549709bc 100644 --- a/policies/group_stability.rego +++ b/policies/group_stability.rego @@ -7,8 +7,12 @@ deny[group_stability_violation(description, group.id, name)] { group.type != "attribute_group" group.stability == "stable" - # TODO: https://github.com/open-telemetry/semantic-conventions/issues/1514 - exceptions = {"metric.kestrel.connection.duration", "metric.kestrel.tls_handshake.duration"} + exceptions = { + # TODO: https://github.com/open-telemetry/semantic-conventions/issues/1514 + "metric.kestrel.connection.duration", "metric.kestrel.tls_handshake.duration", + # TODO: https://github.com/open-telemetry/semantic-conventions/issues/1519 + "service", + } not exceptions[group.id] attr := group.attributes[_] diff --git a/templates/registry/markdown/resource_macros.j2 b/templates/registry/markdown/resource_macros.j2 index 3daa7f1d4..f19680cbd 100644 --- a/templates/registry/markdown/resource_macros.j2 +++ b/templates/registry/markdown/resource_macros.j2 @@ -1,7 +1,14 @@ {#- Macros for simplifying creating "Resource" documentation. -#} {% import 'stability.j2' as stability %} +{% macro real_stability(resource) %} +{% if resource.attributes | map(attribute='stability') | unique | length > 1 -%} +{{ stability.badge("mixed", "") }} +{%- else -%} +{{ stability.badge(resource.stability, resource.deprecated) }} +{%- endif %} +{% endmacro %} {% macro header(resource) %} -**Status:** {{ stability.badge(resource.stability, resource.deprecated) }} +**Status:** {{ real_stability(resource) | trim }} **type:** `{{ resource.name }}` diff --git a/templates/registry/markdown/stability.j2 b/templates/registry/markdown/stability.j2 index 0fc901e5d..c623908ba 100644 --- a/templates/registry/markdown/stability.j2 +++ b/templates/registry/markdown/stability.j2 @@ -1,5 +1,6 @@ {% macro badge(stability, deprecated) -%} {%- if deprecated %}![Deprecated](https://img.shields.io/badge/-deprecated-red)
{{ deprecated | trim }} +{%- elif stability == "mixed" %}![Mixed](https://img.shields.io/badge/-mixed-yellow) {%- elif stability == "stable" %}![Stable](https://img.shields.io/badge/-stable-lightgreen) {%- elif stability == "deprecated" %}![Deprecated](https://img.shields.io/badge/-deprecated-red) {%- else %}![Experimental](https://img.shields.io/badge/-experimental-blue)