docs: explain deployment.environment impact on service identity

CHANGELOG.md

@@ -100,6 +100,7 @@ stabilized.
 - Change the precedence between `:authority` and `Host` headers when populating
   `server.address` and `server.port` attributes.
   ([#455](https://github.com/open-telemetry/semantic-conventions/pull/455))
+- Explain `deployment.environment` impact on service identity. ([#481](https://github.com/open-telemetry/semantic-conventions/pull/481))
 
 ## v1.22.0 (2023-10-12)
 

docs/resource/deployment-environment.md

@@ -9,7 +9,15 @@
 <!-- semconv deployment -->
 | Attribute  | Type | Description  | Examples  | Requirement Level |
 |---|---|---|---|---|
-| `deployment.environment` | string | Name of the [deployment environment](https://wikipedia.org/wiki/Deployment_environment) (aka deployment tier). | `staging`; `production` | Recommended |
+| `deployment.environment` | string | Name of the [deployment environment](https://wikipedia.org/wiki/Deployment_environment) (aka deployment tier). [1] | `staging`; `production` | Recommended |
+
+**[1]:** `deployment.environment` does not affect the uniqueness constraints defined through
+the `service.namespace`, `service.name` and `service.instance.id` resource attributes.
+This implies that resources carrying the following attribute combinations MUST be
+considered to be identifying the same service:
+
+* `service.name=frontend`, `deployment.environment=production`
+* `service.name=frontend`, `deployment.environment=staging`.
 <!-- endsemconv -->
 
 [DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.26.0/specification/document-status.md

model/resource/deployment_environment.yaml

@@ -10,4 +10,12 @@ groups:
         brief: >
           Name of the [deployment environment](https://wikipedia.org/wiki/Deployment_environment)
           (aka deployment tier).
+        note: |
+          `deployment.environment` does not affect the uniqueness constraints defined through
+          the `service.namespace`, `service.name` and `service.instance.id` resource attributes.
+          This implies that resources carrying the following attribute combinations MUST be
+          considered to be identifying the same service:
+
+          * `service.name=frontend`, `deployment.environment=production`
+          * `service.name=frontend`, `deployment.environment=staging`.
         examples: ['staging', 'production']