From 07572975a8a723f9b487076c3b929e3a1239a4ef Mon Sep 17 00:00:00 2001 From: Giovanni Liva Date: Mon, 9 Jan 2023 14:43:50 +0100 Subject: [PATCH 1/4] feat: add attributes for cloud-native deployment Signed-off-by: Giovanni Liva --- semantic_conventions/logs/log-deployment.yaml | 37 ++++++ semantic_conventions/trace/deployment.yaml | 125 ++++++++++++++++++ .../logs/semantic_conventions/deployment.md | 82 ++++++++++++ .../trace/semantic_conventions/deployment.md | 109 +++++++++++++++ 4 files changed, 353 insertions(+) create mode 100644 semantic_conventions/logs/log-deployment.yaml create mode 100644 semantic_conventions/trace/deployment.yaml create mode 100644 specification/logs/semantic_conventions/deployment.md create mode 100644 specification/trace/semantic_conventions/deployment.md diff --git a/semantic_conventions/logs/log-deployment.yaml b/semantic_conventions/logs/log-deployment.yaml new file mode 100644 index 00000000000..5d64d651a4f --- /dev/null +++ b/semantic_conventions/logs/log-deployment.yaml @@ -0,0 +1,37 @@ +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..2fca46c2bd6 --- /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 wass 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..0578d0d8ce2 --- /dev/null +++ b/specification/logs/semantic_conventions/deployment.md @@ -0,0 +1,82 @@ +# Semantic Conventions for Application Deployment + +**Status**: [Experimental](../../document-status.md) + +This document defines semantic conventions for recording an application delivery as +a [log record](../api.md#logrecord) emitted through the [Logger API](../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](../api.md#logrecord) passed to the [Logger](../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](../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](../api.md#logrecord) passed to the [Logger](../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](../api.md#logrecord) passed to the [Logger](../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..8b889808ecc --- /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 wass 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 | + From 00e40c741b7b87fc0749d3f491ce44acb23bc5f9 Mon Sep 17 00:00:00 2001 From: Giovanni Liva Date: Thu, 2 Feb 2023 08:29:33 +0100 Subject: [PATCH 2/4] update changelog Signed-off-by: Giovanni Liva --- CHANGELOG.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/CHANGELOG.md b/CHANGELOG.md index 488693e42f9..336d7a6dfb2 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -170,6 +170,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 From 349be5a09816e8e44ea1ca2a42ba7a9d46ea1fdb Mon Sep 17 00:00:00 2001 From: Giovanni Liva Date: Thu, 2 Feb 2023 08:43:18 +0100 Subject: [PATCH 3/4] linting Signed-off-by: Giovanni Liva --- semantic_conventions/logs/log-deployment.yaml | 1 - semantic_conventions/trace/deployment.yaml | 2 +- specification/logs/semantic_conventions/deployment.md | 1 - specification/trace/semantic_conventions/deployment.md | 6 +++--- 4 files changed, 4 insertions(+), 6 deletions(-) diff --git a/semantic_conventions/logs/log-deployment.yaml b/semantic_conventions/logs/log-deployment.yaml index 5d64d651a4f..30576c9a3e5 100644 --- a/semantic_conventions/logs/log-deployment.yaml +++ b/semantic_conventions/logs/log-deployment.yaml @@ -34,4 +34,3 @@ groups: 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 index 2fca46c2bd6..3807a1b83c3 100644 --- a/semantic_conventions/trace/deployment.yaml +++ b/semantic_conventions/trace/deployment.yaml @@ -83,7 +83,7 @@ groups: brief: 'The deployment was **not** completed correctly' - id: 'unknown' value: 'Unknown' - brief: 'The deployment wass unsuccessful and the reason is unknown' + brief: 'The deployment was unsuccessful and the reason is unknown' brief: > The status of the workload deployment. diff --git a/specification/logs/semantic_conventions/deployment.md b/specification/logs/semantic_conventions/deployment.md index 0578d0d8ce2..b7f6f3d9243 100644 --- a/specification/logs/semantic_conventions/deployment.md +++ b/specification/logs/semantic_conventions/deployment.md @@ -67,7 +67,6 @@ Task executions that support deployments SHOULD be recorded as attributes on the operations. Task executions MAY be recorded on "logs" or "events" depending on the context. - ### Attributes diff --git a/specification/trace/semantic_conventions/deployment.md b/specification/trace/semantic_conventions/deployment.md index 8b889808ecc..b4744521c1c 100644 --- a/specification/trace/semantic_conventions/deployment.md +++ b/specification/trace/semantic_conventions/deployment.md @@ -31,7 +31,7 @@ deployment of an application. ### Application -Each stage of the lifecycle of a cloud-native application deployment SHOULD be recorded as an Event on the span during +Each stage of the lifecycle of a cloud-native application deployment SHOULD be recorded as an Event on the span during which it occurred. @@ -54,7 +54,7 @@ The event name MUST be `deployment.application`. | `Unknown` | The deployment was unsuccessful and the reason is unknown | -### Workload +### 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 @@ -79,7 +79,7 @@ The event name MUST be `deployment.workload`. | `Progressing` | The deployment is currently taking place | | `Succeeded` | The deployment was completed correctly | | `Failed` | The deployment was **not** completed correctly | -| `Unknown` | The deployment wass unsuccessful and the reason is unknown | +| `Unknown` | The deployment was unsuccessful and the reason is unknown | ### Task From 0e0312d08c0901f5e14d6ca01b97812781cb62d9 Mon Sep 17 00:00:00 2001 From: Giovanni Liva Date: Mon, 27 Feb 2023 16:12:48 +0100 Subject: [PATCH 4/4] adapt links Signed-off-by: Giovanni Liva --- specification/logs/semantic_conventions/deployment.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/specification/logs/semantic_conventions/deployment.md b/specification/logs/semantic_conventions/deployment.md index b7f6f3d9243..df157604f35 100644 --- a/specification/logs/semantic_conventions/deployment.md +++ b/specification/logs/semantic_conventions/deployment.md @@ -3,7 +3,7 @@ **Status**: [Experimental](../../document-status.md) This document defines semantic conventions for recording an application delivery as -a [log record](../api.md#logrecord) emitted through the [Logger API](../api.md#emit-logrecord). +a [log record](../bridge-api.md#logrecord) emitted through the [Logger API](../bridge-api.md#emit-logrecord). @@ -21,14 +21,14 @@ a [log record](../api.md#logrecord) emitted through the [Logger API](../api.md#e ## Recording an Application Delivery Application deployments SHOULD be recorded as attributes on the -[LogRecord](../api.md#logrecord) passed to the [Logger](../api.md#logger) emit +[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](../api.md#logrecord) and their types. +[LogRecord](../bridge-api.md#logrecord) and their types. The event name MUST be `deployment.application`. @@ -43,7 +43,7 @@ The event name MUST be `deployment.application`. ## Recording a Workload Delivery Workload deployments SHOULD be recorded as attributes on the -[LogRecord](../api.md#logrecord) passed to the [Logger](../api.md#logger) emit +[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. @@ -63,7 +63,7 @@ The event name MUST be `deployment.workload`. ## Recording a Task execution Task executions that support deployments SHOULD be recorded as attributes on the -[LogRecord](../api.md#logrecord) passed to the [Logger](../api.md#logger) emit +[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.