feat: add attributes for cloud-native deployment #24
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -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 |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,123 @@ | ||
| 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. | ||
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -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](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/logs/bridge-api.md#logrecord) emitted through the [Logger API](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/logs/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](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/logs/bridge-api.md#logrecord) passed to the [Logger](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/logs/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](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/logs/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](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/logs/bridge-api.md#logrecord) passed to the [Logger](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/logs/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](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/logs/bridge-api.md#logrecord) passed to the [Logger](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/logs/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 --> |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -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](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/trace/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 | ||
|
There was a problem hiding this comment. Should these events have any relation with the Continuous Deployment Events of CDEvents? |
||
| 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 | | ||
|
There was a problem hiding this comment. Sounds like this is essentially the same as There was a problem hiding this comment. Thanks @felixbarny for pointing that out. You are right, this has the same semantics as |
||
| | `deployment.workload.namespace` | string | The namespace in which the workload will be deployed. | `podtatohead` | Recommended | | ||
|
There was a problem hiding this comment.
Also There was a problem hiding this comment. Thank @jsuereth for looking into this. I agree, these 3 attributes can be replaced with
Deployment is an overloaded term, especially in K8s. Maybe |
||
| | `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 | | ||
|
There was a problem hiding this comment. I don't understand the difference between workload + application here. Can you outline that somewhere? There was a problem hiding this comment. Sure, maybe this should be in the "Overview" section. |
||
| | `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 --> | ||
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Why mention Kubernetes here?
Opentelemetry is open source and vendor neutral and as such not restricted to deployments on just K8s.
Maybe it should be phrased that "deploying applications on Kubernetes" is an example.
The same question applies for the brief of
deployment.workloadbelow.