Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Merge experimental and stable attributes per resource type. #1423

Open
wants to merge 7 commits into
base: main
Choose a base branch
from
+50 −89
Open

Merge experimental and stable attributes per resource type. #1423

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
7 commits
Select commit Hold shift + click to select a range
45227ea
Merge experimental and stable attributes per resource type.
jsuereth Sep 20, 2024
644f4b7
Merge branch 'main' into wip-join-resource-experimental
jsuereth Oct 11, 2024
8b15a62
Regenerate toc.
jsuereth Oct 11, 2024
db0f32c
Add changelog.
jsuereth Oct 11, 2024
ea0ba3a
Update resource template to denote mixed status when resource attribu…
jsuereth Oct 11, 2024
7c5702b
Add end of line to yaml
jsuereth Oct 11, 2024
267fa49
Merge branch 'main' into wip-join-resource-experimental
joaopgrassi Oct 14, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
23 changes: 23 additions & 0 deletions .chloggen/1423.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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)
78 changes: 11 additions & 67 deletions docs/resource/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -22,9 +22,7 @@ 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)
- [Compute Unit](#compute-unit)
- [Compute Instance](#compute-instance)
- [Environment](#environment)
Expand Down Expand Up @@ -81,7 +79,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`

Expand All @@ -90,40 +88,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) |
Copy link
Contributor

@lmolkova lmolkova Oct 16, 2024 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

If we combine it with #1472, we have a problem:

  • stable instrumentations can't emit experimental attributes (by default).
  • they may have a feature-flag that allows to enable experimental parts

but it means that experimental attributes are opt-in.

I think @joaopgrassi recently created a loophole (open-telemetry/weaver#392) we can use here:

- ref: service.instance.id
   requirement_level:
     opt_in:  on stable instrumentations, `recommended` otherwise.

Let's chat more about it (and what else we can do) on the tooling call tomorrow

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

but it means that experimental attributes are opt-in.

Perhaps it is just a lack of orientation/spec on our side to properly make this clear/obvious:

stable instrumentations can't emit experimental attributes (by default)

I wouldn't indicate such thing via the requirement level. I feel this should be a "rule" in semconv that applies to everyone. Then having them in the same table is not a problem.

Perhaps as a UX improvement:

  • Sort stable attributes first
  • Add an empty line in the table to somewhat separate stable vs experimental ones

| [`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).
Expand All @@ -150,7 +121,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.



Expand Down Expand Up @@ -184,7 +155,7 @@ service.name = Shop.shoppingcart
<!-- markdownlint-disable -->


**Status:** ![Stable](https://img.shields.io/badge/-stable-lightgreen)
**Status:** ![Mixed](https://img.shields.io/badge/-mixed-yellow)

**type:** `telemetry.sdk`

Expand All @@ -195,6 +166,8 @@ service.name = Shop.shoppingcart
| [`telemetry.sdk.language`](/docs/attributes-registry/telemetry.md) | string | The language of the telemetry SDK. | `cpp`; `dotnet`; `erlang` | `Required` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) |
| [`telemetry.sdk.name`](/docs/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`](/docs/attributes-registry/telemetry.md) | string | The version string of the telemetry SDK. | `1.2.3` | `Required` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) |
| [`telemetry.distro.name`](/docs/attributes-registry/telemetry.md) | string | The name of the auto instrumentation agent or distribution, if used. [2] | `parts-unlimited-java` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
| [`telemetry.distro.version`](/docs/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]:** 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
Expand All @@ -203,6 +176,9 @@ 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.
Expand All @@ -224,38 +200,6 @@ All custom identifiers SHOULD be stable across different versions of an implemen



<!-- markdownlint-restore -->
<!-- prettier-ignore-end -->
<!-- END AUTOGENERATED TEXT -->
<!-- endsemconv -->

## Telemetry Distribution (Experimental)

<!-- semconv telemetry.sdk_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:** `telemetry.sdk`

**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.distro.name`](/docs/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`](/docs/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`.




<!-- markdownlint-restore -->
<!-- prettier-ignore-end -->
<!-- END AUTOGENERATED TEXT -->
Expand Down
2 changes: 1 addition & 1 deletion docs/resource/browser.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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`

Expand Down
9 changes: 0 additions & 9 deletions model/service/resources-experimental.yaml
View file
Open in desktop

This file was deleted.

2 changes: 2 additions & 0 deletions model/service/resources.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -9,3 +9,5 @@ groups:
- ref: service.name
requirement_level: required
- ref: service.version
- ref: service.namespace
- ref: service.instance.id
11 changes: 0 additions & 11 deletions model/telemetry/resources-experimental.yaml
View file
Open in desktop

This file was deleted.

4 changes: 4 additions & 0 deletions model/telemetry/resources.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -12,3 +12,7 @@ groups:
requirement_level: required
- ref: telemetry.sdk.version
requirement_level: required
- ref: telemetry.distro.name
requirement_level: recommended
- ref: telemetry.distro.version
requirement_level: recommended
9 changes: 8 additions & 1 deletion templates/registry/markdown/resource_macros.j2
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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 }}`

Expand Down
1 change: 1 addition & 0 deletions templates/registry/markdown/stability.j2
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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)
Expand Down
Loading