Use YAML descriptions for Resources

.chloggen/2921.yaml

@@ -0,0 +1,30 @@
+# 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: enhancement
+
+# The name of the area of concern in the attributes-registry, (e.g. http, cloud, db)
+component: other
+
+# A brief description of the change. Surround your text with quotes ("") if it needs to start with a backtick (`).
+note: Update resource to include stability in the YAML file
+
+# 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: [1399]
+
+# (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: >
+  Makes the following changes:
+
+  - Require `name` on resource groups.
+  - Enforce backwards compatibility stability requirements on resource groups.
+  - Rename `telemetry` to `telemetry.sdk`, attributes are unchanged.
+  - Mark `telemetry.sdk` and `resource` as stable in YAML model.
+  - Markdown templates for resource groups NOW includes header describing
+    the reosurce `type`, `stability` and `description`.

docs/resource/README.md

@@ -73,19 +73,20 @@ as specified in the [Resource SDK specification](https://github.com/open-telemet
 
 ## Service
 
-**Status**: [Stable][DocumentStatus]
-
-**type:** `service`
-
-**Description:** A service instance.
-
 <!-- semconv service -->
 <!-- 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:** ![Stable](https://img.shields.io/badge/-stable-lightgreen)
+
+**type:** `service`
+
+**Description:** A service instance.
+
 | 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) |
@@ -103,19 +104,20 @@ as specified in the [Resource SDK specification](https://github.com/open-telemet
 
 ## Service (Experimental)
 
-**Status**: [Experimental][DocumentStatus]
-
-**type:** `service`
-
-**Description:** Additions to service instance.
-
 <!-- 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) |
@@ -174,19 +176,20 @@ service.name = Shop.shoppingcart
 
 ## Telemetry SDK
 
-**Status**: [Stable][DocumentStatus]
-
-**type:** `telemetry.sdk`
-
-**Description:** The telemetry SDK used to capture data recorded by the instrumentation libraries.
-
-<!-- semconv telemetry -->
+<!-- semconv telemetry.sdk -->
 <!-- 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:** ![Stable](https://img.shields.io/badge/-stable-lightgreen)
+
+**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.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) |
@@ -228,19 +231,20 @@ All custom identifiers SHOULD be stable across different versions of an implemen
 
 ## Telemetry Distribution (Experimental)
 
-**Status**: [Experimental][DocumentStatus]
-
-**type:** `telemetry.distro`
-
-**Description:** The telemetry distribution (distro) used to capture data recorded by the instrumentation libraries.
-
-<!-- semconv telemetry_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) |

docs/resource/android.md

@@ -1,18 +1,19 @@
 # Android
 
-**Status**: [Experimental][DocumentStatus]
-
-**type:** `android`
-
-**Description**: The Android platform on which the Android application is running.
-
 <!-- semconv android -->
 <!-- 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:** `android`
+
+**Description:** The Android platform on which the Android application is running.
+
 | Attribute  | Type | Description  | Examples  | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability |
 |---|---|---|---|---|---|
 | [`android.os.api_level`](/docs/attributes-registry/android.md) | string | Uniquely identifies the framework API revision offered by a version (`os.version`) of the android operating system. More information can be found [here](https://developer.android.com/guide/topics/manifest/uses-sdk-element#ApiLevels). | `33`; `32` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
@@ -22,5 +23,3 @@
 <!-- prettier-ignore-end -->
 <!-- END AUTOGENERATED TEXT -->
 <!-- endsemconv -->
-
-[DocumentStatus]: https://opentelemetry.io/docs/specs/otel/document-status

docs/resource/browser.md

@@ -1,20 +1,19 @@
 # Browser
 
-**Status**: [Experimental][DocumentStatus]
-
-**type:** `browser`
-
-**Description**: The web browser in which the application represented by the resource is running. The `browser.*` attributes MUST be used only for resources that represent applications running in a web browser (regardless of whether running on a mobile or desktop device).
-
-All of these attributes can be provided by the user agent itself in the form of an HTTP header (e.g. Sec-CH-UA, Sec-CH-Platform, User-Agent). However, the headers could be removed by proxy servers, and are tied to calls from individual clients. In order to support batching through services like the Collector and to prevent loss of data (e.g. due to proxy servers removing headers), these attributes should be used when possible.
-
 <!-- semconv browser -->
 <!-- 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:** `browser`
+
+**Description:** The web browser in which the application represented by the resource is running. The `browser.*` attributes MUST be used only for resources that represent applications running in a web browser (regardless of whether running on a mobile or desktop device).
+
 | Attribute  | Type | Description  | Examples  | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability |
 |---|---|---|---|---|---|
 | [`browser.brands`](/docs/attributes-registry/browser.md) | string[] | Array of brand name and version separated by a space [1] | `[" Not A;Brand 99", "Chromium 99", "Chrome 99"]` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
@@ -42,4 +41,4 @@ The list of possible values is defined in the [W3C User-Agent Client Hints speci
 <!-- END AUTOGENERATED TEXT -->
 <!-- endsemconv -->
 
-[DocumentStatus]: https://opentelemetry.io/docs/specs/otel/document-status
+All of these attributes can be provided by the user agent itself in the form of an HTTP header (e.g. Sec-CH-UA, Sec-CH-Platform, User-Agent). However, the headers could be removed by proxy servers, and are tied to calls from individual clients. In order to support batching through services like the Collector and to prevent loss of data (e.g. due to proxy servers removing headers), these attributes should be used when possible.

docs/resource/cloud-provider/aws/ecs.md

@@ -1,18 +1,19 @@
 # AWS ECS
 
-**Status**: [Experimental][DocumentStatus]
-
-**type:** `aws.ecs`
-
-**Description:** Resources used by AWS Elastic Container Service (ECS).
-
 <!-- semconv aws.ecs -->
 <!-- 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:** `aws.ecs`
+
+**Description:** Resources used by AWS Elastic Container Service (ECS).
+
 | Attribute  | Type | Description  | Examples  | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability |
 |---|---|---|---|---|---|
 | [`aws.ecs.task.id`](/docs/attributes-registry/aws.md) | string | The ID of a running ECS task. The ID MUST be extracted from `task.arn`. | `10838bed-421f-43ef-870a-f43feacbbb5b`; `23ebb8ac-c18f-46c6-8bbe-d55d0e37cfbd` | `Conditionally Required` If and only if `task.arn` is populated. | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
@@ -36,5 +37,3 @@
 <!-- prettier-ignore-end -->
 <!-- END AUTOGENERATED TEXT -->
 <!-- endsemconv -->
-
-[DocumentStatus]: https://opentelemetry.io/docs/specs/otel/document-status

docs/resource/cloud-provider/aws/eks.md

@@ -1,18 +1,19 @@
 # AWS EKS
 
-**Status**: [Experimental][DocumentStatus]
-
-**type:** `aws.eks`
-
-**Description:** Resources used by AWS Elastic Kubernetes Service (EKS).
-
 <!-- semconv aws.eks -->
 <!-- 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:** `aws.eks`
+
+**Description:** Resources used by AWS Elastic Kubernetes Service (EKS).
+
 | Attribute  | Type | Description  | Examples  | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability |
 |---|---|---|---|---|---|
 | [`aws.eks.cluster.arn`](/docs/attributes-registry/aws.md) | string | The ARN of an EKS cluster. | `arn:aws:ecs:us-west-2:123456789123:cluster/my-cluster` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
@@ -22,5 +23,3 @@
 <!-- prettier-ignore-end -->
 <!-- END AUTOGENERATED TEXT -->
 <!-- endsemconv -->
-
-[DocumentStatus]: https://opentelemetry.io/docs/specs/otel/document-status

docs/resource/cloud-provider/aws/logs.md

@@ -1,18 +1,19 @@
 # AWS Logs
 
-**Status**: [Experimental][DocumentStatus]
-
-**Type:** `aws.log`
-
-**Description:** Log attributes for Amazon Web Services.
-
 <!-- semconv aws.log -->
 <!-- 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:** `aws.log`
+
+**Description:** Resources specific to Amazon Web Services.
+
 | Attribute  | Type | Description  | Examples  | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability |
 |---|---|---|---|---|---|
 | [`aws.log.group.arns`](/docs/attributes-registry/aws.md) | string[] | The Amazon Resource Name(s) (ARN) of the AWS log group(s). [1] | `["arn:aws:logs:us-west-1:123456789012:log-group:/aws/my/group:*"]` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
@@ -33,5 +34,3 @@
 <!-- prettier-ignore-end -->
 <!-- END AUTOGENERATED TEXT -->
 <!-- endsemconv -->
-
-[DocumentStatus]: https://opentelemetry.io/docs/specs/otel/document-status

docs/resource/cloud-provider/gcp/cloud-run.md

@@ -4,17 +4,20 @@
 
 These conventions are recommended for resources running on Cloud Run.
 
-**Type:** `gcp.cloud_run`
-
-**Description:** Resource attributes for Cloud Run.
-
 <!-- semconv gcp.cloud_run -->
 <!-- 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:** `gcp.cloud_run`
+
+**Description:** Resource used by Google Cloud Run.
+
 | Attribute  | Type | Description  | Examples  | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability |
 |---|---|---|---|---|---|
 | [`gcp.cloud_run.job.execution`](/docs/attributes-registry/gcp.md) | string | The name of the Cloud Run [execution](https://cloud.google.com/run/docs/managing/job-executions) being run for the Job, as set by the [`CLOUD_RUN_EXECUTION`](https://cloud.google.com/run/docs/container-contract#jobs-env-vars) environment variable. | `job-name-xxxx`; `sample-job-mdw84` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) |

docs/resource/cloud-provider/gcp/gce.md

@@ -1,16 +1,19 @@
 # Google Compute Engine
 
-**Type:** `gcp.gce`
-
-**Description:** Resource attributes for GCE instances.
-
 <!-- semconv gcp.gce -->
 <!-- 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:** `gcp.gce`
+
+**Description:** Resources used by Google Compute Engine (GCE).
+
 | Attribute  | Type | Description  | Examples  | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability |
 |---|---|---|---|---|---|
 | [`gcp.gce.instance.hostname`](/docs/attributes-registry/gcp.md) | string | The hostname of a GCE instance. This is the full value of the default or [custom hostname](https://cloud.google.com/compute/docs/instances/custom-hostname-vm). | `my-host1234.example.com`; `sample-vm.us-west1-b.c.my-project.internal` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) |

docs/resource/cloud-provider/heroku.md

@@ -13,6 +13,13 @@
 <!-- markdownlint-capture -->
 <!-- markdownlint-disable -->
 
+
+**Status:** ![Experimental](https://img.shields.io/badge/-experimental-blue)
+
+**type:** `heroku`
+
+**Description:** Heroku dyno metadata
+
 | Attribute  | Type | Description  | Examples  | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability |
 |---|---|---|---|---|---|
 | [`heroku.app.id`](/docs/attributes-registry/heroku.md) | string | Unique identifier for the application | `2daa2797-e42b-4624-9322-ec3f968df4da` | `Opt-In` | ![Experimental](https://img.shields.io/badge/-experimental-blue) |

docs/resource/cloud.md

@@ -1,18 +1,19 @@
 # Cloud
 
-**Status**: [Experimental][DocumentStatus]
-
-**type:** `cloud`
-
-**Description:** A cloud infrastructure (e.g. GCP, Azure, AWS).
-
 <!-- semconv cloud -->
 <!-- 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:** `cloud`
+
+**Description:** A cloud environment (e.g. GCP, Azure, AWS)
+
 | Attribute  | Type | Description  | Examples  | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability |
 |---|---|---|---|---|---|
 | [`cloud.account.id`](/docs/attributes-registry/cloud.md) | string | The cloud account ID the resource is assigned to. | `111111111111`; `opentelemetry` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
@@ -100,5 +101,3 @@ The following well-known definitions MUST be used if you set this attribute and
 <!-- prettier-ignore-end -->
 <!-- END AUTOGENERATED TEXT -->
 <!-- endsemconv -->
-
-[DocumentStatus]: https://opentelemetry.io/docs/specs/otel/document-status