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

Merge experimental and stable attributes per resource type. (#1423) 

Co-authored-by: Joao Grassi <5938087+joaopgrassi@users.noreply.github.com>
This commit is contained in:
Josh Suereth 2024-11-06 11:24:28 -05:00 committed by GitHub
parent de8f94ed5c
commit 2ce39aa87d
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
10 changed files with 62 additions and 59 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

23
.chloggen/1423.yaml Normal file
View File

@ -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)

45
docs/resource/README.md
View File

@ -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
<!-- markdownlint-disable -->
**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`.
<!-- markdownlint-restore -->
<!-- prettier-ignore-end -->
<!-- END AUTOGENERATED TEXT -->
<!-- endsemconv -->
## Service (Experimental)
<!-- semconv service_experimental -->
<!-- NOTE: THIS TEXT IS AUTOGENERATED. DO NOT EDIT BY HAND. -->
<!-- see templates/registry/markdown/snippet.md.j2 -->
<!-- prettier-ignore-start -->
<!-- markdownlint-capture -->
<!-- markdownlint-disable -->
**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.
<!-- markdownlint-restore -->
<!-- prettier-ignore-end -->
@ -219,9 +194,9 @@ All custom identifiers SHOULD be stable across different versions of an implemen
<!-- END AUTOGENERATED TEXT -->
<!-- endsemconv -->
## Telemetry Distribution (Experimental)
## Telemetry Distro
<!-- semconv telemetry.sdk_experimental -->
<!-- semconv telemetry.distro -->
<!-- NOTE: THIS TEXT IS AUTOGENERATED. DO NOT EDIT BY HAND. -->
<!-- see templates/registry/markdown/snippet.md.j2 -->
<!-- prettier-ignore-start -->
@ -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 |
|---|---|---|---|---|---|

2
docs/resource/browser.md
View File

@ -8,7 +8,7 @@
<!-- markdownlint-disable -->
**Status:** ![Experimental](https://img.shields.io/badge/-experimental-blue)
**Status:** ![Mixed](https://img.shields.io/badge/-mixed-yellow)
**type:** `browser`

9
model/service/resources-experimental.yaml
View File

@ -1,9 +0,0 @@
groups:
- id: service_experimental
type: resource
name: 'service'
brief: >
A service instance.
attributes:
- ref: service.namespace
- ref: service.instance.id

2
model/service/resources.yaml
View File

@ -9,3 +9,5 @@ groups:
- ref: service.name
requirement_level: required
- ref: service.version
- ref: service.namespace
- ref: service.instance.id

11
model/telemetry/resources-experimental.yaml
View File

@ -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

11
model/telemetry/resources.yaml
View File

@ -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

8
policies/group_stability.rego
View File

@ -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[_]

9
templates/registry/markdown/resource_macros.j2
View File

@ -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 }}`

1
templates/registry/markdown/stability.j2
View File

@ -1,5 +1,6 @@
{% macro badge(stability, deprecated) -%}
{%- if deprecated %}![Deprecated](https://img.shields.io/badge/-deprecated-red)<br>{{ 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)