From 7c76c20e4f2fe502bc1b802e97bf8b53415168f1 Mon Sep 17 00:00:00 2001 From: Liudmila Molkova Date: Tue, 26 Nov 2024 09:04:32 -0800 Subject: [PATCH 1/4] Add Daniel Dyla to SemConv approvers (#1615) Co-authored-by: Armin Ruech <7052238+arminru@users.noreply.github.com> --- README.md | 1 + 1 file changed, 1 insertion(+) diff --git a/README.md b/README.md index 6227be7ca2..e81f0e5698 100644 --- a/README.md +++ b/README.md @@ -20,6 +20,7 @@ Approvers ([@open-telemetry/specs-semconv-approvers](https://github.com/orgs/ope - [Alexandra Konrad](https://github.com/trisch-me), Elastic - [Christian Neumüller](https://github.com/Oberon00), Dynatrace +- [Daniel Dyla](https://github.com/dyladan), Dynatrace - [James Moessis](https://github.com/jamesmoessis), Atlassian - [Sean Marciniak](https://github.com/MovieStoreGuy), Atlassian - [Ted Young](https://github.com/tedsuo), Lightstep From aca6d57d6a72b9e5ba7c19ab941c8a07d0e343b1 Mon Sep 17 00:00:00 2001 From: Jamie Danielson Date: Tue, 26 Nov 2024 12:31:50 -0500 Subject: [PATCH 2/4] Fix typo in schemas for messaging attribute changes (#1595) --- .chloggen/fix-typo-messaging-schema.yaml | 4 ++++ schema-next.yaml | 4 ++-- 2 files changed, 6 insertions(+), 2 deletions(-) create mode 100644 .chloggen/fix-typo-messaging-schema.yaml diff --git a/.chloggen/fix-typo-messaging-schema.yaml b/.chloggen/fix-typo-messaging-schema.yaml new file mode 100644 index 0000000000..c487a03f06 --- /dev/null +++ b/.chloggen/fix-typo-messaging-schema.yaml @@ -0,0 +1,4 @@ +change_type: 'bug_fix' +component: messaging +note: Fix typo in schemas for messaging attribute changes +issues: [1595] diff --git a/schema-next.yaml b/schema-next.yaml index 50afab2b96..de73f27640 100644 --- a/schema-next.yaml +++ b/schema-next.yaml @@ -59,8 +59,8 @@ versions: attribute_map: messaging.kafka.consumer.group: messaging.consumer.group.name messaging.rocketmq.client_group: messaging.consumer.group.name - messaging.evenhubs.consumer.group: messaging.consumer.group.name - message.servicebus.destination.subscription_name: messaging.destination.subscription.name + messaging.eventhubs.consumer.group: messaging.consumer.group.name + messaging.servicebus.destination.subscription_name: messaging.destination.subscription.name # https://github.com/open-telemetry/semantic-conventions/pull/1200 - rename_attributes: attribute_map: From f49b5cd076ffa761759c0ea02c2a6fc81ccf0a4a Mon Sep 17 00:00:00 2001 From: Liudmila Molkova Date: Tue, 26 Nov 2024 12:50:34 -0800 Subject: [PATCH 3/4] Add section on span status for databases (#1560) Co-authored-by: Trask Stalnaker --- .chloggen/1560.yaml | 4 +++ docs/database/database-spans.md | 60 +++++++++++++++++++++++++++++++++ 2 files changed, 64 insertions(+) create mode 100644 .chloggen/1560.yaml diff --git a/.chloggen/1560.yaml b/.chloggen/1560.yaml new file mode 100644 index 0000000000..35769898b7 --- /dev/null +++ b/.chloggen/1560.yaml @@ -0,0 +1,4 @@ +change_type: enhancement +component: db +note: Specify how to set span status for database operations. +issues: [1536, 1560] diff --git a/docs/database/database-spans.md b/docs/database/database-spans.md index 597a9de6cf..bf5dc93347 100644 --- a/docs/database/database-spans.md +++ b/docs/database/database-spans.md @@ -11,6 +11,8 @@ linkTitle: Client Calls - [Name](#name) +- [Status](#status) + - [Recording exception events](#recording-exception-events) - [Common attributes](#common-attributes) - [Notes and well-known identifiers for `db.system`](#notes-and-well-known-identifiers-for-dbsystem) - [Sanitization of `db.query.text`](#sanitization-of-dbquerytext) @@ -85,6 +87,62 @@ and SHOULD adhere to one of the following values, provided they are accessible: If a corresponding `{target}` value is not available for a specific operation, the instrumentation SHOULD omit the `{target}`. For example, for an operation describing SQL query on an anonymous table like `SELECT * FROM (SELECT * FROM table) t`, span name should be `SELECT`. +## Status + +[Span Status Code][SpanStatus] MUST be left unset if the operation has ended without any errors. + +Instrumentation SHOULD consider the operation as failed if any of the following is true: + +- the `db.response.status_code` value indicates an error + + > [!NOTE] + > + > The classification of status code as an error depends on the context. + > For example, a SQL STATE `02000` (`no_data`) indicates an error when the application + > expected the data to be available. However, it is not an error when the + > application is simply checking whether the data exists. + > + > Instrumentations that have additional context about a specific operation MAY use + > this context to set the span status more precisely. + > Instrumentations that don't have any additional context MUST follow the + > guidelines in this section. + +- an exception is thrown by the instrumented method call +- the instrumented method returns an error in another way + +When the operation ends with an error, instrumentation: + +- SHOULD set the span status code to `Error` +- SHOULD set the `error.type` attribute +- SHOULD set the span status description when it has additional information + about the error which is not expected to contain sensitive details and aligns + with [Span Status Description][SpanStatus] definition. + + It's NOT RECOMMENDED to duplicate `db.response.status_code` or `error.type` + in span status description. + + When the operation fails with an exception, the span status description SHOULD be set to + the exception message. + +### Recording exception events + +**Status**: [Experimental][DocumentStatus] + +When the operation fails with an exception, instrumentation SHOULD record +an [exception event](../exceptions/exceptions-spans.md) by default if, and only if, +the span being recorded is a local root span (does not have a local parent). + +> [!NOTE] +> +> Exception stack traces could be very long and are expensive to capture and store. +> Exceptions which are not handled by instrumented libraries are likely to be handled +> and logged by the caller. +> Exceptions that are not handled will be recorded by the outermost (local root) +> instrumentation such as HTTP or gRPC server. + +Instrumentation MAY provide a configuration option to record exceptions that +escape the surface of the instrumented API. + ## Common attributes These attributes will usually be the same for all operations performed over the same database connection. @@ -309,6 +367,7 @@ The `db.query.summary` attribute captures a shortened representation of a query which SHOULD have low-cardinality and SHOULD NOT contain any dynamic or sensitive data. > [!NOTE] +> > The `db.query.text` attribute is intended to identify individual queries. Even though > it is sanitized if captured by default, it could still have high cardinality and > might reach hundreds of lines. @@ -418,3 +477,4 @@ More specific Semantic Conventions are defined for the following database techno * [SQL](sql.md): Semantic Conventions for *SQL* databases. [DocumentStatus]: https://opentelemetry.io/docs/specs/otel/document-status +[SpanStatus]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.37.0/specification/trace/api.md#set-status From 3357f693776002e1df800b738f91075da2d4a98b Mon Sep 17 00:00:00 2001 From: Riccardo Magliocchetti Date: Tue, 26 Nov 2024 22:09:20 +0100 Subject: [PATCH 4/4] Add conventions for CLI Spans (#1588) Co-authored-by: Liudmila Molkova --- .chloggen/add-cli-spans.yaml | 22 +++++++ docs/cli/cli-spans.md | 122 +++++++++++++++++++++++++++++++++++ model/cli/spans.yaml | 42 ++++++++++++ 3 files changed, 186 insertions(+) create mode 100644 .chloggen/add-cli-spans.yaml create mode 100644 docs/cli/cli-spans.md create mode 100644 model/cli/spans.yaml diff --git a/.chloggen/add-cli-spans.yaml b/.chloggen/add-cli-spans.yaml new file mode 100644 index 0000000000..428bb1d701 --- /dev/null +++ b/.chloggen/add-cli-spans.yaml @@ -0,0 +1,22 @@ +# Use this changelog template to create an entry for release notes. +# +# If your change doesn't affect end users you should instead start +# your pull request title with [chore] or use the "Skip Changelog" label. + +# One of 'breaking', 'deprecation', 'new_component', 'enhancement', 'bug_fix' +change_type: 'new_component' + +# The name of the area of concern in the attributes-registry, (e.g. http, cloud, db) +component: 'cli' + +# A brief description of the change. Surround your text with quotes ("") if it needs to start with a backtick (`). +note: Define span describing CLI application execution + +# Mandatory: One or more tracking issues related to the change. You can use the PR number here if no issue exists. +# The values here must be integers. +issues: [1577] + +# (Optional) One or more lines of additional information to render under the primary note. +# These lines will be padded with 2 spaces and then inserted directly into the document. +# Use pipe (|) for multiline entries. +subtext: diff --git a/docs/cli/cli-spans.md b/docs/cli/cli-spans.md new file mode 100644 index 0000000000..be7e2a61b8 --- /dev/null +++ b/docs/cli/cli-spans.md @@ -0,0 +1,122 @@ + + +# Semantic Conventions for CLI (Command Line Interface) programs + +**Status**: [Experimental][DocumentStatus] + +This document defines semantic conventions to apply when instrumenting CLI programs, both as a caller and as callee. This document is intended for short-lived programs that end their execution, i.e. not daemon or long running background tasks. + +Span kind SHOULD be `INTERNAL` when the traced program is the callee or `CLIENT` when the caller is tracing another program. + +The span name SHOULD be set to `{process.executable.name}`. +Instrumentations that have additional context about executed commands MAY use a different low-cardinality span name format and SHOULD document it. + +Span status SHOULD be set to `Error` if `{process.exit.code}` is not 0. + + + +## Execution (callee) spans + + + + + + + + +| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | +|---|---|---|---|---|---| +| [`process.executable.name`](/docs/attributes-registry/process.md) | string | The name of the process executable. On Linux based systems, can be set to the `Name` in `proc/[pid]/status`. On Windows, can be set to the base name of `GetProcessImageFileNameW`. | `otelcol` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`process.exit.code`](/docs/attributes-registry/process.md) | int | The exit code of the process. | `127` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`process.pid`](/docs/attributes-registry/process.md) | int | Process identifier (PID). | `1234` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`error.type`](/docs/attributes-registry/error.md) | string | Describes a class of error the operation ended with. [1] | `timeout`; `java.net.UnknownHostException`; `server_certificate_invalid`; `500` | `Conditionally Required` if and only if process.exit.code is not 0 | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| [`process.command_args`](/docs/attributes-registry/process.md) | string[] | All the command arguments (including the command/executable itself) as received by the process. On Linux-based systems (and some other Unixoid systems supporting procfs), can be set according to the list of null-delimited strings extracted from `proc/[pid]/cmdline`. For libc-based executables, this would be the full argv vector passed to `main`. | `["cmd/otecol", "--config=config.yaml"]` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`process.executable.path`](/docs/attributes-registry/process.md) | string | The full path to the process executable. On Linux based systems, can be set to the target of `proc/[pid]/exe`. On Windows, can be set to the result of `GetProcessImageFileNameW`. | `/usr/bin/cmd/otelcol` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + +**[1] `error.type`:** The `error.type` SHOULD be predictable, and SHOULD have low cardinality. + +When `error.type` is set to a type (e.g., an exception type), its +canonical class name identifying the type within the artifact SHOULD be used. + +Instrumentations SHOULD document the list of errors they report. + +The cardinality of `error.type` within one instrumentation library SHOULD be low. +Telemetry consumers that aggregate data from multiple instrumentation libraries and applications +should be prepared for `error.type` to have high cardinality at query time when no +additional filters are applied. + +If the operation has completed successfully, instrumentations SHOULD NOT set `error.type`. + +If a specific domain defines its own set of error identifiers (such as HTTP or gRPC status codes), +it's RECOMMENDED to: + +- Use a domain-specific attribute +- Set `error.type` to capture all errors, regardless of whether they are defined within the domain-specific set or not. + +--- + +`error.type` 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 | Stability | +|---|---|---| +| `_OTHER` | A fallback error value to be used when the instrumentation doesn't define a custom value. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | + + + + + + +## Client (caller) spans + + + + + + + + +| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | +|---|---|---|---|---|---| +| [`process.executable.name`](/docs/attributes-registry/process.md) | string | The name of the process executable. On Linux based systems, can be set to the `Name` in `proc/[pid]/status`. On Windows, can be set to the base name of `GetProcessImageFileNameW`. | `otelcol` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`process.exit.code`](/docs/attributes-registry/process.md) | int | The exit code of the process. | `127` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`process.pid`](/docs/attributes-registry/process.md) | int | Process identifier (PID). | `1234` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`error.type`](/docs/attributes-registry/error.md) | string | Describes a class of error the operation ended with. [1] | `timeout`; `java.net.UnknownHostException`; `server_certificate_invalid`; `500` | `Conditionally Required` if and only if process.exit.code is not 0 | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| [`process.command_args`](/docs/attributes-registry/process.md) | string[] | All the command arguments (including the command/executable itself) as received by the process. On Linux-based systems (and some other Unixoid systems supporting procfs), can be set according to the list of null-delimited strings extracted from `proc/[pid]/cmdline`. For libc-based executables, this would be the full argv vector passed to `main`. | `["cmd/otecol", "--config=config.yaml"]` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`process.executable.path`](/docs/attributes-registry/process.md) | string | The full path to the process executable. On Linux based systems, can be set to the target of `proc/[pid]/exe`. On Windows, can be set to the result of `GetProcessImageFileNameW`. | `/usr/bin/cmd/otelcol` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + +**[1] `error.type`:** The `error.type` SHOULD be predictable, and SHOULD have low cardinality. + +When `error.type` is set to a type (e.g., an exception type), its +canonical class name identifying the type within the artifact SHOULD be used. + +Instrumentations SHOULD document the list of errors they report. + +The cardinality of `error.type` within one instrumentation library SHOULD be low. +Telemetry consumers that aggregate data from multiple instrumentation libraries and applications +should be prepared for `error.type` to have high cardinality at query time when no +additional filters are applied. + +If the operation has completed successfully, instrumentations SHOULD NOT set `error.type`. + +If a specific domain defines its own set of error identifiers (such as HTTP or gRPC status codes), +it's RECOMMENDED to: + +- Use a domain-specific attribute +- Set `error.type` to capture all errors, regardless of whether they are defined within the domain-specific set or not. + +--- + +`error.type` 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 | Stability | +|---|---|---| +| `_OTHER` | A fallback error value to be used when the instrumentation doesn't define a custom value. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | + + + + + + +[DocumentStatus]: https://opentelemetry.io/docs/specs/otel/document-status diff --git a/model/cli/spans.yaml b/model/cli/spans.yaml new file mode 100644 index 0000000000..4df8e9c32f --- /dev/null +++ b/model/cli/spans.yaml @@ -0,0 +1,42 @@ +groups: + - id: span.cli.internal + type: span + span_kind: internal + stability: experimental + brief: > + Describes span of CLI (Command Line Interfaces) programs. + attributes: + - ref: process.executable.name + requirement_level: required + - ref: process.executable.path + requirement_level: recommended + - ref: process.pid + requirement_level: required + - ref: process.exit.code + requirement_level: required + - ref: process.command_args + requirement_level: recommended + - ref: error.type + requirement_level: + conditionally_required: if and only if process.exit.code is not 0 + + - id: span.cli.client + type: span + span_kind: client + stability: experimental + brief: > + Describes span to calls of CLI (Command Line Interfaces) programs. + attributes: + - ref: process.executable.name + requirement_level: required + - ref: process.executable.path + requirement_level: recommended + - ref: process.pid + requirement_level: required + - ref: process.exit.code + requirement_level: required + - ref: process.command_args + requirement_level: recommended + - ref: error.type + requirement_level: + conditionally_required: if and only if process.exit.code is not 0