feat: add attributes for cloud-native deployment

CHANGELOG.md

@@ -364,6 +364,8 @@ release.
 
 ### Semantic Conventions
 
+- Add semantic conventions for Deployments
+  ([#3169](https://github.com/open-telemetry/opentelemetry-specification/pull/3169))
 - Clarify common HTTP attributes apply to both clients and servers
   ([#3044](https://github.com/open-telemetry/opentelemetry-specification/pull/3044))
 - Add `code.lineno` source code attribute

semantic_conventions/logs/log-deployment.yaml

@@ -0,0 +1,36 @@
+groups:
+  - id: log-deployment-application
+    type: event
+    prefix: deployment.application
+    brief: >
+      This document defines attributes for Cloud Native deployments
+      represented using Log Records.
+    attributes:
+      - ref: deployment.application.name
+      - ref: deployment.application.version
+      - ref: deployment.application.status
+
+  - id: log-deployment-workload
+    type: event
+    prefix: deployment.workload
+    brief: >
+      This document defines attributes for Cloud Native workload
+      represented using Log Records.
+    attributes:
+      - ref: deployment.application.name
+      - ref: deployment.workload.name
+      - ref: deployment.workload.version
+      - ref: deployment.workload.status
+
+  - id: log-deployment-task
+    type: event
+    prefix: deployment.task
+    brief: >
+      This document defines attributes for accompanying tasks that support Cloud Native deployments
+      represented using Log Records.
+    attributes:
+      - ref: deployment.application.name
+      - ref: deployment.workload.name
+        requirement_level: recommended
+      - ref: deployment.task.name
+      - ref: deployment.task.status

semantic_conventions/trace/deployment.yaml

@@ -0,0 +1,125 @@
+groups:
+  - id: deployment.application
+    prefix: deployment.application
+    type: event
+    brief: >
+        This document defines attributes for Cloud Native deployments of applications.
+        These attributes can be attached to spans when performing operations for deploying applications on Kubernetes,
+        regardless of the deployment tool being used.
+    attributes:
+      - id: name
+        type: string
+        requirement_level: required
+        brief: >
+          The name of the application under deployment.
+        examples: [ 'podtato-head' ]
+      - id: version
+        type: string
+        brief: >
+          The version of the application under deployment.
+        examples: [ '0.1.0' ]
+      - id: status
+        type:
+          allow_custom_values: true
+          members:
+            - id: 'pending'
+              value: 'Pending'
+              brief: 'The deployment has been accepted and is being set up'
+            - id: 'progressing'
+              value: 'Progressing'
+              brief: 'The deployment is currently taking place'
+            - id: 'succeeded'
+              value: 'Succeeded'
+              brief: 'The deployment was completed correctly'
+            - id: 'failed'
+              value: 'Failed'
+              brief: 'The deployment was **not** completed correctly'
+            - id: 'unknown'
+              value: 'Unknown'
+              brief: 'The deployment was unsuccessful and the reason is unknown'
+        brief: >
+          The status of the application deployment.
+
+  - id: deployment.workload
+    prefix: deployment.workload
+    type: event
+    brief: >
+      This document defines attributes for the deployment of Cloud Native workloads.
+      These attributes can be attached to spans when performing operations for deploying workloads on Kubernetes,
+      regardless of the deployment tool being used.
+    attributes:
+      - ref: deployment.application.name
+      - id: name
+        type: string
+        requirement_level: required
+        brief: >
+          The name of the single workload under deployment.
+        examples: [ 'podtato-head-hat', 'podtato-head-left-leg' ]
+      - id: namespace
+        type: string
+        brief: >
+          The namespace in which the workload will be deployed.
+        examples: [ 'podtatohead' ]
+      - id: version
+        type: string
+        brief: >
+          The version of the workload under deployment.
+        examples: [ 'v0.1.0' ]
+      - id: status
+        type:
+          allow_custom_values: true
+          members:
+            - id: 'pending'
+              value: 'Pending'
+              brief: 'The deployment has been accepted and is being set up'
+            - id: 'progressing'
+              value: 'Progressing'
+              brief: 'The deployment is currently taking place'
+            - id: 'succeeded'
+              value: 'Succeeded'
+              brief: 'The deployment was completed correctly'
+            - id: 'failed'
+              value: 'Failed'
+              brief: 'The deployment was **not** completed correctly'
+            - id: 'unknown'
+              value: 'Unknown'
+              brief: 'The deployment was unsuccessful and the reason is unknown'
+        brief: >
+          The status of the workload deployment.
+
+  - id: deployment.task
+    prefix: deployment.task
+    type: event
+    brief: >
+      This document defines attributes for accompanying tasks that support Cloud Native deployments.
+    attributes:
+      - ref: deployment.application.name
+      - ref: deployment.workload.name
+        requirement_level: recommended
+      - id: name
+        type: string
+        requirement_level: required
+        brief: >
+          The name that identifies the executed task.
+        examples: [ 'database-migration', 'report-metric', 'provision-infrastructure' ]
+      - id: status
+        type:
+          allow_custom_values: true
+          members:
+            - id: 'pending'
+              value: 'Pending'
+              brief: 'The deployment has been accepted and is being set up'
+            - id: 'progressing'
+              value: 'Progressing'
+              brief: 'The deployment is currently taking place'
+            - id: 'succeeded'
+              value: 'Succeeded'
+              brief: 'The deployment was completed correctly'
+            - id: 'failed'
+              value: 'Failed'
+              brief: 'The deployment was **not** completed correctly'
+            - id: 'unknown'
+              value: 'Unknown'
+              brief: 'The deployment was unsuccessful and the reason is unknown'
+        brief: >
+          The status of the task execution.

specification/logs/semantic_conventions/deployment.md

@@ -0,0 +1,81 @@
+# Semantic Conventions for Application Deployment
+
+**Status**: [Experimental](../../document-status.md)
+
+This document defines semantic conventions for recording an application delivery as
+a [log record](../bridge-api.md#logrecord) emitted through the [Logger API](../bridge-api.md#emit-logrecord).
+
+<!-- Re-generate TOC with `markdown-toc --no-first-h1 -i` -->
+
+<!-- toc -->
+
+- [Recording an Application Delivery](#recording-an-application-delivery)
+  * [Attributes](#attributes)
+- [Recording a Workload Delivery](#recording-a-workload-delivery)
+  * [Attributes](#attributes-1)
+- [Recording a Task execution](#recording-a-task-execution)
+  * [Attributes](#attributes-2)
+
+<!-- tocstop -->
+
+## Recording an Application Delivery
+
+Application deployments SHOULD be recorded as attributes on the
+[LogRecord](../bridge-api.md#logrecord) passed to the [Logger](../bridge-api.md#logger) emit
+operations. Application deployments MAY be recorded on "logs" or "events" depending on the
+context.
+
+### Attributes
+
+The table below indicates which attributes should be added to the
+[LogRecord](../bridge-api.md#logrecord) and their types.
+
+<!-- semconv log-deployment-application -->
+The event name MUST be `deployment.application`.
+
+| Attribute  | Type | Description  | Examples  | Requirement Level |
+|---|---|---|---|---|
+| [`deployment.application.name`](../../trace/semantic_conventions/deployment.md) | string | The name of the application under deployment. | `podtato-head` | Required |
+| [`deployment.application.status`](../../trace/semantic_conventions/deployment.md) | string | The status of the application deployment. | `Pending` | Recommended |
+| [`deployment.application.version`](../../trace/semantic_conventions/deployment.md) | string | The version of the application under deployment. | `0.1.0` | Recommended |
+<!-- endsemconv -->
+
+## Recording a Workload Delivery
+
+Workload deployments SHOULD be recorded as attributes on the
+[LogRecord](../bridge-api.md#logrecord) passed to the [Logger](../bridge-api.md#logger) emit
+operations. Workload deployments MAY be recorded on "logs" or "events" depending on the
+context.
+
+### Attributes
+
+<!-- semconv log-deployment-workload -->
+The event name MUST be `deployment.workload`.
+
+| Attribute  | Type | Description  | Examples  | Requirement Level |
+|---|---|---|---|---|
+| [`deployment.application.name`](../../trace/semantic_conventions/deployment.md) | string | The name of the application under deployment. | `podtato-head` | Required |
+| [`deployment.workload.name`](../../trace/semantic_conventions/deployment.md) | string | The name of the single workload under deployment. | `podtato-head-hat`; `podtato-head-left-leg` | Required |
+| [`deployment.workload.status`](../../trace/semantic_conventions/deployment.md) | string | The status of the workload deployment. | `Pending` | Recommended |
+| [`deployment.workload.version`](../../trace/semantic_conventions/deployment.md) | string | The version of the workload under deployment. | `v0.1.0` | Recommended |
+<!-- endsemconv -->
+
+## Recording a Task execution
+
+Task executions that support deployments SHOULD be recorded as attributes on the
+[LogRecord](../bridge-api.md#logrecord) passed to the [Logger](../bridge-api.md#logger) emit
+operations. Task executions MAY be recorded on "logs" or "events" depending on the
+context.
+
+### Attributes
+
+<!-- semconv log-deployment-task -->
+The event name MUST be `deployment.task`.
+
+| Attribute  | Type | Description  | Examples  | Requirement Level |
+|---|---|---|---|---|
+| [`deployment.application.name`](../../trace/semantic_conventions/deployment.md) | string | The name of the application under deployment. | `podtato-head` | Required |
+| [`deployment.task.name`](../../trace/semantic_conventions/deployment.md) | string | The name that identifies the executed task. | `database-migration`; `report-metric`; `provision-infrastructure` | Required |
+| [`deployment.task.status`](../../trace/semantic_conventions/deployment.md) | string | The status of the task execution. | `Pending` | Recommended |
+| [`deployment.workload.name`](../../trace/semantic_conventions/deployment.md) | string | The name of the single workload under deployment. | `podtato-head-hat`; `podtato-head-left-leg` | Recommended |
+<!-- endsemconv -->

specification/trace/semantic_conventions/deployment.md

@@ -0,0 +1,109 @@
+# Semantic conventions for Application Deployment
+
+**Status**: [Experimental](../../document-status.md)
+
+This document defines semantic conventions for recording application delivery as span events.
+To record an evaluation outside a transaction context, consider
+[recording it as a log record](../../logs/semantic_conventions/deployment.md).
+
+<!-- Re-generate TOC with `markdown-toc --no-first-h1 -i` -->
+
+<!-- toc -->
+
+- [Overview](#overview)
+- [Definitions](#definitions)
+  * [Application](#application)
+  * [Workload](#workload)
+  * [Task](#task)
+
+<!-- tocstop -->
+
+## Overview
+
+Deployments of cloud-native applications are automated and done at a fast phase.
+In most cases, deployments are complex, require multiple steps, could spawn across multiple environments,
+and are delivered mostly via either Operators or GitOps practices and tools.
+Hence, the delivery process is modeled as an event stream of OpenTelemetry [`Event`s](../api.md#add-events).
+This document defines semantic conventions to collect telemetry signals about events that occur during the
+deployment of an application.
+
+## Definitions
+
+### Application
+
+Each stage of the lifecycle of a cloud-native application deployment SHOULD be recorded as an Event on the span during
+which it occurred.
+
+<!-- semconv deployment.application -->
+The event name MUST be `deployment.application`.
+
+| Attribute  | Type | Description  | Examples  | Requirement Level |
+|---|---|---|---|---|
+| `deployment.application.name` | string | The name of the application under deployment. | `podtato-head` | Required |
+| `deployment.application.version` | string | The version of the application under deployment. | `0.1.0` | Recommended |
+| `deployment.application.status` | string | The status of the application deployment. | `Pending` | Recommended |
+
+`deployment.application.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 |
+|---|---|
+| `Pending` | The deployment has been accepted and is being set up |
+| `Progressing` | The deployment is currently taking place |
+| `Succeeded` | The deployment was completed correctly |
+| `Failed` | The deployment was **not** completed correctly |
+| `Unknown` | The deployment was unsuccessful and the reason is unknown |
+<!-- endsemconv -->
+
+### Workload
+
+Cloud-native applications are composed of one or several components that are usually called [workloads](https://kubernetes.io/docs/concepts/workloads/).
+Similarly to applications, each stage of the lifecycle of a workload deployment SHOULD be recorded as an Event on the span during
+which it occurred.
+
+<!-- semconv deployment.workload -->
+The event name MUST be `deployment.workload`.
+
+| Attribute  | Type | Description  | Examples  | Requirement Level |
+|---|---|---|---|---|
+| `deployment.workload.name` | string | The name of the single workload under deployment. | `podtato-head-hat`; `podtato-head-left-leg` | Required |
+| `deployment.workload.namespace` | string | The namespace in which the workload will be deployed. | `podtatohead` | Recommended |
+| `deployment.workload.version` | string | The version of the workload under deployment. | `v0.1.0` | Recommended |
+| `deployment.workload.status` | string | The status of the workload deployment. | `Pending` | Recommended |
+| `deployment.application.name` | string | The name of the application under deployment. | `podtato-head` | Required |
+
+`deployment.workload.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 |
+|---|---|
+| `Pending` | The deployment has been accepted and is being set up |
+| `Progressing` | The deployment is currently taking place |
+| `Succeeded` | The deployment was completed correctly |
+| `Failed` | The deployment was **not** completed correctly |
+| `Unknown` | The deployment was unsuccessful and the reason is unknown |
+<!-- endsemconv -->
+
+### Task
+
+The deployment of the new version of an application usually requires several external tasks.
+Their execution SHOULD be recorded as an Event on the span during which it occurred.
+
+<!-- semconv deployment.task -->
+The event name MUST be `deployment.task`.
+
+| Attribute  | Type | Description  | Examples  | Requirement Level |
+|---|---|---|---|---|
+| `deployment.task.name` | string | The name that identifies the executed task. | `database-migration`; `report-metric`; `provision-infrastructure` | Required |
+| `deployment.task.status` | string | The status of the task execution. | `Pending` | Recommended |
+| `deployment.application.name` | string | The name of the application under deployment. | `podtato-head` | Required |
+| `deployment.workload.name` | string | The name of the single workload under deployment. | `podtato-head-hat`; `podtato-head-left-leg` | Recommended |
+
+`deployment.task.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 |
+|---|---|
+| `Pending` | The deployment has been accepted and is being set up |
+| `Progressing` | The deployment is currently taking place |
+| `Succeeded` | The deployment was completed correctly |
+| `Failed` | The deployment was **not** completed correctly |
+| `Unknown` | The deployment was unsuccessful and the reason is unknown |
+<!-- endsemconv -->