diff --git a/CHANGELOG.md b/CHANGELOG.md index 52188613a7c..2ca4be54da9 100644 --- a/CHANGELOG.md +++ b/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 diff --git a/semantic_conventions/logs/log-deployment.yaml b/semantic_conventions/logs/log-deployment.yaml new file mode 100644 index 00000000000..30576c9a3e5 --- /dev/null +++ b/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 diff --git a/semantic_conventions/trace/deployment.yaml b/semantic_conventions/trace/deployment.yaml new file mode 100644 index 00000000000..3807a1b83c3 --- /dev/null +++ b/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. diff --git a/specification/logs/semantic_conventions/deployment.md b/specification/logs/semantic_conventions/deployment.md new file mode 100644 index 00000000000..df157604f35 --- /dev/null +++ b/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). + + + + + +- [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) + + + +## 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. + + +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 | + + +## 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 + + +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 | + + +## 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 + + +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 | + diff --git a/specification/trace/semantic_conventions/deployment.md b/specification/trace/semantic_conventions/deployment.md new file mode 100644 index 00000000000..b4744521c1c --- /dev/null +++ b/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). + + + + + +- [Overview](#overview) +- [Definitions](#definitions) + * [Application](#application) + * [Workload](#workload) + * [Task](#task) + + + +## 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. + + +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 | + + +### 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. + + +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 | + + +### 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. + + +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 | +