diff --git a/.chloggen/deployment-environment-enum.yaml b/.chloggen/deployment-environment-enum.yaml new file mode 100644 index 0000000000..1003f614bc --- /dev/null +++ b/.chloggen/deployment-environment-enum.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: enhancement + +# The name of the area of concern in the attributes-registry, (e.g. http, cloud, db) +component: deployment + +# A brief description of the change. Surround your text with quotes ("") if it needs to start with a backtick (`). +note: Add enum values for `deployment.environment.name` attribute. + +# 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: [3339] + +# (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: | + The `deployment.environment.name` attribute now has well-known enum values: Production, Staging, Test, and Development. diff --git a/.chloggen/deployment-environment-stable.yaml b/.chloggen/deployment-environment-stable.yaml new file mode 100644 index 0000000000..c522eda2e7 --- /dev/null +++ b/.chloggen/deployment-environment-stable.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: enhancement + +# The name of the area of concern in the attributes-registry, (e.g. http, cloud, db) +component: deployment + +# A brief description of the change. Surround your text with quotes ("") if it needs to start with a backtick (`). +note: Stabilize `deployment.environment.name` attribute and `deployment.environment` entity. + +# 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: [3339] + +# (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: | + The `deployment.environment.name` attribute and `deployment.environment` entity are promoted from development to stable status. diff --git a/docs/registry/attributes/deployment.md b/docs/registry/attributes/deployment.md index 21f6f026d2..c9ce01d239 100644 --- a/docs/registry/attributes/deployment.md +++ b/docs/registry/attributes/deployment.md @@ -14,7 +14,7 @@ This document defines attributes for software deployments. | Key | Stability | Value Type | Description | Example Values | | --- | --- | --- | --- | --- | -| `deployment.environment.name` | ![Development](https://img.shields.io/badge/-development-blue) | string | Name of the [deployment environment](https://wikipedia.org/wiki/Deployment_environment) (aka deployment tier). [1] | `staging`; `production` | +| `deployment.environment.name` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | string | Name of the [deployment environment](https://wikipedia.org/wiki/Deployment_environment) (aka deployment tier). [1] | `staging`; `production` | | `deployment.id` | ![Development](https://img.shields.io/badge/-development-blue) | string | The id of the deployment. | `1208` | | `deployment.name` | ![Development](https://img.shields.io/badge/-development-blue) | string | The name of the deployment. | `deploy my app`; `deploy-frontend` | | `deployment.status` | ![Development](https://img.shields.io/badge/-development-blue) | string | The status of the deployment. | `failed`; `succeeded` | @@ -29,6 +29,17 @@ considered to be identifying the same service: --- +`deployment.environment.name` 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 | +| --- | --- | --- | +| `Development` | Development environment | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| `Production` | Production environment | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| `Staging` | Staging environment | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| `Test` | Testing environment | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | + +--- + `deployment.status` 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 | diff --git a/docs/registry/entities/README.md b/docs/registry/entities/README.md index ab9fd0b7dd..3c98039024 100644 --- a/docs/registry/entities/README.md +++ b/docs/registry/entities/README.md @@ -46,7 +46,7 @@ Currently, the following namespaces exist: | | [container.image](container.md#container-image) | ![Development](https://img.shields.io/badge/-development-blue) | | | [container.runtime](container.md#container-runtime) | ![Development](https://img.shields.io/badge/-development-blue) | | Deployment | | | -| | [deployment](deployment.md#deployment) | ![Development](https://img.shields.io/badge/-development-blue) | +| | [deployment.environment](deployment.md#deployment-environment) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | | Device | | | | | [device](device.md#device) | ![Development](https://img.shields.io/badge/-development-blue) | | Faas | | | diff --git a/docs/registry/entities/deployment.md b/docs/registry/entities/deployment.md index f7882d87c8..1bc3cc3f71 100644 --- a/docs/registry/entities/deployment.md +++ b/docs/registry/entities/deployment.md @@ -3,23 +3,19 @@ # Deployment -## Deployment +## Deployment Environment -**Status:** ![Development](https://img.shields.io/badge/-development-blue) +**Status:** ![Stable](https://img.shields.io/badge/-stable-lightgreen) -**type:** `deployment` +**type:** `deployment.environment` -**Description:** The software deployment. - -> [!warning] -> This entity definition contains attributes without a role. -> Stable Entities MUST NOT have attributes without a defined role. +**Description:** The deployment environment. **Attributes:** | Role | Key | Stability | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Value Type | Description | Example Values | | --- | --- | --- | --- | --- | --- | --- | -| Other | [`deployment.environment.name`](/docs/registry/attributes/deployment.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Recommended` | string | Name of the [deployment environment](https://wikipedia.org/wiki/Deployment_environment) (aka deployment tier). [1] | `staging`; `production` | +| Identity | [`deployment.environment.name`](/docs/registry/attributes/deployment.md) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Required` | string | Name of the [deployment environment](https://wikipedia.org/wiki/Deployment_environment) (aka deployment tier). [1] | `staging`; `production` | **[1] `deployment.environment.name`:** `deployment.environment.name` does not affect the uniqueness constraints defined through the `service.namespace`, `service.name` and `service.instance.id` resource attributes. @@ -28,3 +24,14 @@ considered to be identifying the same service: - `service.name=frontend`, `deployment.environment.name=production` - `service.name=frontend`, `deployment.environment.name=staging`. + +--- + +`deployment.environment.name` 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 | +| --- | --- | --- | +| `Development` | Development environment | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| `Production` | Production environment | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| `Staging` | Staging environment | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| `Test` | Testing environment | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | diff --git a/docs/resource/deployment-environment.md b/docs/resource/deployment-environment.md index e22663217a..5acb1b6e2b 100644 --- a/docs/resource/deployment-environment.md +++ b/docs/resource/deployment-environment.md @@ -1,25 +1,21 @@ # Deployment - + -**Status:** ![Development](https://img.shields.io/badge/-development-blue) +**Status:** ![Stable](https://img.shields.io/badge/-stable-lightgreen) -**type:** `deployment` +**type:** `deployment.environment` -**Description:** The software deployment. - -> [!warning] -> This entity definition contains attributes without a role. -> Stable Entities MUST NOT have attributes without a defined role. +**Description:** The deployment environment. **Attributes:** | Role | Key | Stability | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Value Type | Description | Example Values | | --- | --- | --- | --- | --- | --- | --- | -| Other | [`deployment.environment.name`](/docs/registry/attributes/deployment.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Recommended` | string | Name of the [deployment environment](https://wikipedia.org/wiki/Deployment_environment) (aka deployment tier). [1] | `staging`; `production` | +| Identity | [`deployment.environment.name`](/docs/registry/attributes/deployment.md) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Required` | string | Name of the [deployment environment](https://wikipedia.org/wiki/Deployment_environment) (aka deployment tier). [1] | `staging`; `production` | **[1] `deployment.environment.name`:** `deployment.environment.name` does not affect the uniqueness constraints defined through the `service.namespace`, `service.name` and `service.instance.id` resource attributes. @@ -28,6 +24,17 @@ considered to be identifying the same service: - `service.name=frontend`, `deployment.environment.name=production` - `service.name=frontend`, `deployment.environment.name=staging`. + +--- + +`deployment.environment.name` 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 | +| --- | --- | --- | +| `Development` | Development environment | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| `Production` | Production environment | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| `Staging` | Staging environment | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| `Test` | Testing environment | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | diff --git a/model/deployment/entities.yaml b/model/deployment/entities.yaml index caa820451d..3db40bc63b 100644 --- a/model/deployment/entities.yaml +++ b/model/deployment/entities.yaml @@ -1,10 +1,11 @@ groups: - - id: entity.deployment + - id: entity.deployment.environment type: entity - stability: development - name: deployment + stability: stable + name: deployment.environment brief: > - The software deployment. + The deployment environment. attributes: - ref: deployment.environment.name - requirement_level: recommended + role: identifying + requirement_level: required diff --git a/model/deployment/registry.yaml b/model/deployment/registry.yaml index b27e89ff27..d28f078906 100644 --- a/model/deployment/registry.yaml +++ b/model/deployment/registry.yaml @@ -32,8 +32,25 @@ groups: The status of the deployment. stability: development - id: deployment.environment.name - type: string - stability: development + type: + members: + - id: production + value: "Production" + brief: Production environment + stability: stable + - id: staging + value: "Staging" + brief: Staging environment + stability: stable + - id: test + value: "Test" + brief: Testing environment + stability: stable + - id: development + value: "Development" + brief: Development environment + stability: stable + stability: stable brief: > Name of the [deployment environment](https://wikipedia.org/wiki/Deployment_environment) (aka deployment tier).