From 6d5ecc7ae138ae4c430caf23e2c1624b0c59291e Mon Sep 17 00:00:00 2001 From: Liudmila Molkova Date: Wed, 2 Apr 2025 19:00:46 -0700 Subject: [PATCH 1/5] Move span name, kind, status and notes to yaml --- docs/cli/cli-spans.md | 34 +++-- docs/cloud-providers/aws-sdk.md | 33 +++-- docs/database/cassandra.md | 20 ++- docs/database/cosmosdb.md | 26 ++-- docs/database/couchdb.md | 14 +- docs/database/database-spans.md | 46 +++---- docs/database/dynamodb.md | 136 +++++++++++++++++++- docs/database/elasticsearch.md | 23 ++-- docs/database/hbase.md | 20 ++- docs/database/mariadb.md | 20 +-- docs/database/mongodb.md | 22 ++-- docs/database/mssql.md | 18 ++- docs/database/mysql.md | 18 ++- docs/database/postgresql.md | 18 ++- docs/database/redis.md | 27 ++-- docs/database/sql.md | 26 ++-- docs/faas/aws-lambda.md | 21 ++- docs/faas/faas-spans.md | 45 +++++-- docs/gen-ai/azure-ai-inference.md | 20 ++- docs/gen-ai/gen-ai-agent-spans.md | 21 +-- docs/gen-ai/gen-ai-spans.md | 68 ++++++---- docs/gen-ai/openai.md | 30 +++-- docs/graphql/graphql-spans.md | 25 ++-- docs/http/http-spans.md | 46 ++++--- docs/object-stores/s3.md | 15 ++- docs/rpc/rpc-spans.md | 45 ++++--- model/aws/lambda-spans.yaml | 10 +- model/aws/{sdk-spans.yml => sdk-spans.yaml} | 85 +++++++++--- model/cli/spans.yaml | 47 ++++--- model/database/spans.yaml | 124 +++++++++++++++--- model/faas/spans.yaml | 26 ++-- model/gen-ai/spans.yaml | 32 ++++- model/graphql/spans.yml | 16 ++- model/http/spans.yaml | 28 +++- model/rpc/spans.yaml | 14 +- templates/registry/markdown/snippet.md.j2 | 7 +- templates/registry/markdown/span_macros.j2 | 17 +++ 37 files changed, 908 insertions(+), 335 deletions(-) rename model/aws/{sdk-spans.yml => sdk-spans.yaml} (73%) create mode 100644 templates/registry/markdown/span_macros.j2 diff --git a/docs/cli/cli-spans.md b/docs/cli/cli-spans.md index f9561d5257..7c719ce729 100644 --- a/docs/cli/cli-spans.md +++ b/docs/cli/cli-spans.md @@ -8,14 +8,6 @@ linkTitle: CLI programs 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. Refer to the [Recording Errors](/docs/general/recording-errors.md) document for -additional details on how to record span status. - ## Execution (callee) spans @@ -27,6 +19,19 @@ additional details on how to record span status. +**Status:** ![Development](https://img.shields.io/badge/-development-blue) + +This span describes CLI (Command Line Interfaces) program execution from a callee perspective. + +**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. Refer to +the [Recording Errors](/docs/general/recording-errors.md) document for details on how to record span status. + +**Span kind** SHOULD be `INTERNAL`. + | 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, this SHOULD be set to the base name of the target of `/proc/[pid]/exe`. On Windows, this SHOULD be set to the base name of `GetProcessImageFileNameW`. | `otelcol` | `Required` | ![Development](https://img.shields.io/badge/-development-blue) | @@ -78,6 +83,19 @@ it's RECOMMENDED to: +**Status:** ![Development](https://img.shields.io/badge/-development-blue) + +This span describes CLI (Command Line Interfaces) program execution from a caller perspective. + +**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. Refer to +the [Recording Errors](/docs/general/recording-errors.md) document for details on how to record span status. + +**Span kind** SHOULD be `CLIENT`. + | 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, this SHOULD be set to the base name of the target of `/proc/[pid]/exe`. On Windows, this SHOULD be set to the base name of `GetProcessImageFileNameW`. | `otelcol` | `Required` | ![Development](https://img.shields.io/badge/-development-blue) | diff --git a/docs/cloud-providers/aws-sdk.md b/docs/cloud-providers/aws-sdk.md index 231ccf8a7e..04ec5b1f89 100644 --- a/docs/cloud-providers/aws-sdk.md +++ b/docs/cloud-providers/aws-sdk.md @@ -2,26 +2,15 @@ linkTitle: AWS SDK ---> -# Semantic conventions for AWS SDK +# Semantic conventions for AWS SDK client spans **Status**: [Development][DocumentStatus] -This document defines semantic conventions to apply when instrumenting the AWS SDK. They map request or response -parameters in AWS SDK API calls to attributes on a Span. The conventions have been collected over time based -on feedback from AWS users of tracing and will continue to increase as new interesting conventions -are found. - -Some descriptions are also provided for populating general OpenTelemetry semantic conventions based on these APIs. - ## Context propagation See [compatibility](../non-normative/compatibility/aws.md#context-propagation). -## Common attributes - -The span name MUST be of the format `Service.Operation` as per the AWS HTTP API, e.g., `DynamoDB.GetItem`, -`S3.ListBuckets`. This is equivalent to concatenating `rpc.service` and `rpc.method` with `.` and consistent -with the naming guidelines for RPC client spans. +## AWS SDK spans @@ -31,6 +20,24 @@ with the naming guidelines for RPC client spans. +**Status:** ![Development](https://img.shields.io/badge/-development-blue) + +This span describes AWS SDK client call. + +**Span name** MUST be of the format `Service.Operation` as per the +AWS HTTP API, e.g., `DynamoDB.GetItem`, `S3.ListBuckets`. This is +equivalent to concatenating `rpc.service` and `rpc.method` with `.` and +consistent with the naming guidelines for RPC client spans. + +AWS SDK span attributes are based on the request or response parameters +in AWS SDK API calls. The conventions have been collected over time based +on feedback from AWS users of tracing and will continue to increase as new +interesting conventions are found. + +**Span kind** SHOULD be `CLIENT`. + +**Span status** SHOULD follow [Recording Errors](/docs/general/recording-errors.md) document. + | Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | |---|---|---|---|---|---| | [`rpc.system`](/docs/attributes-registry/rpc.md) | string | The value `aws-api`. | `aws-api` | `Required` | ![Development](https://img.shields.io/badge/-development-blue) | diff --git a/docs/database/cassandra.md b/docs/database/cassandra.md index 9456e4069a..6e0d3230d3 100644 --- a/docs/database/cassandra.md +++ b/docs/database/cassandra.md @@ -2,7 +2,7 @@ linkTitle: Cassandra ---> -# Semantic conventions for Cassandra +# Semantic conventions for Cassandra client operations **Status**: [Development][DocumentStatus] @@ -17,12 +17,6 @@ The Semantic Conventions for [Cassandra](https://cassandra.apache.org/) extend a ## Spans -Spans representing calls to a Cassandra database adhere to the general [Semantic Conventions for Database Client Spans](database-spans.md). - -`db.system.name` MUST be set to `"cassandra"` and SHOULD be provided **at span creation time**. - -The following table outlines the span attributes applicable to Cassandra. - @@ -30,6 +24,18 @@ The following table outlines the span attributes applicable to Cassandra. +**Status:** ![Development](https://img.shields.io/badge/-development-blue) + +Spans representing calls to a Cassandra database adhere to the general [Semantic Conventions for Database Client Spans](/docs/database/database-spans.md). + +`db.system.name` MUST be set to `"cassandra"` and SHOULD be provided **at span creation time**. + +**Span name** SHOULD follow the general [database span name convention](/docs/database/database-spans.md#name) + +**Span kind** SHOULD be `CLIENT`. + +**Span status** SHOULD follow [Recording Errors](/docs/general/recording-errors.md) document. + | Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | |---|---|---|---|---|---| | [`db.collection.name`](/docs/attributes-registry/db.md) | string | The name of the Cassandra table that the operation is acting upon. [1] | `public.users`; `customers` | `Conditionally Required` [2] | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | diff --git a/docs/database/cosmosdb.md b/docs/database/cosmosdb.md index a8e7d3b848..b9f6c0ed6c 100644 --- a/docs/database/cosmosdb.md +++ b/docs/database/cosmosdb.md @@ -2,7 +2,7 @@ linkTitle: Cosmos DB ---> -# Semantic conventions for Microsoft Azure Cosmos DB +# Semantic conventions for Microsoft Azure Cosmos DB client operations **Status**: [Development][DocumentStatus] @@ -23,15 +23,6 @@ extend and override the [Database Semantic Conventions](README.md). ## Spans -Cosmos DB instrumentations include call-level spans that represent logical database -calls and adhere to the general [Semantic Conventions for Database Client Spans](database-spans.md). - -Additional spans representing network calls may also be created depending on the connection mode (Gateway or Direct). Semantic conventions described in this document apply to the call-level spans only. - -The following table outlines the span attributes applicable to Cosmos DB. - -`db.system.name` MUST be set to `"azure.cosmosdb"` and SHOULD be provided **at span creation time**. - @@ -39,6 +30,21 @@ The following table outlines the span attributes applicable to Cosmos DB. +**Status:** ![Development](https://img.shields.io/badge/-development-blue) + +Cosmos DB instrumentations include call-level spans that represent logical database calls and adhere to the general [Semantic Conventions for Database Client Spans](/docs/database/database-spans.md). + +Additional spans representing network calls may also be created depending on the connection mode (Gateway or Direct). +Semantic conventions described in this document apply to the call-level spans only. + +`db.system.name` MUST be set to `"azure.cosmosdb"` and SHOULD be provided **at span creation time**. + +**Span name** SHOULD follow the general [database span name convention](/docs/database/database-spans.md#name) + +**Span kind** SHOULD be `CLIENT`. + +**Span status** SHOULD follow [Recording Errors](/docs/general/recording-errors.md) document. + | Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | |---|---|---|---|---|---| | [`azure.cosmosdb.connection.mode`](/docs/attributes-registry/azure.md) | string | Cosmos client connection mode. | `gateway`; `direct` | `Conditionally Required` [1] | ![Development](https://img.shields.io/badge/-development-blue) | diff --git a/docs/database/couchdb.md b/docs/database/couchdb.md index 6fd4a11171..40569b5509 100644 --- a/docs/database/couchdb.md +++ b/docs/database/couchdb.md @@ -2,7 +2,7 @@ linkTitle: CouchDB ---> -# Semantic conventions for CouchDB +# Semantic conventions for CouchDB client operations **Status**: [Development][DocumentStatus] @@ -30,6 +30,18 @@ The following table outlines the span attributes applicable to CouchDB. +**Status:** ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) + +Spans representing calls to CouchDB adhere to the general [Semantic Conventions for Database Client Spans](/docs/database/database-spans.md). + +`db.system.name` MUST be set to `"couchdb"` and SHOULD be provided **at span creation time**. + +**Span name** SHOULD follow the general [database span name convention](/docs/database/database-spans.md#name) + +**Span kind** SHOULD be `CLIENT`. + +**Span status** SHOULD follow [Recording Errors](/docs/general/recording-errors.md) document. + | Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | |---|---|---|---|---|---| | [`db.namespace`](/docs/attributes-registry/db.md) | string | The name of the database, fully qualified within the server address and port. | `customers`; `test.users` | `Conditionally Required` If available. | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | diff --git a/docs/database/database-spans.md b/docs/database/database-spans.md index e9994ca9ec..d571037242 100644 --- a/docs/database/database-spans.md +++ b/docs/database/database-spans.md @@ -9,8 +9,7 @@ linkTitle: Spans - [Name](#name) -- [Status](#status) -- [Common attributes](#common-attributes) +- [Span definition](#span-definition) - [Notes and well-known identifiers for `db.system.name`](#notes-and-well-known-identifiers-for-dbsystemname) - [Sanitization of `db.query.text`](#sanitization-of-dbquerytext) - [Generating a summary of the query text](#generating-a-summary-of-the-query-text) @@ -44,16 +43,6 @@ linkTitle: Spans > for at least six months after it starts emitting both sets of conventions. > * SHOULD drop the environment variable in the next major version. -**Span kind:** SHOULD be `CLIENT`. It MAY be set to `INTERNAL` on spans representing -in-memory database calls. -It's RECOMMENDED to use `CLIENT` kind when database system being instrumented usually -runs in a different process than its client or when database calls happen over -instrumented protocol such as HTTP. - -Span that describes database call SHOULD cover the duration of the corresponding call as if it was observed by the caller (such as client application). -For example, if a transient issue happened and was retried within this database call, the corresponding span should cover the duration of the logical operation -with all retries. - ## Name Database spans MUST follow the overall [guidelines for span names](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.43.0/specification/trace/api.md#span). @@ -81,17 +70,7 @@ 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 - -Refer to the [Recording Errors](/docs/general/recording-errors.md) document for -details on how to record span status. - -Semantic conventions for individual systems SHOULD specify which values of `db.response.status_code` -classify as errors. - -## Common attributes - -These attributes are commonly used across different database systems. +## Span definition @@ -100,6 +79,27 @@ These attributes are commonly used across different database systems. +**Status:** ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) + +This span describes database client call. + +It SHOULD cover the duration of the corresponding call as if it was observed by the caller (such as client application). +For example, if a transient issue happened and was retried within this database call, the corresponding span should cover the duration of the logical operation +with all retries. + +**Span name** is covered in the [Name](/docs/database/database-spans.md#name) section. + +**Span kind** SHOULD be `CLIENT`. It MAY be set to `INTERNAL` on spans representing +in-memory database calls. +It's RECOMMENDED to use `CLIENT` kind when database system being instrumented usually +runs in a different process than its client or when database calls happen over +instrumented protocol such as HTTP. + +**Span status** Refer to the [Recording Errors](/docs/general/recording-errors.md) +document for details on how to record span status. Semantic conventions for +individual systems SHOULD specify which values of `db.response.status_code` +classify as errors. + | Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | |---|---|---|---|---|---| | [`db.system.name`](/docs/attributes-registry/db.md) | string | The database management system (DBMS) product as identified by the client instrumentation. [1] | `other_sql`; `softwareag.adabas`; `actian.ingres` | `Required` | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | diff --git a/docs/database/dynamodb.md b/docs/database/dynamodb.md index 58de4fa9b2..d86c58c6bd 100644 --- a/docs/database/dynamodb.md +++ b/docs/database/dynamodb.md @@ -2,7 +2,7 @@ linkTitle: DynamoDB ---> -# Semantic conventions for AWS DynamoDB +# Semantic conventions for AWS DynamoDB client operations **Status**: [Development][DocumentStatus] @@ -33,10 +33,6 @@ The Semantic Conventions for [AWS DynamoDB](https://aws.amazon.com/dynamodb/) ex Spans representing calls to AWS DynamoDB adhere to the general [Semantic Conventions for Database Client Spans](database-spans.md). -The following table outlines the span attributes applicable to DynamoDB. - -`db.system.name` MUST be set to `"aws.dynamodb"` and SHOULD be provided **at span creation time**. - ### DynamoDB.BatchGetItem @@ -46,6 +42,16 @@ The following table outlines the span attributes applicable to DynamoDB. +**Status:** ![Development](https://img.shields.io/badge/-development-blue) + +This span represents `DynamoDB.BatchGetItem` call. + +`db.system.name` MUST be set to `"aws.dynamodb"` and SHOULD be provided **at span creation time**. + +**Span kind** SHOULD be `CLIENT`. + +**Span status** SHOULD follow [Recording Errors](/docs/general/recording-errors.md) document. + | Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | |---|---|---|---|---|---| | [`rpc.system`](/docs/attributes-registry/rpc.md) | string | The value `aws-api`. | `aws-api` | `Required` | ![Development](https://img.shields.io/badge/-development-blue) | @@ -86,6 +92,16 @@ The following table outlines the span attributes applicable to DynamoDB. +**Status:** ![Development](https://img.shields.io/badge/-development-blue) + +This span represents `DynamoDB.BatchWriteItem` call. + +`db.system.name` MUST be set to `"aws.dynamodb"` and SHOULD be provided **at span creation time**. + +**Span kind** SHOULD be `CLIENT`. + +**Span status** SHOULD follow [Recording Errors](/docs/general/recording-errors.md) document. + | Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | |---|---|---|---|---|---| | [`rpc.system`](/docs/attributes-registry/rpc.md) | string | The value `aws-api`. | `aws-api` | `Required` | ![Development](https://img.shields.io/badge/-development-blue) | @@ -127,6 +143,16 @@ The following table outlines the span attributes applicable to DynamoDB. +**Status:** ![Development](https://img.shields.io/badge/-development-blue) + +This span represents `DynamoDB.CreateTable` call. + +`db.system.name` MUST be set to `"aws.dynamodb"` and SHOULD be provided **at span creation time**. + +**Span kind** SHOULD be `CLIENT`. + +**Span status** SHOULD follow [Recording Errors](/docs/general/recording-errors.md) document. + | Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | |---|---|---|---|---|---| | [`rpc.system`](/docs/attributes-registry/rpc.md) | string | The value `aws-api`. | `aws-api` | `Required` | ![Development](https://img.shields.io/badge/-development-blue) | @@ -172,6 +198,16 @@ The following table outlines the span attributes applicable to DynamoDB. +**Status:** ![Development](https://img.shields.io/badge/-development-blue) + +This span represents `DynamoDB.DeleteItem` call. + +`db.system.name` MUST be set to `"aws.dynamodb"` and SHOULD be provided **at span creation time**. + +**Span kind** SHOULD be `CLIENT`. + +**Span status** SHOULD follow [Recording Errors](/docs/general/recording-errors.md) document. + | Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | |---|---|---|---|---|---| | [`rpc.system`](/docs/attributes-registry/rpc.md) | string | The value `aws-api`. | `aws-api` | `Required` | ![Development](https://img.shields.io/badge/-development-blue) | @@ -213,6 +249,16 @@ The following table outlines the span attributes applicable to DynamoDB. +**Status:** ![Development](https://img.shields.io/badge/-development-blue) + +This span represents `DynamoDB.DeleteTable` call. + +`db.system.name` MUST be set to `"aws.dynamodb"` and SHOULD be provided **at span creation time**. + +**Span kind** SHOULD be `CLIENT`. + +**Span status** SHOULD follow [Recording Errors](/docs/general/recording-errors.md) document. + | Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | |---|---|---|---|---|---| | [`rpc.system`](/docs/attributes-registry/rpc.md) | string | The value `aws-api`. | `aws-api` | `Required` | ![Development](https://img.shields.io/badge/-development-blue) | @@ -252,6 +298,16 @@ The following table outlines the span attributes applicable to DynamoDB. +**Status:** ![Development](https://img.shields.io/badge/-development-blue) + +This span represents `DynamoDB.DescribeTable` call. + +`db.system.name` MUST be set to `"aws.dynamodb"` and SHOULD be provided **at span creation time**. + +**Span kind** SHOULD be `CLIENT`. + +**Span status** SHOULD follow [Recording Errors](/docs/general/recording-errors.md) document. + | Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | |---|---|---|---|---|---| | [`rpc.system`](/docs/attributes-registry/rpc.md) | string | The value `aws-api`. | `aws-api` | `Required` | ![Development](https://img.shields.io/badge/-development-blue) | @@ -291,6 +347,16 @@ The following table outlines the span attributes applicable to DynamoDB. +**Status:** ![Development](https://img.shields.io/badge/-development-blue) + +This span represents `DynamoDB.GetItem` call. + +`db.system.name` MUST be set to `"aws.dynamodb"` and SHOULD be provided **at span creation time**. + +**Span kind** SHOULD be `CLIENT`. + +**Span status** SHOULD follow [Recording Errors](/docs/general/recording-errors.md) document. + | Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | |---|---|---|---|---|---| | [`rpc.system`](/docs/attributes-registry/rpc.md) | string | The value `aws-api`. | `aws-api` | `Required` | ![Development](https://img.shields.io/badge/-development-blue) | @@ -333,6 +399,16 @@ The following table outlines the span attributes applicable to DynamoDB. +**Status:** ![Development](https://img.shields.io/badge/-development-blue) + +This span represents `DynamoDB.ListTables` call. + +`db.system.name` MUST be set to `"aws.dynamodb"` and SHOULD be provided **at span creation time**. + +**Span kind** SHOULD be `CLIENT`. + +**Span status** SHOULD follow [Recording Errors](/docs/general/recording-errors.md) document. + | Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | |---|---|---|---|---|---| | [`rpc.system`](/docs/attributes-registry/rpc.md) | string | The value `aws-api`. | `aws-api` | `Required` | ![Development](https://img.shields.io/badge/-development-blue) | @@ -374,6 +450,16 @@ The following table outlines the span attributes applicable to DynamoDB. +**Status:** ![Development](https://img.shields.io/badge/-development-blue) + +This span represents `DynamoDB.PutItem` call. + +`db.system.name` MUST be set to `"aws.dynamodb"` and SHOULD be provided **at span creation time**. + +**Span kind** SHOULD be `CLIENT`. + +**Span status** SHOULD follow [Recording Errors](/docs/general/recording-errors.md) document. + | Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | |---|---|---|---|---|---| | [`rpc.system`](/docs/attributes-registry/rpc.md) | string | The value `aws-api`. | `aws-api` | `Required` | ![Development](https://img.shields.io/badge/-development-blue) | @@ -415,6 +501,16 @@ The following table outlines the span attributes applicable to DynamoDB. +**Status:** ![Development](https://img.shields.io/badge/-development-blue) + +This span represents `DynamoDB.Query` call. + +`db.system.name` MUST be set to `"aws.dynamodb"` and SHOULD be provided **at span creation time**. + +**Span kind** SHOULD be `CLIENT`. + +**Span status** SHOULD follow [Recording Errors](/docs/general/recording-errors.md) document. + | Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | |---|---|---|---|---|---| | [`rpc.system`](/docs/attributes-registry/rpc.md) | string | The value `aws-api`. | `aws-api` | `Required` | ![Development](https://img.shields.io/badge/-development-blue) | @@ -462,6 +558,16 @@ The following table outlines the span attributes applicable to DynamoDB. +**Status:** ![Development](https://img.shields.io/badge/-development-blue) + +This span represents `DynamoDB.Scan` call. + +`db.system.name` MUST be set to `"aws.dynamodb"` and SHOULD be provided **at span creation time**. + +**Span kind** SHOULD be `CLIENT`. + +**Span status** SHOULD follow [Recording Errors](/docs/general/recording-errors.md) document. + | Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | |---|---|---|---|---|---| | [`rpc.system`](/docs/attributes-registry/rpc.md) | string | The value `aws-api`. | `aws-api` | `Required` | ![Development](https://img.shields.io/badge/-development-blue) | @@ -512,6 +618,16 @@ The following table outlines the span attributes applicable to DynamoDB. +**Status:** ![Development](https://img.shields.io/badge/-development-blue) + +This span represents `DynamoDB.UpdateItem` call. + +`db.system.name` MUST be set to `"aws.dynamodb"` and SHOULD be provided **at span creation time**. + +**Span kind** SHOULD be `CLIENT`. + +**Span status** SHOULD follow [Recording Errors](/docs/general/recording-errors.md) document. + | Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | |---|---|---|---|---|---| | [`rpc.system`](/docs/attributes-registry/rpc.md) | string | The value `aws-api`. | `aws-api` | `Required` | ![Development](https://img.shields.io/badge/-development-blue) | @@ -553,6 +669,16 @@ The following table outlines the span attributes applicable to DynamoDB. +**Status:** ![Development](https://img.shields.io/badge/-development-blue) + +This span represents `DynamoDB.UpdateTable` call. + +`db.system.name` MUST be set to `"aws.dynamodb"` and SHOULD be provided **at span creation time**. + +**Span kind** SHOULD be `CLIENT`. + +**Span status** SHOULD follow [Recording Errors](/docs/general/recording-errors.md) document. + | Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | |---|---|---|---|---|---| | [`rpc.system`](/docs/attributes-registry/rpc.md) | string | The value `aws-api`. | `aws-api` | `Required` | ![Development](https://img.shields.io/badge/-development-blue) | diff --git a/docs/database/elasticsearch.md b/docs/database/elasticsearch.md index 28d02f2f10..5e9ce379b8 100644 --- a/docs/database/elasticsearch.md +++ b/docs/database/elasticsearch.md @@ -2,7 +2,7 @@ linkTitle: Elasticsearch ---> -# Semantic conventions for Elasticsearch +# Semantic conventions for Elasticsearch client operations **Status**: [Development][DocumentStatus] @@ -18,14 +18,6 @@ The Semantic Conventions for [Elasticsearch](https://www.elastic.co/) extend and ## Spans -Spans representing calls to Elasticsearch adhere to the general [Semantic Conventions for Database Client Spans](database-spans.md). - -The **span name** follows the [general database span name guidelines](database-spans.md#name) with the endpoint identifier stored in `db.operation.name`, and the index stored in `db.collection.name`. - -`db.system` MUST be set to `"elasticsearch"` and SHOULD be provided **at span creation time**. - -The following table outlines the span attributes applicable to Elasticsearch. - @@ -33,6 +25,19 @@ The following table outlines the span attributes applicable to Elasticsearch. +**Status:** ![Development](https://img.shields.io/badge/-development-blue) + +Spans representing calls to Elasticsearch adhere to the general [Semantic Conventions for Database Client Spans](/docs/database/database-spans.md). + +`db.system.name` MUST be set to `"elasticsearch"` and SHOULD be provided **at span creation time**. + +**Span name** SHOULD follow the general [database span name convention](/docs/database/database-spans.md#name) +with the endpoint identifier stored in `db.operation.name`, and the index stored in `db.collection.name`. + +**Span kind** SHOULD be `CLIENT`. + +**Span status** SHOULD follow [Recording Errors](/docs/general/recording-errors.md) document. + | Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | |---|---|---|---|---|---| | [`db.operation.name`](/docs/attributes-registry/db.md) | string | The name of the operation or command being executed. [1] | `search`; `ml.close_job`; `cat.aliases` | `Required` | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | diff --git a/docs/database/hbase.md b/docs/database/hbase.md index 14682bee0f..6d898c6362 100644 --- a/docs/database/hbase.md +++ b/docs/database/hbase.md @@ -2,7 +2,7 @@ linkTitle: HBase ---> -# Semantic conventions for HBase +# Semantic conventions for HBase client operations **Status**: [Development][DocumentStatus] @@ -17,12 +17,6 @@ The Semantic Conventions for [HBase](https://hbase.apache.org/) extend and overr ## Spans -Spans representing calls to an HBase database adhere to the general [Semantic Conventions for Database Client Spans](database-spans.md). - -`db.system.name` MUST be set to `"hbase"` and SHOULD be provided **at span creation time**. - -The following table outlines the span attributes applicable to HBase. - @@ -30,6 +24,18 @@ The following table outlines the span attributes applicable to HBase. +**Status:** ![Development](https://img.shields.io/badge/-development-blue) + +Spans representing calls to an HBase database adhere to the general [Semantic Conventions for Database Client Spans](/docs/database/database-spans.md). + +`db.system.name` MUST be set to `"hbase"` and SHOULD be provided **at span creation time**. + +**Span name** SHOULD follow the general [database span name convention](/docs/database/database-spans.md#name) + +**Span kind** SHOULD be `CLIENT`. + +**Span status** SHOULD follow [Recording Errors](/docs/general/recording-errors.md) document. + | Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | |---|---|---|---|---|---| | [`db.collection.name`](/docs/attributes-registry/db.md) | string | The HBase table name. [1] | `mytable`; `ns:table` | `Conditionally Required` If applicable. | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | diff --git a/docs/database/mariadb.md b/docs/database/mariadb.md index e84e8acee0..a037c80bd1 100644 --- a/docs/database/mariadb.md +++ b/docs/database/mariadb.md @@ -2,7 +2,7 @@ linkTitle: MariaDB ---> -# Semantic conventions for MariaDB +# Semantic conventions for MariaDB client operations **Status**: [Release Candidate][DocumentStatus] @@ -13,16 +13,8 @@ linkTitle: MariaDB -The Semantic Conventions for *MariaDB* extend and override the [Database Semantic Conventions](README.md). - ## Spans -Spans representing calls to MariaDB adhere to the general [Semantic Conventions for Database Client Spans](database-spans.md). - -`db.system.name` MUST be set to `"mariadb"` and SHOULD be provided **at span creation time**. - -The following table outlines the span attributes applicable to MariaDB. - @@ -30,6 +22,16 @@ The following table outlines the span attributes applicable to MariaDB. +**Status:** ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) + +Spans representing calls to MariaDB adhere to the general [Semantic Conventions for Database Client Spans](/docs/database/README.md). + +`db.system.name` MUST be set to `"mariadb"` and SHOULD be provided **at span creation time**. + +**Span kind** SHOULD be `CLIENT`. + +**Span status** SHOULD follow [Recording Errors](/docs/general/recording-errors.md) document. + | Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | |---|---|---|---|---|---| | [`db.namespace`](/docs/attributes-registry/db.md) | string | The database associated with the connection. [1] | `products`; `customers` | `Conditionally Required` If available without an additional network call. | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | diff --git a/docs/database/mongodb.md b/docs/database/mongodb.md index 7b07d25e45..9a5b909d98 100644 --- a/docs/database/mongodb.md +++ b/docs/database/mongodb.md @@ -2,14 +2,13 @@ linkTitle: MongoDB ---> -# Semantic conventions for MongoDB +# Semantic conventions for MongoDB client operations **Status**: [Development][DocumentStatus] - [Spans](#spans) -- [Attributes](#attributes) - [Example](#example) - [Metrics](#metrics) @@ -19,14 +18,6 @@ The Semantic Conventions for [MongoDB](https://www.mongodb.com/) extend and over ## Spans -Spans representing calls to MongoDB adhere to the general [Semantic Conventions for Database Client Spans](database-spans.md). - -`db.system.name` MUST be set to `"mongodb"` and SHOULD be provided **at span creation time**. - -The following table outlines the span attributes applicable to MongoDB. - -## Attributes - @@ -34,6 +25,17 @@ The following table outlines the span attributes applicable to MongoDB. +**Status:** ![Development](https://img.shields.io/badge/-development-blue) + +Spans representing calls to MongoDB adhere to the general [Semantic Conventions for Database Client Spans](/docs/database/database-spans.md). + +`db.system.name` MUST be set to `"mongodb"` and SHOULD be provided **at span creation time**. +**Span name** SHOULD follow the general [database span name convention](/docs/database/database-spans.md#name) + +**Span kind** SHOULD be `CLIENT`. + +**Span status** SHOULD follow [Recording Errors](/docs/general/recording-errors.md) document. + | Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | |---|---|---|---|---|---| | [`db.collection.name`](/docs/attributes-registry/db.md) | string | The MongoDB collection being accessed within the database stated in `db.namespace`. [1] | `public.users`; `customers` | `Required` | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | diff --git a/docs/database/mssql.md b/docs/database/mssql.md index 21e0c9c993..a5b39bbddf 100644 --- a/docs/database/mssql.md +++ b/docs/database/mssql.md @@ -2,7 +2,7 @@ linkTitle: SQL Server ---> -# Semantic conventions for Microsoft SQL Server +# Semantic conventions for Microsoft SQL Server client operations **Status**: [Release Candidate][DocumentStatus] @@ -17,12 +17,6 @@ The Semantic Conventions for *Microsoft SQL Server* extend and override the [Dat ## Spans -Spans representing calls to Microsoft SQL Server adhere to the general [Semantic Conventions for Database Client Spans](database-spans.md). - -`db.system.name` MUST be set to `"microsoft.sql_server"` and SHOULD be provided **at span creation time**. - -The following table outlines the span attributes applicable to Microsoft SQL Server. - @@ -30,6 +24,16 @@ The following table outlines the span attributes applicable to Microsoft SQL Ser +**Status:** ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) + +Spans representing calls to Microsoft SQL Server adhere to the general [Semantic Conventions for Database Client Spans](database-spans.md). + +`db.system.name` MUST be set to `"microsoft.sql_server"` and SHOULD be provided **at span creation time**. + +**Span kind** SHOULD be `CLIENT`. + +**Span status** SHOULD follow [Recording Errors](/docs/general/recording-errors.md) document. + | Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | |---|---|---|---|---|---| | [`db.namespace`](/docs/attributes-registry/db.md) | string | The database associated with the connection, qualified by the instance name. [1] | `instance1.products`; `customers` | `Conditionally Required` If available without an additional network call. | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | diff --git a/docs/database/mysql.md b/docs/database/mysql.md index ea4eb3af60..a6f9e22bf8 100644 --- a/docs/database/mysql.md +++ b/docs/database/mysql.md @@ -2,7 +2,7 @@ linkTitle: MySQL ---> -# Semantic conventions for MySQL +# Semantic conventions for MySQL client operations **Status**: [Release Candidate][DocumentStatus] @@ -17,12 +17,6 @@ The Semantic Conventions for *MySQL* extend and override the [Database Semantic ## Spans -Spans representing calls to a MySQL database adhere to the general [Semantic Conventions for Database Client Spans](database-spans.md). - -`db.system.name` MUST be set to `"mysql"` and SHOULD be provided **at span creation time**. - -The following table outlines the span attributes applicable to MySQL. - @@ -30,6 +24,16 @@ The following table outlines the span attributes applicable to MySQL. +**Status:** ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) + +Spans representing calls to a MySQL Server adhere to the general [Semantic Conventions for Database Client Spans](database-spans.md). + +`db.system.name` MUST be set to `"microsoft.sql_server"` and SHOULD be provided **at span creation time**. + +**Span kind** SHOULD be `CLIENT`. + +**Span status** SHOULD follow [Recording Errors](/docs/general/recording-errors.md) document. + | Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | |---|---|---|---|---|---| | [`db.namespace`](/docs/attributes-registry/db.md) | string | The database associated with the connection. [1] | `products`; `customers` | `Conditionally Required` If available without an additional network call. | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | diff --git a/docs/database/postgresql.md b/docs/database/postgresql.md index 082aff86e6..3630736b4b 100644 --- a/docs/database/postgresql.md +++ b/docs/database/postgresql.md @@ -2,7 +2,7 @@ linkTitle: PostgreSQL ---> -# Semantic conventions for PostgreSQL +# Semantic conventions for PostgreSQL client operations **Status**: [Release Candidate][DocumentStatus] @@ -17,12 +17,6 @@ The Semantic Conventions for *PostgreSQL* extend and override the [Database Sema ## Spans -Spans representing calls to a PostgreSQL database adhere to the general [Semantic Conventions for Database Client Spans](database-spans.md). - -`db.system.name` MUST be set to `"postgresql"` and SHOULD be provided **at span creation time**. - -The following table outlines the span attributes applicable to PostgreSQL. - @@ -30,6 +24,16 @@ The following table outlines the span attributes applicable to PostgreSQL. +**Status:** ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) + +Spans representing calls to a PostgreSQL database adhere to the general [Semantic Conventions for Database Client Spans](database-spans.md). + +`db.system.name` MUST be set to `"postgresql"` and SHOULD be provided **at span creation time**. + +**Span kind** SHOULD be `CLIENT`. + +**Span status** SHOULD follow [Recording Errors](/docs/general/recording-errors.md) document. + | Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | |---|---|---|---|---|---| | [`db.namespace`](/docs/attributes-registry/db.md) | string | The schema associated with the connection, qualified by the database name. [1] | `mydatabase.products`; `mydatabase.customers` | `Conditionally Required` If available without an additional network call. | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | diff --git a/docs/database/redis.md b/docs/database/redis.md index a751b0dad0..993445ee81 100644 --- a/docs/database/redis.md +++ b/docs/database/redis.md @@ -2,22 +2,13 @@ linkTitle: Redis ---> -# Semantic conventions for Redis +# Semantic conventions for Redis client operations **Status**: [Development][DocumentStatus] The Semantic Conventions for [Redis](https://redis.com/) extend and override the [Database Semantic Conventions](database-spans.md). -`db.system.name` MUST be set to `"redis"` and SHOULD be provided **at span creation time**. - -## Span name - -Redis spans SHOULD follow the general [database span name convention](./database-spans.md#name), -except that `db.namespace` SHOULD NOT be used in the span name since it is a numeric value that ends up -looking confusing. - -## Attributes - +## Spans @@ -25,6 +16,20 @@ looking confusing. +**Status:** ![Development](https://img.shields.io/badge/-development-blue) + +Spans representing calls to Redis adhere to the general [Semantic Conventions for Database Client Spans](/docs/database/database-spans.md). + +`db.system.name` MUST be set to `"redis"` and SHOULD be provided **at span creation time**. + +**Span name** SHOULD follow the general [database span name convention](/docs/database/database-spans.md#name) +except that `db.namespace` SHOULD NOT be used in the span name since it is a numeric value that ends up +looking confusing. + +**Span kind** SHOULD be `CLIENT`. + +**Span status** SHOULD follow [Recording Errors](/docs/general/recording-errors.md) document. + | Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | |---|---|---|---|---|---| | [`db.namespace`](/docs/attributes-registry/db.md) | string | The [database index] associated with the connection, represented as a string. [1] | `0`; `1`; `15` | `Conditionally Required` If and only if it can be captured reliably. | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | diff --git a/docs/database/sql.md b/docs/database/sql.md index 11eb7062b2..9488bb3ebd 100644 --- a/docs/database/sql.md +++ b/docs/database/sql.md @@ -2,11 +2,22 @@ linkTitle: SQL ---> -# Semantic conventions for SQL databases +# Semantic conventions for SQL databases client operations **Status**: [Release Candidate][DocumentStatus] -The SQL databases Semantic Conventions describes how common [Database Semantic Conventions](database-spans.md) apply to SQL databases. +## Spans + + + + + + + + +**Status:** ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) + +The SQL databases Semantic Conventions describes how common [Database Semantic Conventions](/docs/database/database-spans.md) apply to SQL databases. The following database systems (defined in the [`db.system.name`](./database-spans.md#notes-and-well-known-identifiers-for-dbsystemname) set) are known to use SQL as their primary query language: @@ -30,14 +41,11 @@ The following database systems (defined in the [`db.system.name`](./database-spa Many other database systems support SQL and can be accessed via generic database driver such as JDBC or ODBC. Instrumentations applied to generic SQL drivers SHOULD adhere to SQL semantic conventions. -## Attributes +**Span name** SHOULD follow the general [database span name convention](/docs/database/database-spans.md#name) - - - - - - +**Span kind** SHOULD be `CLIENT`. + +**Span status** SHOULD follow [Recording Errors](/docs/general/recording-errors.md) document. | Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | |---|---|---|---|---|---| diff --git a/docs/faas/aws-lambda.md b/docs/faas/aws-lambda.md index 1b9bb6279f..7b8331105e 100644 --- a/docs/faas/aws-lambda.md +++ b/docs/faas/aws-lambda.md @@ -30,18 +30,13 @@ use cases. ## All triggers -For all events, a span with kind `SERVER` SHOULD be created corresponding to the function invocation unless stated -otherwise below. Unless stated otherwise below, the name of the span MUST be set to the function name from the -Lambda `Context`. +For all events, a span with kind `SERVER` SHOULD be created corresponding to the function invocation unless stated otherwise below. The following attributes SHOULD be set: - [`faas.invocation_id`][faas] - The value of the AWS Request ID, which is always available through an accessor on the Lambda `Context`. - [`cloud.account.id`][cloud] - In some languages, this is available as an accessor on the Lambda `Context`. Otherwise, it can be parsed from the ARN as the fifth item when splitting on `:` -Also consider setting other attributes of the [`faas` resource][faasres] and [trace][faas] conventions -and the [cloud resource conventions][cloud]. The following AWS Lambda-specific attribute MAY also be set: - @@ -49,6 +44,20 @@ and the [cloud resource conventions][cloud]. The following AWS Lambda-specific a +**Status:** ![Development](https://img.shields.io/badge/-development-blue) + +This span represents AWS Lambda invocation. + +Consider setting other attributes of the [`faas` resource][faasres] and [trace][faas] conventions +and the [cloud resource conventions][cloud]. + +**Span name** MUST be set to the function name from the Lambda `Context` +unless stated otherwise. + +**Span kind** MUST be set to `SERVER` unless stated otherwise. + +**Span status** SHOULD follow [Recording Errors](/docs/general/recording-errors.md) document. + | Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | |---|---|---|---|---|---| | [`aws.lambda.invoked_arn`](/docs/attributes-registry/aws.md) | string | The full invoked ARN as provided on the `Context` passed to the function (`Lambda-Runtime-Invoked-Function-Arn` header on the `/runtime/invocation/next` applicable). [1] | `arn:aws:lambda:us-east-1:123456:function:myfunction:myalias` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | diff --git a/docs/faas/faas-spans.md b/docs/faas/faas-spans.md index 3e14991daa..110c48a8b2 100644 --- a/docs/faas/faas-spans.md +++ b/docs/faas/faas-spans.md @@ -127,9 +127,7 @@ The span attribute `faas.invocation_id` differs from the [resource attribute][Fa This section describes incoming FaaS invocations as they are reported by the FaaS instance itself. -For incoming FaaS spans, the span kind SHOULD be `SERVER`. - -### Incoming FaaS span attributes +### Incoming FaaS Span attributes @@ -138,6 +136,14 @@ For incoming FaaS spans, the span kind SHOULD be `SERVER`. +**Status:** ![Development](https://img.shields.io/badge/-development-blue) + +This span represents server (incoming) side of the FaaS invocation. + +**Span kind** SHOULD be `SERVER`. + +**Span status** SHOULD follow [Recording Errors](/docs/general/recording-errors.md) document. + | Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | |---|---|---|---|---|---| | [`faas.trigger`](/docs/attributes-registry/faas.md) | string | Type of the trigger which caused this function invocation. [1] | `datasource`; `http`; `pubsub` | `Required` | ![Development](https://img.shields.io/badge/-development-blue) | @@ -186,8 +192,6 @@ In principle, the above considerations apply to any resource attribute that fulf This section describes outgoing FaaS invocations as they are reported by a client calling a FaaS instance. -For outgoing FaaS spans, the span kind SHOULD be `CLIENT`. - The values reported by the client for the attributes listed below SHOULD be equal to the corresponding [FaaS resource attributes][] and [Cloud resource attributes][], which the invoked FaaS instance reports about itself, if it's instrumented. @@ -199,6 +203,18 @@ which the invoked FaaS instance reports about itself, if it's instrumented. +**Status:** ![Development](https://img.shields.io/badge/-development-blue) + +This span represents outgoing call to FaaS service. + +The values reported by the client for the attributes listed below SHOULD be equal to +the corresponding [FaaS resource attributes][] and [Cloud resource attributes][], +which the invoked FaaS instance reports about itself, if it's instrumented. + +**Span kind** SHOULD be `CLIENT`. + +**Span status** SHOULD follow [Recording Errors](/docs/general/recording-errors.md) document. + | Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | |---|---|---|---|---|---| | [`faas.invoked_name`](/docs/attributes-registry/faas.md) | string | The name of the invoked function. [1] | `my-function` | `Required` | ![Development](https://img.shields.io/badge/-development-blue) | @@ -239,9 +255,6 @@ This section describes how to handle the span creation and additional attributes ### Datasource -A datasource function is triggered as a response to some data source operation such as a database or filesystem read/write. -FaaS instrumentations that produce `faas` spans with trigger `datasource`, SHOULD use the following set of attributes. - @@ -249,6 +262,14 @@ FaaS instrumentations that produce `faas` spans with trigger `datasource`, SHOUL +**Status:** ![Development](https://img.shields.io/badge/-development-blue) + +This span represents server side if the FaaS invocations triggered in response response to some data source operation such as a database or filesystem read/write. + +**Span kind** SHOULD be `SERVER`. + +**Span status** SHOULD follow [Recording Errors](/docs/general/recording-errors.md) document. + | Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | |---|---|---|---|---|---| | [`faas.document.collection`](/docs/attributes-registry/faas.md) | string | The name of the source on which the triggering operation was performed. For example, in Cloud Storage or S3 corresponds to the bucket name, and in Cosmos DB to the database name. | `myBucketName`; `myDbName` | `Required` | ![Development](https://img.shields.io/badge/-development-blue) | @@ -294,6 +315,14 @@ A function is scheduled to be executed regularly. The following additional attri +**Status:** ![Development](https://img.shields.io/badge/-development-blue) + +This span represents server side if the FaaS invocations triggered by a timer. + +**Span kind** SHOULD be `SERVER`. + +**Span status** SHOULD follow [Recording Errors](/docs/general/recording-errors.md) document. + | Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | |---|---|---|---|---|---| | [`faas.cron`](/docs/attributes-registry/faas.md) | string | A string containing the schedule period as [Cron Expression](https://docs.oracle.com/cd/E12058_01/doc/doc.1014/e12030/cron_expressions.htm). | `0/5 * * * ? *` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | diff --git a/docs/gen-ai/azure-ai-inference.md b/docs/gen-ai/azure-ai-inference.md index 1ce8be1abd..9d9e575d32 100644 --- a/docs/gen-ai/azure-ai-inference.md +++ b/docs/gen-ai/azure-ai-inference.md @@ -2,17 +2,13 @@ linkTitle: Azure AI Inference ---> -# Semantic conventions for Azure AI Inference +# Semantic conventions for Azure AI Inference client operations **Status**: [Development][DocumentStatus] The Semantic Conventions for [Azure AI Inference](https://learn.microsoft.com/azure/ai-studio) extend and override the [GenAI Semantic Conventions](README.md). -## Azure AI Inference spans - -`gen_ai.system` MUST be set to `"az.ai.inference"` and SHOULD be provided **at span creation time**. - -### Attributes +## Spans @@ -21,6 +17,18 @@ The Semantic Conventions for [Azure AI Inference](https://learn.microsoft.com/az +**Status:** ![Development](https://img.shields.io/badge/-development-blue) + +Semantic Conventions for [Azure AI Inference](https://learn.microsoft.com/azure/ai-studio/reference/reference-model-inference-api) client spans extend and override the semantic conventions for [Gen AI Spans](gen-ai-spans.md). + +`gen_ai.system` MUST be set to `"az.ai.inference"` and SHOULD be provided **at span creation time**. + +**Span name** SHOULD follow the general [GenAI span name convention](/docs/gen-ai/spans.md#span-name). + +**Span kind** SHOULD be `CLIENT`. + +**Span status** SHOULD follow [Recording Errors](/docs/general/recording-errors.md) document. + | Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | |---|---|---|---|---|---| | [`gen_ai.operation.name`](/docs/attributes-registry/gen-ai.md) | string | The name of the operation being performed. [1] | `chat`; `text_completion`; `embeddings` | `Required` | ![Development](https://img.shields.io/badge/-development-blue) | diff --git a/docs/gen-ai/gen-ai-agent-spans.md b/docs/gen-ai/gen-ai-agent-spans.md index 64d51be0aa..ab8c458a35 100644 --- a/docs/gen-ai/gen-ai-agent-spans.md +++ b/docs/gen-ai/gen-ai-agent-spans.md @@ -28,14 +28,6 @@ The semantic conventions for GenAI agents extend and override the semantic conve ### Create agent span -Describes GenAI agent creation and is usually applicable when working with remote agent -services. - -The `gen_ai.operation.name` SHOULD be `create_agent`. - -The **span name** SHOULD be `create_agent {gen_ai.agent.name}`. -Semantic conventions for individual GenAI systems and frameworks MAY specify different span name format. - @@ -43,6 +35,19 @@ Semantic conventions for individual GenAI systems and frameworks MAY specify dif +**Status:** ![Development](https://img.shields.io/badge/-development-blue) + +Describes GenAI agent creation and is usually applicable when working with remote agent services. + +The `gen_ai.operation.name` SHOULD be `create_agent`. + +**Span name** SHOULD be `create_agent {gen_ai.agent.name}`. +Semantic conventions for individual GenAI systems and frameworks MAY specify different span name format. + +**Span kind** SHOULD be `CLIENT`. + +**Span status** SHOULD follow [Recording Errors](/docs/general/recording-errors.md) document. + | Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | |---|---|---|---|---|---| | [`gen_ai.operation.name`](/docs/attributes-registry/gen-ai.md) | string | The name of the operation being performed. [1] | `chat`; `text_completion`; `embeddings` | `Required` | ![Development](https://img.shields.io/badge/-development-blue) | diff --git a/docs/gen-ai/gen-ai-spans.md b/docs/gen-ai/gen-ai-spans.md index ec1b20faa2..d0118896a0 100644 --- a/docs/gen-ai/gen-ai-spans.md +++ b/docs/gen-ai/gen-ai-spans.md @@ -2,43 +2,31 @@ linkTitle: Spans ---> -# Semantic conventions for generative AI spans +# Semantic conventions for generative client AI spans **Status**: [Development][DocumentStatus] -- [Name](#name) - - [Status](#status) -- [GenAI attributes](#genai-attributes) -- [Execute Tool Span](#execute-tool-span) +- [Spans](#spans) + - [GenAI span](#genai-span) + - [Execute Tool Span](#execute-tool-span) - [Capturing inputs and outputs](#capturing-inputs-and-outputs) A request to an Generative AI is modeled as a span in a trace. -**Span kind:** SHOULD be `CLIENT`. It MAY be set to `INTERNAL` on spans representing -call to models running in the same process. -It's RECOMMENDED to use `CLIENT` kind when GenAI system being instrumented usually -runs in a different process than its client or when GenAI call happens over -instrumented protocol such as HTTP. +## Spans -## Name +### GenAI span -GenAI spans MUST follow the overall [guidelines for span names](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.43.0/specification/trace/api.md#span). -The **span name** SHOULD be `{gen_ai.operation.name} {gen_ai.request.model}`. -Semantic conventions for individual GenAI systems and frameworks MAY specify different span name format. +The span contains input data and metadata for a request to a GenAI model. +Each attribute represents a concept that is common to most Generative AI clients. +Many of these attributes only apply to specific GenAI operations. -### Status - -Refer to the [Recording Errors](/docs/general/recording-errors.md) document for -details on how to record span status. - -## GenAI attributes - -These attributes track input data and metadata for a request to a GenAI model. Each attribute represents a concept that is common to most Generative AI clients. -Many of these attributes only apply to specific GenAI operations. For example, GenAI embeddings requests don't use output tokens, so `gen_ai.usage.output_tokens` does not apply to embeddings operations. +For example, GenAI embeddings requests don't use output tokens, +so `gen_ai.usage.output_tokens` does not apply to embeddings operations. @@ -47,6 +35,21 @@ Many of these attributes only apply to specific GenAI operations. For example, G +**Status:** ![Development](https://img.shields.io/badge/-development-blue) + +This span represents client call to Generative AI model or service. + +**Span name** SHOULD be `{gen_ai.operation.name} {gen_ai.request.model}`. +Semantic conventions for individual GenAI systems and frameworks MAY specify different span name format +and MUST follow the overall [guidelines for span names](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.37.0/specification/trace/api.md#span). + +**Span kind** SHOULD be `CLIENT`and MAY be set to `INTERNAL` on spans representing +call to models running in the same process. It's RECOMMENDED to use `CLIENT` kind +when GenAI system being instrumented usually runs in a different process than its +client or when GenAI call happens over instrumented protocol such as HTTP. + +**Span status** SHOULD follow [Recording Errors](/docs/general/recording-errors.md) document. + | Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | |---|---|---|---|---|---| | [`gen_ai.operation.name`](/docs/attributes-registry/gen-ai.md) | string | The name of the operation being performed. [1] | `chat`; `text_completion`; `embeddings` | `Required` | ![Development](https://img.shields.io/badge/-development-blue) | @@ -163,7 +166,7 @@ Additional output format details may be recorded in the future in the `gen_ai.ou -## Execute Tool Span +### Execute Tool Span @@ -172,6 +175,23 @@ Additional output format details may be recorded in the future in the `gen_ai.ou +**Status:** ![Development](https://img.shields.io/badge/-development-blue) + +Describes tool execution span. + +`gen_ai.operation.name` SHOULD be `execute_tool`. + +**Span name** SHOULD be `execute_tool {gen_ai.tool.name}`. + +GenAI instrumentations that are able to instrument tool execution call SHOULD do so. +However, it's common for tools to be executed by the application code. It's recommended +for the application developers to follow this semantic conventions for tool invoked +by the application code. + +**Span kind** SHOULD be `INTERNAL`. + +**Span status** SHOULD follow [Recording Errors](/docs/general/recording-errors.md) document. + | Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | |---|---|---|---|---|---| | [`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 the operation ended in an error | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | diff --git a/docs/gen-ai/openai.md b/docs/gen-ai/openai.md index 42d1c0b798..972a99e96f 100644 --- a/docs/gen-ai/openai.md +++ b/docs/gen-ai/openai.md @@ -2,28 +2,22 @@ linkTitle: OpenAI ---> -# Semantic conventions for OpenAI operations +# Semantic conventions for OpenAI client operations **Status**: [Development][DocumentStatus] -- [OpenAI spans](#openai-spans) -- [OpenAI Metrics](#openai-metrics) +- [Spans](#spans) +- [Metrics](#metrics) - [Metric: `gen_ai.client.token.usage`](#metric-gen_aiclienttokenusage) - [Metric: `gen_ai.client.operation.duration`](#metric-gen_aiclientoperationduration) -The Semantic Conventions for [OpenAI](https://openai.com/) extend and override the semantic conventions -for [Gen AI Spans](gen-ai-spans.md) and [Gen AI Metrics](gen-ai-metrics.md). +The Semantic Conventions for [OpenAI](https://openai.com/) extend and override the [Gen AI Semantic Conventions](/docs/gen-ai/README.md). -`gen_ai.system` MUST be set to `"openai"`. - -## OpenAI spans - -These attributes track input data and metadata for a request to an OpenAI model. The attributes include general Generative AI -attributes and ones specific the OpenAI. +## Spans @@ -32,6 +26,18 @@ attributes and ones specific the OpenAI. +**Status:** ![Development](https://img.shields.io/badge/-development-blue) + +Semantic Conventions for [OpenAI](https://openai.com/) client spans extend and override the semantic conventions for [Gen AI Spans](gen-ai-spans.md). + +`gen_ai.system` MUST be set to `"openai"` and SHOULD be provided **at span creation time**. + +**Span name** SHOULD follow the general [GenAI span name convention](/docs/gen-ai/spans.md#span-name). + +**Span kind** SHOULD be `CLIENT`. + +**Span status** SHOULD follow [Recording Errors](/docs/general/recording-errors.md) document. + | Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | |---|---|---|---|---|---| | [`gen_ai.operation.name`](/docs/attributes-registry/gen-ai.md) | string | The name of the operation being performed. [1] | `chat`; `text_completion`; `embeddings` | `Required` | ![Development](https://img.shields.io/badge/-development-blue) | @@ -129,7 +135,7 @@ Additional output format details may be recorded in the future in the `gen_ai.ou -## OpenAI Metrics +## Metrics OpenAI metrics follow [Generative AI metrics](gen-ai-metrics.md) with the noted additional attributes. Individual systems may include additional system-specific attributes. It is recommended to check system-specific documentation, if available. diff --git a/docs/graphql/graphql-spans.md b/docs/graphql/graphql-spans.md index 0327159d6a..f5d5e2d3c0 100644 --- a/docs/graphql/graphql-spans.md +++ b/docs/graphql/graphql-spans.md @@ -2,14 +2,22 @@ linkTitle: GraphQL server ---> -# Semantic conventions for GraphQL server +# Semantic conventions for GraphQL server spans **Status**: [Development][DocumentStatus] -This document defines semantic conventions to apply when instrumenting the GraphQL implementation. They map GraphQL -operations to attributes on a Span. + + + + + + + +**Status:** ![Development](https://img.shields.io/badge/-development-blue) + +This span represents incoming operation on GraphQL server implementation. -The **span name** SHOULD be of the format `{graphql.operation.type}` provided +**Span name** SHOULD be of the format `{graphql.operation.type}` provided `graphql.operation.type` is available. If `graphql.operation.type` is not available, the span SHOULD be named `GraphQL Operation`. @@ -22,12 +30,9 @@ the span SHOULD be named `GraphQL Operation`. > span name following `{graphql.operation.type} {graphql.operation.name}` format > when `graphql.operation.name` is available. - - - - - - +**Span kind** SHOULD be `SERVER`. + +**Span status** SHOULD follow [Recording Errors](/docs/general/recording-errors.md) document. | Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | |---|---|---|---|---|---| diff --git a/docs/http/http-spans.md b/docs/http/http-spans.md index e05e8e74b7..783560e474 100644 --- a/docs/http/http-spans.md +++ b/docs/http/http-spans.md @@ -14,7 +14,7 @@ and various HTTP versions like 1.1, 2 and SPDY. - [Name](#name) - [Status](#status) -- [HTTP client](#http-client) +- [HTTP client span](#http-client-span) - [HTTP client span duration](#http-client-span-duration) - [HTTP request retries and redirects](#http-request-retries-and-redirects) - [HTTP server](#http-server) @@ -22,7 +22,7 @@ and various HTTP versions like 1.1, 2 and SPDY. - [Setting `server.address` and `server.port` attributes](#setting-serveraddress-and-serverport-attributes) - [Simple client/server example](#simple-clientserver-example) - [Client/server example with reverse proxy](#clientserver-example-with-reverse-proxy) - - [HTTP server semantic conventions](#http-server-semantic-conventions) + - [HTTP server span](#http-server-span) - [Examples](#examples) - [HTTP client-server example](#http-client-server-example) - [HTTP client retries examples](#http-client-retries-examples) @@ -115,9 +115,20 @@ and SHOULD set the `error.type` attribute. **Status**: [Development][DocumentStatus] - Refer to the [Recording Errors](/docs/general/recording-errors.md) document for general considerations on how to record span status. -## HTTP client +## HTTP client span -This span type represents an outbound HTTP request. There are two ways this can be achieved in an instrumentation: + + + + + + + +**Status:** ![Stable](https://img.shields.io/badge/-stable-lightgreen) + +This span represents an outbound HTTP request. + +There are two ways HTTP client spans can be implemented in an instrumentation: 1. Instrumentations SHOULD create an HTTP span for each attempt to send an HTTP request over the wire. In case the request is resent, the resend attempts MUST follow the [HTTP resend spec](#http-request-retries-and-redirects). @@ -127,14 +138,11 @@ This span type represents an outbound HTTP request. There are two ways this can instrumentations MAY create an HTTP span for the top-most operation of the HTTP client. In this case, the `url.full` MUST be the absolute URL that was originally requested, before any HTTP-redirects that may happen when executing the request. -For an HTTP client span, `SpanKind` MUST be `CLIENT`. +**Span name:** refer to the [Span Name](#span-name) section. - - - - - - +**Span kind** MUST be `SERVER`. + +**Span status:** refer to the [Span Status](#span-status) section. | Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | |---|---|---|---|---|---| @@ -379,11 +387,7 @@ Application developers MAY overwrite potentially inaccurate values of `server.*` [Forwarded#host]: https://developer.mozilla.org/docs/Web/HTTP/Headers/Forwarded#host [X-Forwarded-Host]: https://developer.mozilla.org/docs/Web/HTTP/Headers/X-Forwarded-Host -### HTTP server semantic conventions - -This span type represents an inbound HTTP request. - -For an HTTP server span, `SpanKind` MUST be `SERVER`. +### HTTP server span @@ -392,6 +396,16 @@ For an HTTP server span, `SpanKind` MUST be `SERVER`. +**Status:** ![Stable](https://img.shields.io/badge/-stable-lightgreen) + +This span represents an inbound HTTP request. + +**Span name:** refer to the [Span Name](#span-name) section. + +**Span kind** MUST be `SERVER`. + +**Span status:** refer to the [Span Status](#span-status) section. + | Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | |---|---|---|---|---|---| | [`http.request.method`](/docs/attributes-registry/http.md) | string | HTTP request method. [1] | `GET`; `POST`; `HEAD` | `Required` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | diff --git a/docs/object-stores/s3.md b/docs/object-stores/s3.md index b3f70b83c9..10b72a9746 100644 --- a/docs/object-stores/s3.md +++ b/docs/object-stores/s3.md @@ -2,15 +2,10 @@ linkTitle: S3 ---> -# Semantic conventions for AWS S3 +# Semantic conventions for AWS S3 client spans **Status**: [Development][DocumentStatus] -The Semantic Conventions for AWS S3 extend the general -[AWS SDK Semantic Conventions](/docs/cloud-providers/aws-sdk.md) -that describe common AWS SDK attributes in addition to the Semantic Conventions -described on this page. - @@ -18,6 +13,14 @@ described on this page. +**Status:** ![Development](https://img.shields.io/badge/-development-blue) + +Semantic Conventions for AWS S3 client spans extend the general [AWS SDK Semantic Conventions](/docs/cloud-providers/aws-sdk.md) + +**Span kind** SHOULD be `CLIENT`. + +**Span status** SHOULD follow [Recording Errors](/docs/general/recording-errors.md) document. + | Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | |---|---|---|---|---|---| | [`rpc.system`](/docs/attributes-registry/rpc.md) | string | The value `aws-api`. | `aws-api` | `Required` | ![Development](https://img.shields.io/badge/-development-blue) | diff --git a/docs/rpc/rpc-spans.md b/docs/rpc/rpc-spans.md index 27e9c22563..b6812a56ac 100644 --- a/docs/rpc/rpc-spans.md +++ b/docs/rpc/rpc-spans.md @@ -13,10 +13,9 @@ This document defines how to describe remote procedure calls - [Common remote procedure call conventions](#common-remote-procedure-call-conventions) - [Span name](#span-name) - - [Span status](#span-status) - [Service name](#service-name) - - [Client attributes](#client-attributes) - - [Server attributes](#server-attributes) + - [RPC client span](#rpc-client-span) + - [RPC server span](#rpc-server-span) - [Events](#events) - [Message event](#message-event) - [Distinction from HTTP spans](#distinction-from-http-spans) @@ -52,12 +51,6 @@ This document defines how to describe remote procedure calls ## Common remote procedure call conventions -A remote procedure calls is described by two separate spans, one on the client-side and one on the server-side. - -For outgoing requests, the `SpanKind` MUST be set to `CLIENT` and for incoming requests to `SERVER`. - -Remote procedure calls can only be represented with these semantic conventions, when the names of the called service and method are known and available. - ### Span name The *span name* MUST be the full RPC method name formatted as: @@ -78,10 +71,6 @@ Examples of span names: `MyServiceReference.ICalculator/Add` reported by the client for .NET WCF calls - `MyServiceWithNoPackage/theMethod` -### Span status - -Refer to the [Recording Errors](/docs/general/recording-errors.md) document for -details on how to record span status. ### Service name @@ -97,7 +86,7 @@ Generally, a user SHOULD NOT set `peer.service` to a fully qualified RPC service [`service.name`]: /docs/resource/README.md#service [`peer.service`]: /docs/general/attributes.md#general-remote-service-attributes -### Client attributes +### RPC client span @@ -106,6 +95,19 @@ Generally, a user SHOULD NOT set `peer.service` to a fully qualified RPC service +**Status:** ![Development](https://img.shields.io/badge/-development-blue) + +This span represents an outgoing Remote Procedure (RPC) call. + +Remote procedure calls can only be represented with these semantic conventions, +when the names of the called service and method are known and available. + +**Span name:** refer to the [Span Name](#span-name) section. + +**Span kind** SHOULD be `CLIENT`. + +**Span status** SHOULD follow [Recording Errors](/docs/general/recording-errors.md) document. + | Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | |---|---|---|---|---|---| | [`rpc.system`](/docs/attributes-registry/rpc.md) | string | A string identifying the remoting system. See below for a list of well-known identifiers. | `grpc`; `java_rmi`; `dotnet_wcf` | `Required` | ![Development](https://img.shields.io/badge/-development-blue) | @@ -174,7 +176,7 @@ different processes could be listening on TCP port 12345 and UDP port 12345. -### Server attributes +### RPC server span @@ -183,6 +185,19 @@ different processes could be listening on TCP port 12345 and UDP port 12345. +**Status:** ![Development](https://img.shields.io/badge/-development-blue) + +This span represents an incoming Remote Procedure (RPC) call. + +Remote procedure calls can only be represented with these semantic conventions, +when the names of the called service and method are known and available. + +**Span name:** refer to the [Span Name](#span-name) section. + +**Span kind** SHOULD be `SERVER`. + +**Span status** SHOULD follow [Recording Errors](/docs/general/recording-errors.md) document. + | Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | |---|---|---|---|---|---| | [`rpc.system`](/docs/attributes-registry/rpc.md) | string | A string identifying the remoting system. See below for a list of well-known identifiers. | `grpc`; `java_rmi`; `dotnet_wcf` | `Required` | ![Development](https://img.shields.io/badge/-development-blue) | diff --git a/model/aws/lambda-spans.yaml b/model/aws/lambda-spans.yaml index 0374b12cdc..86be106f54 100644 --- a/model/aws/lambda-spans.yaml +++ b/model/aws/lambda-spans.yaml @@ -4,7 +4,15 @@ groups: span_kind: server stability: development brief: > - Span attributes used by AWS Lambda (in addition to general `faas` attributes). + This span represents AWS Lambda invocation. + note: | + Consider setting other attributes of the [`faas` resource][faasres] and [trace][faas] conventions + and the [cloud resource conventions][cloud]. + + **Span name** MUST be set to the function name from the Lambda `Context` + unless stated otherwise. + + **Span kind** MUST be set to `SERVER` unless stated otherwise. attributes: - ref: aws.lambda.invoked_arn requirement_level: recommended diff --git a/model/aws/sdk-spans.yml b/model/aws/sdk-spans.yaml similarity index 73% rename from model/aws/sdk-spans.yml rename to model/aws/sdk-spans.yaml index f54e61fd89..16bf00e504 100644 --- a/model/aws/sdk-spans.yml +++ b/model/aws/sdk-spans.yaml @@ -4,13 +4,17 @@ groups: stability: development span_kind: client brief: > - The `aws` conventions apply to operations using the AWS SDK. They map request or response parameters - in AWS SDK API calls to attributes on a Span. The conventions have been collected over time based - on feedback from AWS users of tracing and will continue to evolve as new interesting conventions - are found. + This span describes AWS SDK client call. + note: | + **Span name** MUST be of the format `Service.Operation` as per the + AWS HTTP API, e.g., `DynamoDB.GetItem`, `S3.ListBuckets`. This is + equivalent to concatenating `rpc.service` and `rpc.method` with `.` and + consistent with the naming guidelines for RPC client spans. - Some descriptions are also provided for populating general OpenTelemetry semantic conventions based on - these APIs. + AWS SDK span attributes are based on the request or response parameters + in AWS SDK API calls. The conventions have been collected over time based + on feedback from AWS users of tracing and will continue to increase as new + interesting conventions are found. attributes: - ref: rpc.system brief: "The value `aws-api`." @@ -34,7 +38,10 @@ groups: conditionally_required: If available. - id: span.dynamodb.batchgetitem.client - brief: DynamoDB.BatchGetItem + brief: > + This span represents `DynamoDB.BatchGetItem` call. + note: > + `db.system.name` MUST be set to `"aws.dynamodb"` and SHOULD be provided **at span creation time**. extends: span.aws.client stability: development type: span @@ -46,7 +53,10 @@ groups: requirement_level: recommended - id: span.dynamodb.batchwriteitem.client - brief: DynamoDB.BatchWriteItem + brief: > + This span represents `DynamoDB.BatchWriteItem` call. + note: > + `db.system.name` MUST be set to `"aws.dynamodb"` and SHOULD be provided **at span creation time**. extends: span.aws.client type: span stability: development @@ -60,7 +70,10 @@ groups: requirement_level: recommended - id: span.dynamodb.createtable.client - brief: DynamoDB.CreateTable + brief: > + This span represents `DynamoDB.CreateTable` call. + note: > + `db.system.name` MUST be set to `"aws.dynamodb"` and SHOULD be provided **at span creation time**. extends: span.aws.client type: span stability: development @@ -85,7 +98,10 @@ groups: requirement_level: recommended - id: span.dynamodb.deleteitem.client - brief: DynamoDB.DeleteItem + brief: > + This span represents `DynamoDB.DeleteItem` call. + note: > + `db.system.name` MUST be set to `"aws.dynamodb"` and SHOULD be provided **at span creation time**. extends: span.aws.client type: span stability: development @@ -102,7 +118,10 @@ groups: requirement_level: recommended - id: span.dynamodb.deletetable.client - brief: DynamoDB.DeleteTable + brief: > + This span represents `DynamoDB.DeleteTable` call. + note: > + `db.system.name` MUST be set to `"aws.dynamodb"` and SHOULD be provided **at span creation time**. extends: span.aws.client type: span stability: development @@ -115,7 +134,10 @@ groups: - Users - id: span.dynamodb.describetable.client - brief: DynamoDB.DescribeTable + brief: > + This span represents `DynamoDB.DescribeTable` call. + note: > + `db.system.name` MUST be set to `"aws.dynamodb"` and SHOULD be provided **at span creation time**. extends: span.aws.client type: span stability: development @@ -128,7 +150,10 @@ groups: - Users - id: span.dynamodb.getitem.client - brief: DynamoDB.GetItem + brief: > + This span represents `DynamoDB.GetItem` call. + note: > + `db.system.name` MUST be set to `"aws.dynamodb"` and SHOULD be provided **at span creation time**. extends: span.aws.client type: span stability: development @@ -147,7 +172,10 @@ groups: requirement_level: recommended - id: span.dynamodb.listtables.client - brief: DynamoDB.ListTables + brief: > + This span represents `DynamoDB.ListTables` call. + note: > + `db.system.name` MUST be set to `"aws.dynamodb"` and SHOULD be provided **at span creation time**. extends: span.aws.client type: span stability: development @@ -161,7 +189,10 @@ groups: requirement_level: recommended - id: span.dynamodb.putitem.client - brief: DynamoDB.PutItem + brief: > + This span represents `DynamoDB.PutItem` call. + note: > + `db.system.name` MUST be set to `"aws.dynamodb"` and SHOULD be provided **at span creation time**. extends: span.aws.client type: span stability: development @@ -175,7 +206,10 @@ groups: requirement_level: recommended - id: span.dynamodb.query.client - brief: DynamoDB.Query + brief: > + This span represents `DynamoDB.Query` call. + note: > + `db.system.name` MUST be set to `"aws.dynamodb"` and SHOULD be provided **at span creation time**. extends: span.aws.client type: span stability: development @@ -204,7 +238,10 @@ groups: requirement_level: recommended - id: span.dynamodb.scan.client - brief: DynamoDB.Scan + brief: > + This span represents `DynamoDB.Scan` call. + note: > + `db.system.name` MUST be set to `"aws.dynamodb"` and SHOULD be provided **at span creation time**. extends: span.aws.client type: span stability: development @@ -239,7 +276,10 @@ groups: requirement_level: recommended - id: span.dynamodb.updateitem.client - brief: DynamoDB.UpdateItem + brief: > + This span represents `DynamoDB.UpdateItem` call. + note: > + `db.system.name` MUST be set to `"aws.dynamodb"` and SHOULD be provided **at span creation time**. extends: span.aws.client type: span span_kind: client @@ -256,7 +296,10 @@ groups: requirement_level: recommended - id: span.dynamodb.updatetable.client - brief: DynamoDB.UpdateTable + brief: > + This span represents `DynamoDB.UpdateTable` call. + note: > + `db.system.name` MUST be set to `"aws.dynamodb"` and SHOULD be provided **at span creation time**. extends: span.aws.client type: span stability: development @@ -283,7 +326,9 @@ groups: type: span stability: development span_kind: client - brief: "Attributes that exist for S3 request types." + brief: > + Semantic Conventions for AWS S3 client spans extend the general + [AWS SDK Semantic Conventions](/docs/cloud-providers/aws-sdk.md) attributes: - ref: aws.s3.bucket requirement_level: recommended diff --git a/model/cli/spans.yaml b/model/cli/spans.yaml index 50de0a54cd..ce1a0c31ce 100644 --- a/model/cli/spans.yaml +++ b/model/cli/spans.yaml @@ -1,10 +1,8 @@ groups: - - id: span.cli.internal - type: span - span_kind: internal - stability: development + - id: attributes.cli.common + type: attribute_group brief: > - Describes span of CLI (Command Line Interfaces) programs. + Common CLI attributes. attributes: - ref: process.executable.name requirement_level: required @@ -20,23 +18,32 @@ groups: requirement_level: conditionally_required: if and only if process.exit.code is not 0 + - id: span.cli.internal + type: span + span_kind: internal + stability: development + brief: > + This span describes CLI (Command Line Interfaces) program execution from a callee perspective. + note: | + **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. Refer to + the [Recording Errors](/docs/general/recording-errors.md) document for details on how to record span status. + extends: attributes.cli.common + - id: span.cli.client type: span span_kind: client stability: development 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 + This span describes CLI (Command Line Interfaces) program execution from a caller perspective. + note: | + **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. Refer to + the [Recording Errors](/docs/general/recording-errors.md) document for details on how to record span status. + extends: attributes.cli.common diff --git a/model/database/spans.yaml b/model/database/spans.yaml index 176594fc8a..c2a708251e 100644 --- a/model/database/spans.yaml +++ b/model/database/spans.yaml @@ -105,18 +105,37 @@ groups: - id: span.db.client type: span - stability: development - brief: This span defines the attributes used to perform database client calls. + stability: release_candidate + brief: This span describes database client call. + note: | + It SHOULD cover the duration of the corresponding call as if it was observed by the caller (such as client application). + For example, if a transient issue happened and was retried within this database call, the corresponding span should cover the duration of the logical operation + with all retries. + + **Span name** is covered in the [Name](/docs/database/database-spans.md#name) section. + + **Span kind** SHOULD be `CLIENT`. It MAY be set to `INTERNAL` on spans representing + in-memory database calls. + It's RECOMMENDED to use `CLIENT` kind when database system being instrumented usually + runs in a different process than its client or when database calls happen over + instrumented protocol such as HTTP. + + **Span status** Refer to the [Recording Errors](/docs/general/recording-errors.md) + document for details on how to record span status. Semantic conventions for + individual systems SHOULD specify which values of `db.response.status_code` + classify as errors. span_kind: client extends: trace.db.common.full - id: span.db.mssql.client type: span - stability: development + stability: release_candidate extends: span.db.sql.client span_kind: client brief: > - Attributes for Microsoft SQL Server + Spans representing calls to Microsoft SQL Server adhere to the general [Semantic Conventions for Database Client Spans](database-spans.md). + note: | + `db.system.name` MUST be set to `"microsoft.sql_server"` and SHOULD be provided **at span creation time**. attributes: - ref: db.namespace sampling_relevant: true @@ -150,11 +169,13 @@ groups: - id: span.db.postgresql.client type: span - stability: development + stability: release_candidate extends: span.db.sql.client span_kind: client brief: > - Attributes for PostgreSQL + Spans representing calls to a PostgreSQL database adhere to the general [Semantic Conventions for Database Client Spans](database-spans.md). + note: | + `db.system.name` MUST be set to `"postgresql"` and SHOULD be provided **at span creation time**. attributes: - ref: db.namespace sampling_relevant: true @@ -187,11 +208,13 @@ groups: examples: ["08000", "08P01"] - id: span.db.mysql.client type: span - stability: development + stability: release_candidate extends: span.db.sql.client span_kind: client brief: > - Attributes for MySQL + Spans representing calls to a MySQL Server adhere to the general [Semantic Conventions for Database Client Spans](database-spans.md). + note: | + `db.system.name` MUST be set to `"microsoft.sql_server"` and SHOULD be provided **at span creation time**. attributes: - ref: db.namespace sampling_relevant: true @@ -217,11 +240,13 @@ groups: - id: span.db.mariadb.client type: span - stability: development + stability: release_candidate extends: span.db.sql.client span_kind: client brief: > - Attributes for MariaDB + Spans representing calls to MariaDB adhere to the general [Semantic Conventions for Database Client Spans](/docs/database/README.md). + note: > + `db.system.name` MUST be set to `"mariadb"` and SHOULD be provided **at span creation time**. attributes: - ref: db.namespace sampling_relevant: true @@ -259,7 +284,11 @@ groups: stability: development extends: trace.db.common.query_and_collection brief: > - Attributes for Cassandra + Spans representing calls to a Cassandra database adhere to the general [Semantic Conventions for Database Client Spans](/docs/database/database-spans.md). + note: | + `db.system.name` MUST be set to `"cassandra"` and SHOULD be provided **at span creation time**. + + **Span name** SHOULD follow the general [database span name convention](/docs/database/database-spans.md#name) attributes: - ref: db.namespace sampling_relevant: true @@ -302,7 +331,11 @@ groups: stability: development extends: trace.db.common.minimal brief: > - Attributes for HBase + Spans representing calls to an HBase database adhere to the general [Semantic Conventions for Database Client Spans](/docs/database/database-spans.md). + note: | + `db.system.name` MUST be set to `"hbase"` and SHOULD be provided **at span creation time**. + + **Span name** SHOULD follow the general [database span name convention](/docs/database/database-spans.md#name) attributes: - ref: db.namespace sampling_relevant: true @@ -338,10 +371,14 @@ groups: - id: span.db.couchdb.client type: span span_kind: client - stability: development + stability: release_candidate extends: trace.db.common.minimal brief: > - Attributes for CouchDB + Spans representing calls to CouchDB adhere to the general [Semantic Conventions for Database Client Spans](/docs/database/database-spans.md). + note: | + `db.system.name` MUST be set to `"couchdb"` and SHOULD be provided **at span creation time**. + + **Span name** SHOULD follow the general [database span name convention](/docs/database/database-spans.md#name) attributes: - ref: db.operation.name sampling_relevant: true @@ -376,7 +413,13 @@ groups: span_kind: client extends: trace.db.common.minimal brief: > - Attributes for Redis + Spans representing calls to Redis adhere to the general [Semantic Conventions for Database Client Spans](/docs/database/database-spans.md). + note: | + `db.system.name` MUST be set to `"redis"` and SHOULD be provided **at span creation time**. + + **Span name** SHOULD follow the general [database span name convention](/docs/database/database-spans.md#name) + except that `db.namespace` SHOULD NOT be used in the span name since it is a numeric value that ends up + looking confusing. attributes: - ref: db.namespace sampling_relevant: true @@ -461,7 +504,11 @@ groups: span_kind: client extends: trace.db.common.minimal brief: > - Attributes for MongoDB + Spans representing calls to MongoDB adhere to the general [Semantic Conventions for Database Client Spans](/docs/database/database-spans.md). + note: > + `db.system.name` MUST be set to `"mongodb"` and SHOULD be provided **at span creation time**. + + **Span name** SHOULD follow the general [database span name convention](/docs/database/database-spans.md#name) attributes: - ref: db.operation.name sampling_relevant: true @@ -502,7 +549,12 @@ groups: span_kind: client extends: trace.db.common.minimal brief: > - Attributes for Elasticsearch + Spans representing calls to Elasticsearch adhere to the general [Semantic Conventions for Database Client Spans](/docs/database/database-spans.md). + note: | + `db.system.name` MUST be set to `"elasticsearch"` and SHOULD be provided **at span creation time**. + + **Span name** SHOULD follow the general [database span name convention](/docs/database/database-spans.md#name) + with the endpoint identifier stored in `db.operation.name`, and the index stored in `db.collection.name`. attributes: - ref: http.request.method sampling_relevant: true @@ -574,10 +626,34 @@ groups: - id: span.db.sql.client type: span span_kind: client - stability: development + stability: release_candidate extends: trace.db.common.query brief: > - Attributes for SQL databases + The SQL databases Semantic Conventions describes how common [Database Semantic Conventions](/docs/database/database-spans.md) apply to SQL databases. + note: | + The following database systems (defined in the [`db.system.name`](./database-spans.md#notes-and-well-known-identifiers-for-dbsystemname) set) are known to use SQL as their primary query language: + + - `actian.ingres` + - `cockroachdb` + - `derby` + - `firebirdsql` + - `h2database` + - `hsqldb` + - `ibm.db2` + - `mariadb` + - `microsoft.sql_server` + - `mysql` + - `oracle.db` + - `other_sql` + - `postgresql` + - `sap.maxdb` + - `sqlite` + - `trino` + + Many other database systems support SQL and can be accessed via generic database driver such as JDBC or ODBC. + Instrumentations applied to generic SQL drivers SHOULD adhere to SQL semantic conventions. + + **Span name** SHOULD follow the general [database span name convention](/docs/database/database-spans.md#name) attributes: - ref: db.namespace brief: > @@ -655,7 +731,15 @@ groups: span_kind: client extends: trace.db.common.query_and_collection brief: > - Attributes for Cosmos DB. + Cosmos DB instrumentations include call-level spans that represent logical database + calls and adhere to the general [Semantic Conventions for Database Client Spans](/docs/database/database-spans.md). + note: | + Additional spans representing network calls may also be created depending on the connection mode (Gateway or Direct). + Semantic conventions described in this document apply to the call-level spans only. + + `db.system.name` MUST be set to `"azure.cosmosdb"` and SHOULD be provided **at span creation time**. + + **Span name** SHOULD follow the general [database span name convention](/docs/database/database-spans.md#name) attributes: - ref: azure.client.id - ref: user_agent.original diff --git a/model/faas/spans.yaml b/model/faas/spans.yaml index 199c35f43a..891951b1c8 100644 --- a/model/faas/spans.yaml +++ b/model/faas/spans.yaml @@ -3,9 +3,15 @@ groups: type: attribute_group stability: development brief: > - This semantic convention describes an instance of a function that - runs without provisioning or managing of servers (also known as - serverless functions or Function as a Service (FaaS)) with spans. + This span represents a serverless function (FaaS) execution. + note: | + Span `name` should be set to the function name being executed. + Depending on the value of the `faas.trigger` attribute, additional attributes MUST be set. + + For example, an `http` trigger SHOULD follow the [HTTP Server semantic conventions](/docs/http/http-spans.md#http-server-semantic-conventions). + For more information, refer to the [Function Trigger Type](#function-trigger-type) section. + + If Spans following this convention are produced, a Resource of type `faas` MUST exist following the [Resource semantic convention](../resource/faas.md). attributes: - ref: faas.trigger note: | @@ -26,8 +32,8 @@ groups: span_kind: server stability: development brief: > - Semantic Convention for FaaS triggered as a response to some data - source operation such as a database or filesystem read/write. + This span represents server side if the FaaS invocations triggered in response + response to some data source operation such as a database or filesystem read/write. attributes: - ref: faas.document.collection requirement_level: required @@ -41,7 +47,7 @@ groups: span_kind: server stability: development brief: > - Semantic Convention for FaaS scheduled to be executed regularly. + This span represents server side if the FaaS invocations triggered by a timer. attributes: - ref: faas.time - ref: faas.cron @@ -51,7 +57,7 @@ groups: type: span stability: development brief: > - Describes an incoming FaaS span. + This span represents server (incoming) side of the FaaS invocation. attributes: - ref: faas.coldstart - ref: faas.trigger @@ -72,7 +78,11 @@ groups: type: span stability: development brief: > - Contains additional attributes for outgoing FaaS spans. + This span represents outgoing call to FaaS service. + note: | + The values reported by the client for the attributes listed below SHOULD be equal to + the corresponding [FaaS resource attributes][] and [Cloud resource attributes][], + which the invoked FaaS instance reports about itself, if it's instrumented. attributes: - ref: faas.invoked_name requirement_level: required diff --git a/model/gen-ai/spans.yaml b/model/gen-ai/spans.yaml index ad4c9a125f..6bec32c7b0 100644 --- a/model/gen-ai/spans.yaml +++ b/model/gen-ai/spans.yaml @@ -70,7 +70,16 @@ groups: stability: development span_kind: client brief: > - Describes GenAI operation span. + This span represents client call to Generative AI model or service. + note: | + **Span name** SHOULD be `{gen_ai.operation.name} {gen_ai.request.model}`. + Semantic conventions for individual GenAI systems and frameworks MAY specify different span name format + and MUST follow the overall [guidelines for span names](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.37.0/specification/trace/api.md#span). + + **Span kind** SHOULD be `CLIENT`and MAY be set to `INTERNAL` on spans representing + call to models running in the same process. It's RECOMMENDED to use `CLIENT` kind + when GenAI system being instrumented usually runs in a different process than its + client or when GenAI call happens over instrumented protocol such as HTTP. extends: trace.gen_ai.client.common_attributes attributes: - ref: gen_ai.system @@ -109,7 +118,12 @@ groups: span_kind: client type: span brief: > - Describes an OpenAI operation span. + Semantic Conventions for [OpenAI](https://openai.com/) client spans extend + and override the semantic conventions for [Gen AI Spans](gen-ai-spans.md). + note: | + `gen_ai.system` MUST be set to `"openai"` and SHOULD be provided **at span creation time**. + + **Span name** SHOULD follow the general [GenAI span name convention](/docs/gen-ai/spans.md#span-name). attributes: - ref: gen_ai.request.model requirement_level: required @@ -133,7 +147,12 @@ groups: type: span span_kind: client brief: > - Describes Azure AI Inference span attributes. + Semantic Conventions for [Azure AI Inference](https://learn.microsoft.com/azure/ai-studio/reference/reference-model-inference-api) + client spans extend and override the semantic conventions for [Gen AI Spans](gen-ai-spans.md). + note: | + `gen_ai.system` MUST be set to `"az.ai.inference"` and SHOULD be provided **at span creation time**. + + **Span name** SHOULD follow the general [GenAI span name convention](/docs/gen-ai/spans.md#span-name). attributes: - ref: az.namespace note: > @@ -159,7 +178,8 @@ groups: with remote agent services. note: | The `gen_ai.operation.name` SHOULD be `create_agent`. - The **span name** SHOULD be `create_agent {gen_ai.agent.name}`. + + **Span name** SHOULD be `create_agent {gen_ai.agent.name}`. Semantic conventions for individual GenAI systems and frameworks MAY specify different span name format. extends: trace.gen_ai.client.common_attributes attributes: @@ -195,7 +215,9 @@ groups: brief: Describes tool execution span. note: | `gen_ai.operation.name` SHOULD be `execute_tool`. - Span name SHOULD be `execute_tool {gen_ai.tool.name}`. + + **Span name** SHOULD be `execute_tool {gen_ai.tool.name}`. + GenAI instrumentations that are able to instrument tool execution call SHOULD do so. However, it's common for tools to be executed by the application code. It's recommended for the application developers to follow this semantic conventions for tool invoked diff --git a/model/graphql/spans.yml b/model/graphql/spans.yml index 4efe37e0e2..ea4042a5aa 100644 --- a/model/graphql/spans.yml +++ b/model/graphql/spans.yml @@ -4,8 +4,20 @@ groups: stability: development span_kind: server brief: > - This document defines semantic conventions to apply when instrumenting the GraphQL implementation. They map - GraphQL operations to attributes on a Span. + This span represents incoming operation on GraphQL server implementation. + note: | + **Span name** SHOULD be of the format `{graphql.operation.type}` provided + `graphql.operation.type` is available. If `graphql.operation.type` is not available, + the span SHOULD be named `GraphQL Operation`. + + > **Warning** + > The `graphql.operation.name` value is provided by the client and can have high + > cardinality. Using it in the GraphQL server span name (by default) is + > NOT RECOMMENDED. + > + > Instrumentation MAY provide a configuration option to enable a more descriptive + > span name following `{graphql.operation.type} {graphql.operation.name}` format + > when `graphql.operation.name` is available. attributes: - ref: graphql.operation.name requirement_level: recommended diff --git a/model/http/spans.yaml b/model/http/spans.yaml index 86ee3154c4..9bffaa3c8a 100644 --- a/model/http/spans.yaml +++ b/model/http/spans.yaml @@ -3,8 +3,25 @@ groups: type: span extends: attributes.http.client span_kind: client - brief: 'Semantic Convention for HTTP Client' stability: stable + brief: > + This span represents an outbound HTTP request. + note: | + There are two ways HTTP client spans can be implemented in an instrumentation: + + 1. Instrumentations SHOULD create an HTTP span for each attempt to send an HTTP request over the wire. + In case the request is resent, the resend attempts MUST follow the [HTTP resend spec](#http-request-retries-and-redirects). + In this case, instrumentations SHOULD NOT (also) emit a logical encompassing HTTP client span. + + 2. If for some reason it is not possible to emit a span for each send attempt (because e.g. the instrumented library does not expose hooks that would allow this), + instrumentations MAY create an HTTP span for the top-most operation of the HTTP client. + In this case, the `url.full` MUST be the absolute URL that was originally requested, before any HTTP-redirects that may happen when executing the request. + + **Span name:** refer to the [Span Name](#span-name) section. + + **Span kind** MUST be `SERVER`. + + **Span status:** refer to the [Span Status](#span-status) section. attributes: - ref: http.request.method sampling_relevant: true @@ -52,7 +69,14 @@ groups: type: span extends: attributes.http.server span_kind: server - brief: 'Semantic Convention for HTTP Server' + brief: > + This span represents an inbound HTTP request. + note: | + **Span name:** refer to the [Span Name](#span-name) section. + + **Span kind** MUST be `SERVER`. + + **Span status:** refer to the [Span Status](#span-status) section. stability: stable attributes: - ref: http.request.method diff --git a/model/rpc/spans.yaml b/model/rpc/spans.yaml index 4edbd437f4..d836bb8e0f 100644 --- a/model/rpc/spans.yaml +++ b/model/rpc/spans.yaml @@ -28,7 +28,12 @@ groups: - id: span.rpc.client type: span stability: development - brief: 'This document defines semantic conventions for remote procedure call client spans.' + brief: This span represents an outgoing Remote Procedure (RPC) call. + note: | + Remote procedure calls can only be represented with these semantic conventions, + when the names of the called service and method are known and available. + + **Span name:** refer to the [Span Name](#span-name) section. extends: rpc span_kind: client events: [rpc.message] @@ -44,8 +49,13 @@ groups: stability: development extends: rpc span_kind: server - brief: 'Semantic Convention for RPC server spans' + brief: 'This span represents an incoming Remote Procedure (RPC) call.' events: [rpc.message] + note: | + Remote procedure calls can only be represented with these semantic conventions, + when the names of the called service and method are known and available. + + **Span name:** refer to the [Span Name](#span-name) section. attributes: - ref: client.address requirement_level: recommended diff --git a/templates/registry/markdown/snippet.md.j2 b/templates/registry/markdown/snippet.md.j2 index 6b225c8119..fb660602da 100644 --- a/templates/registry/markdown/snippet.md.j2 +++ b/templates/registry/markdown/snippet.md.j2 @@ -6,7 +6,8 @@ {%- import 'attribute_table.j2' as at -%} {%- import 'metric_table.j2' as mt -%} {%- import 'event_macros.j2' as event -%} -{%- import 'resource_macros.j2' as resource %} +{%- import 'resource_macros.j2' as resource -%} +{%- import 'span_macros.j2' as span %} {% macro generate_event(group) -%} {{ event.header(group) }}{{ generate_attributes(group) }}{{ event.body(group.body) }}{% endmacro -%} @@ -15,6 +16,8 @@ {%- macro generate_metric(group) -%} {{ mt.generate(group) }} {{ generate_attributes(group) }}{% endmacro -%} +{%- macro generate_span(group) -%} +{{ span.header(group) }}{{ generate_attributes(group) }}{% endmacro -%} {%- macro generate_attributes(group) -%} {{ at.generate(group.attributes, tag_filter, attribute_registry_base_url, group.lineage.attributes) }}{% endmacro -%} @@ -24,6 +27,8 @@ {{ generate_resource(group) }} {%- elif group.type == "metric" -%} {{ generate_metric(group) }} +{%- elif group.type == "span" -%} +{{ generate_span(group) }} {%- else -%} {{ generate_attributes(group) -}} {% endif -%} diff --git a/templates/registry/markdown/span_macros.j2 b/templates/registry/markdown/span_macros.j2 new file mode 100644 index 0000000000..17fcdc30de --- /dev/null +++ b/templates/registry/markdown/span_macros.j2 @@ -0,0 +1,17 @@ +{#- Macros for simplifying creating "Span" documentation. -#} +{% import 'stability.j2' as stability %} +{% macro header(span) -%} +**Status:** {{ stability.badge(span.stability, span.deprecated) }} + +{{ span.brief | trim }} +{%- if span.note %} + +{{ span.note | trim }}{% endif %} +{%- if "**Span kind" not in span.note %} + +**Span kind** SHOULD be `{{ span.span_kind | upper }}`.{% endif %} +{%- if "**Span status" not in span.note %} + +**Span status** SHOULD follow [Recording Errors](/docs/general/recording-errors.md) document.{% endif %} + +{% endmacro %} From 4b178586d3d0913d7f29ba0d01efb30b498f9106 Mon Sep 17 00:00:00 2001 From: Liudmila Molkova Date: Sat, 5 Apr 2025 10:23:19 -0700 Subject: [PATCH 2/5] lint --- docs/attributes-registry/db.md | 4 ++-- docs/database/cassandra.md | 8 ++++---- docs/database/cosmosdb.md | 8 ++++---- docs/database/database-metrics.md | 8 ++++---- docs/database/database-spans.md | 8 ++++---- docs/database/elasticsearch.md | 2 +- docs/database/mariadb.md | 8 ++++---- docs/database/mssql.md | 8 ++++---- docs/database/mysql.md | 8 ++++---- docs/database/postgresql.md | 8 ++++---- docs/database/redis.md | 4 ++-- docs/database/sql.md | 12 +++++++----- docs/faas/aws-lambda.md | 2 +- docs/faas/faas-spans.md | 4 ++-- docs/gen-ai/azure-ai-inference.md | 3 ++- docs/gen-ai/openai.md | 2 +- docs/http/http-spans.md | 8 ++++---- docs/rpc/rpc-spans.md | 1 - model/database/registry.yaml | 4 ++-- model/database/spans.yaml | 16 +++++++++------- model/faas/spans.yaml | 4 ++-- model/gen-ai/spans.yaml | 5 +++-- model/http/spans.yaml | 8 ++++---- 23 files changed, 74 insertions(+), 69 deletions(-) diff --git a/docs/attributes-registry/db.md b/docs/attributes-registry/db.md index b8a63e6a63..d1c0fac06e 100644 --- a/docs/attributes-registry/db.md +++ b/docs/attributes-registry/db.md @@ -61,9 +61,9 @@ If `db.query.text` is also captured, then `db.operation.parameter.` SHOULD `db.operation.parameter.` SHOULD NOT be captured on batch operations. **[6] `db.query.summary`:** `db.query.summary` provides static summary of the query text. It describes a class of database queries and is useful as a grouping key, especially when analyzing telemetry for database calls involving complex queries. -Summary may be available to the instrumentation through instrumentation hooks or other means. If it is not available, instrumentations that support query parsing SHOULD generate a summary following [Generating query summary](../database/database-spans.md#generating-a-summary-of-the-query-text) section. +Summary may be available to the instrumentation through instrumentation hooks or other means. If it is not available, instrumentations that support query parsing SHOULD generate a summary following [Generating query summary](/docs/database/database-spans.md#generating-a-summary-of-the-query-text) section. -**[7] `db.query.text`:** For sanitization see [Sanitization of `db.query.text`](../database/database-spans.md#sanitization-of-dbquerytext). +**[7] `db.query.text`:** For sanitization see [Sanitization of `db.query.text`](/docs/database/database-spans.md#sanitization-of-dbquerytext). For batch operations, if the individual operations are known to have the same query text then that query text SHOULD be used, otherwise all of the individual query texts SHOULD be concatenated with separator `; ` or some other database system specific separator if more applicable. Even though parameterized query text can potentially have sensitive data, by using a parameterized query the user is giving a strong signal that any sensitive data will be passed as parameter values, and the benefit to observability of capturing the static part of the query text by default outweighs the risk. diff --git a/docs/database/cassandra.md b/docs/database/cassandra.md index 6e0d3230d3..25143ef8d8 100644 --- a/docs/database/cassandra.md +++ b/docs/database/cassandra.md @@ -102,16 +102,16 @@ Instrumentations SHOULD document how `error.type` is populated. **[11] `db.operation.batch.size`:** Operations are only considered batches when they contain two or more operations, and so `db.operation.batch.size` SHOULD never be `1`. **[12] `db.query.summary`:** `db.query.summary` provides static summary of the query text. It describes a class of database queries and is useful as a grouping key, especially when analyzing telemetry for database calls involving complex queries. -Summary may be available to the instrumentation through instrumentation hooks or other means. If it is not available, instrumentations that support query parsing SHOULD generate a summary following [Generating query summary](../database/database-spans.md#generating-a-summary-of-the-query-text) section. +Summary may be available to the instrumentation through instrumentation hooks or other means. If it is not available, instrumentations that support query parsing SHOULD generate a summary following [Generating query summary](/docs/database/database-spans.md#generating-a-summary-of-the-query-text) section. **[13] `db.query.summary`:** if readily available or if instrumentation supports query summarization. -**[14] `db.query.text`:** For sanitization see [Sanitization of `db.query.text`](../database/database-spans.md#sanitization-of-dbquerytext). +**[14] `db.query.text`:** For sanitization see [Sanitization of `db.query.text`](/docs/database/database-spans.md#sanitization-of-dbquerytext). For batch operations, if the individual operations are known to have the same query text then that query text SHOULD be used, otherwise all of the individual query texts SHOULD be concatenated with separator `; ` or some other database system specific separator if more applicable. Even though parameterized query text can potentially have sensitive data, by using a parameterized query the user is giving a strong signal that any sensitive data will be passed as parameter values, and the benefit to observability of capturing the static part of the query text by default outweighs the risk. -**[15] `db.query.text`:** Non-parameterized query text SHOULD NOT be collected by default unless there is sanitization that excludes sensitive data, e.g. by redacting all literal values present in the query text. See [Sanitization of `db.query.text`](../database/database-spans.md#sanitization-of-dbquerytext). -Parameterized query text SHOULD be collected by default (the query parameter values themselves are opt-in, see [`db.operation.parameter.`](../attributes-registry/db.md)). +**[15] `db.query.text`:** Non-parameterized query text SHOULD NOT be collected by default unless there is sanitization that excludes sensitive data, e.g. by redacting all literal values present in the query text. See [Sanitization of `db.query.text`](/docs/database/database-spans.md#sanitization-of-dbquerytext). +Parameterized query text SHOULD be collected by default (the query parameter values themselves are opt-in, see [`db.operation.parameter.`](/docs/attributes-registry/db.md)). **[16] `network.peer.address`:** If a database operation involved multiple network calls (for example retries), the address of the last contacted node SHOULD be used. diff --git a/docs/database/cosmosdb.md b/docs/database/cosmosdb.md index b9f6c0ed6c..c01d756b99 100644 --- a/docs/database/cosmosdb.md +++ b/docs/database/cosmosdb.md @@ -215,16 +215,16 @@ Instrumentations SHOULD document how `error.type` is populated. **[10] `db.operation.batch.size`:** Operations are only considered batches when they contain two or more operations, and so `db.operation.batch.size` SHOULD never be `1`. **[11] `db.query.summary`:** `db.query.summary` provides static summary of the query text. It describes a class of database queries and is useful as a grouping key, especially when analyzing telemetry for database calls involving complex queries. -Summary may be available to the instrumentation through instrumentation hooks or other means. If it is not available, instrumentations that support query parsing SHOULD generate a summary following [Generating query summary](../database/database-spans.md#generating-a-summary-of-the-query-text) section. +Summary may be available to the instrumentation through instrumentation hooks or other means. If it is not available, instrumentations that support query parsing SHOULD generate a summary following [Generating query summary](/docs/database/database-spans.md#generating-a-summary-of-the-query-text) section. **[12] `db.query.summary`:** if readily available or if instrumentation supports query summarization. -**[13] `db.query.text`:** For sanitization see [Sanitization of `db.query.text`](../database/database-spans.md#sanitization-of-dbquerytext). +**[13] `db.query.text`:** For sanitization see [Sanitization of `db.query.text`](/docs/database/database-spans.md#sanitization-of-dbquerytext). For batch operations, if the individual operations are known to have the same query text then that query text SHOULD be used, otherwise all of the individual query texts SHOULD be concatenated with separator `; ` or some other database system specific separator if more applicable. Even though parameterized query text can potentially have sensitive data, by using a parameterized query the user is giving a strong signal that any sensitive data will be passed as parameter values, and the benefit to observability of capturing the static part of the query text by default outweighs the risk. -**[14] `db.query.text`:** Non-parameterized query text SHOULD NOT be collected by default unless there is sanitization that excludes sensitive data, e.g. by redacting all literal values present in the query text. See [Sanitization of `db.query.text`](../database/database-spans.md#sanitization-of-dbquerytext). -Parameterized query text SHOULD be collected by default (the query parameter values themselves are opt-in, see [`db.operation.parameter.`](../attributes-registry/db.md)). +**[14] `db.query.text`:** Non-parameterized query text SHOULD NOT be collected by default unless there is sanitization that excludes sensitive data, e.g. by redacting all literal values present in the query text. See [Sanitization of `db.query.text`](/docs/database/database-spans.md#sanitization-of-dbquerytext). +Parameterized query text SHOULD be collected by default (the query parameter values themselves are opt-in, see [`db.operation.parameter.`](/docs/attributes-registry/db.md)). **[15] `db.stored_procedure.name`:** It is RECOMMENDED to capture the value as provided by the application without attempting to do any case normalization. diff --git a/docs/database/database-metrics.md b/docs/database/database-metrics.md index fbffd7ddcf..8b9d639d23 100644 --- a/docs/database/database-metrics.md +++ b/docs/database/database-metrics.md @@ -142,7 +142,7 @@ Instrumentations SHOULD document how `error.type` is populated. **[11] `server.port`:** If using a port other than the default port for this DBMS and if `server.address` is set. **[12] `db.query.summary`:** `db.query.summary` provides static summary of the query text. It describes a class of database queries and is useful as a grouping key, especially when analyzing telemetry for database calls involving complex queries. -Summary may be available to the instrumentation through instrumentation hooks or other means. If it is not available, instrumentations that support query parsing SHOULD generate a summary following [Generating query summary](../database/database-spans.md#generating-a-summary-of-the-query-text) section. +Summary may be available to the instrumentation through instrumentation hooks or other means. If it is not available, instrumentations that support query parsing SHOULD generate a summary following [Generating query summary](/docs/database/database-spans.md#generating-a-summary-of-the-query-text) section. **[13] `db.query.summary`:** if readily available or if instrumentation supports query summarization. @@ -159,7 +159,7 @@ If a database operation involved multiple network calls (for example retries), t **[17] `server.address`:** When observed from the client side, and when communicating through an intermediary, `server.address` SHOULD represent the server address behind any intermediaries, for example proxies, if it's available. -**[18] `db.query.text`:** For sanitization see [Sanitization of `db.query.text`](../database/database-spans.md#sanitization-of-dbquerytext). +**[18] `db.query.text`:** For sanitization see [Sanitization of `db.query.text`](/docs/database/database-spans.md#sanitization-of-dbquerytext). For batch operations, if the individual operations are known to have the same query text then that query text SHOULD be used, otherwise all of the individual query texts SHOULD be concatenated with separator `; ` or some other database system specific separator if more applicable. Even though parameterized query text can potentially have sensitive data, by using a parameterized query the user is giving a strong signal that any sensitive data will be passed as parameter values, and the benefit to observability of capturing the static part of the query text by default outweighs the risk. @@ -320,7 +320,7 @@ Instrumentations SHOULD document how `error.type` is populated. **[11] `server.port`:** If using a port other than the default port for this DBMS and if `server.address` is set. **[12] `db.query.summary`:** `db.query.summary` provides static summary of the query text. It describes a class of database queries and is useful as a grouping key, especially when analyzing telemetry for database calls involving complex queries. -Summary may be available to the instrumentation through instrumentation hooks or other means. If it is not available, instrumentations that support query parsing SHOULD generate a summary following [Generating query summary](../database/database-spans.md#generating-a-summary-of-the-query-text) section. +Summary may be available to the instrumentation through instrumentation hooks or other means. If it is not available, instrumentations that support query parsing SHOULD generate a summary following [Generating query summary](/docs/database/database-spans.md#generating-a-summary-of-the-query-text) section. **[13] `db.query.summary`:** if readily available or if instrumentation supports query summarization. @@ -329,7 +329,7 @@ If a database operation involved multiple network calls (for example retries), t **[15] `server.address`:** When observed from the client side, and when communicating through an intermediary, `server.address` SHOULD represent the server address behind any intermediaries, for example proxies, if it's available. -**[16] `db.query.text`:** For sanitization see [Sanitization of `db.query.text`](../database/database-spans.md#sanitization-of-dbquerytext). +**[16] `db.query.text`:** For sanitization see [Sanitization of `db.query.text`](/docs/database/database-spans.md#sanitization-of-dbquerytext). For batch operations, if the individual operations are known to have the same query text then that query text SHOULD be used, otherwise all of the individual query texts SHOULD be concatenated with separator `; ` or some other database system specific separator if more applicable. Even though parameterized query text can potentially have sensitive data, by using a parameterized query the user is giving a strong signal that any sensitive data will be passed as parameter values, and the benefit to observability of capturing the static part of the query text by default outweighs the risk. diff --git a/docs/database/database-spans.md b/docs/database/database-spans.md index d571037242..57db5e0aac 100644 --- a/docs/database/database-spans.md +++ b/docs/database/database-spans.md @@ -167,16 +167,16 @@ Instrumentations SHOULD document how `error.type` is populated. **[12] `db.operation.batch.size`:** Operations are only considered batches when they contain two or more operations, and so `db.operation.batch.size` SHOULD never be `1`. **[13] `db.query.summary`:** `db.query.summary` provides static summary of the query text. It describes a class of database queries and is useful as a grouping key, especially when analyzing telemetry for database calls involving complex queries. -Summary may be available to the instrumentation through instrumentation hooks or other means. If it is not available, instrumentations that support query parsing SHOULD generate a summary following [Generating query summary](../database/database-spans.md#generating-a-summary-of-the-query-text) section. +Summary may be available to the instrumentation through instrumentation hooks or other means. If it is not available, instrumentations that support query parsing SHOULD generate a summary following [Generating query summary](/docs/database/database-spans.md#generating-a-summary-of-the-query-text) section. **[14] `db.query.summary`:** if readily available or if instrumentation supports query summarization. -**[15] `db.query.text`:** For sanitization see [Sanitization of `db.query.text`](../database/database-spans.md#sanitization-of-dbquerytext). +**[15] `db.query.text`:** For sanitization see [Sanitization of `db.query.text`](/docs/database/database-spans.md#sanitization-of-dbquerytext). For batch operations, if the individual operations are known to have the same query text then that query text SHOULD be used, otherwise all of the individual query texts SHOULD be concatenated with separator `; ` or some other database system specific separator if more applicable. Even though parameterized query text can potentially have sensitive data, by using a parameterized query the user is giving a strong signal that any sensitive data will be passed as parameter values, and the benefit to observability of capturing the static part of the query text by default outweighs the risk. -**[16] `db.query.text`:** Non-parameterized query text SHOULD NOT be collected by default unless there is sanitization that excludes sensitive data, e.g. by redacting all literal values present in the query text. See [Sanitization of `db.query.text`](../database/database-spans.md#sanitization-of-dbquerytext). -Parameterized query text SHOULD be collected by default (the query parameter values themselves are opt-in, see [`db.operation.parameter.`](../attributes-registry/db.md)). +**[16] `db.query.text`:** Non-parameterized query text SHOULD NOT be collected by default unless there is sanitization that excludes sensitive data, e.g. by redacting all literal values present in the query text. See [Sanitization of `db.query.text`](/docs/database/database-spans.md#sanitization-of-dbquerytext). +Parameterized query text SHOULD be collected by default (the query parameter values themselves are opt-in, see [`db.operation.parameter.`](/docs/attributes-registry/db.md)). **[17] `network.peer.address`:** Semantic conventions for individual database systems SHOULD document whether `network.peer.*` attributes are applicable. Network peer address and port are useful when the application interacts with individual database nodes directly. If a database operation involved multiple network calls (for example retries), the address of the last contacted node SHOULD be used. diff --git a/docs/database/elasticsearch.md b/docs/database/elasticsearch.md index 5e9ce379b8..4d131d10a0 100644 --- a/docs/database/elasticsearch.md +++ b/docs/database/elasticsearch.md @@ -114,7 +114,7 @@ Instrumentations SHOULD document how `error.type` is populated. **[11] `db.operation.batch.size`:** Operations are only considered batches when they contain two or more operations, and so `db.operation.batch.size` SHOULD never be `1`. -**[12] `db.query.text`:** For sanitization see [Sanitization of `db.query.text`](../database/database-spans.md#sanitization-of-dbquerytext). +**[12] `db.query.text`:** For sanitization see [Sanitization of `db.query.text`](/docs/database/database-spans.md#sanitization-of-dbquerytext). For batch operations, if the individual operations are known to have the same query text then that query text SHOULD be used, otherwise all of the individual query texts SHOULD be concatenated with separator `; ` or some other database system specific separator if more applicable. Even though parameterized query text can potentially have sensitive data, by using a parameterized query the user is giving a strong signal that any sensitive data will be passed as parameter values, and the benefit to observability of capturing the static part of the query text by default outweighs the risk. diff --git a/docs/database/mariadb.md b/docs/database/mariadb.md index a037c80bd1..3eb25f2074 100644 --- a/docs/database/mariadb.md +++ b/docs/database/mariadb.md @@ -71,16 +71,16 @@ Instrumentations SHOULD document how `error.type` is populated. **[6] `db.operation.batch.size`:** Operations are only considered batches when they contain two or more operations, and so `db.operation.batch.size` SHOULD never be `1`. **[7] `db.query.summary`:** `db.query.summary` provides static summary of the query text. It describes a class of database queries and is useful as a grouping key, especially when analyzing telemetry for database calls involving complex queries. -Summary may be available to the instrumentation through instrumentation hooks or other means. If it is not available, instrumentations that support query parsing SHOULD generate a summary following [Generating query summary](../database/database-spans.md#generating-a-summary-of-the-query-text) section. +Summary may be available to the instrumentation through instrumentation hooks or other means. If it is not available, instrumentations that support query parsing SHOULD generate a summary following [Generating query summary](/docs/database/database-spans.md#generating-a-summary-of-the-query-text) section. **[8] `db.query.summary`:** if readily available or if instrumentation supports query summarization. -**[9] `db.query.text`:** For sanitization see [Sanitization of `db.query.text`](../database/database-spans.md#sanitization-of-dbquerytext). +**[9] `db.query.text`:** For sanitization see [Sanitization of `db.query.text`](/docs/database/database-spans.md#sanitization-of-dbquerytext). For batch operations, if the individual operations are known to have the same query text then that query text SHOULD be used, otherwise all of the individual query texts SHOULD be concatenated with separator `; ` or some other database system specific separator if more applicable. Even though parameterized query text can potentially have sensitive data, by using a parameterized query the user is giving a strong signal that any sensitive data will be passed as parameter values, and the benefit to observability of capturing the static part of the query text by default outweighs the risk. -**[10] `db.query.text`:** Non-parameterized query text SHOULD NOT be collected by default unless there is sanitization that excludes sensitive data, e.g. by redacting all literal values present in the query text. See [Sanitization of `db.query.text`](../database/database-spans.md#sanitization-of-dbquerytext). -Parameterized query text SHOULD be collected by default (the query parameter values themselves are opt-in, see [`db.operation.parameter.`](../attributes-registry/db.md)). +**[10] `db.query.text`:** Non-parameterized query text SHOULD NOT be collected by default unless there is sanitization that excludes sensitive data, e.g. by redacting all literal values present in the query text. See [Sanitization of `db.query.text`](/docs/database/database-spans.md#sanitization-of-dbquerytext). +Parameterized query text SHOULD be collected by default (the query parameter values themselves are opt-in, see [`db.operation.parameter.`](/docs/attributes-registry/db.md)). **[11] `db.stored_procedure.name`:** It is RECOMMENDED to capture the value as provided by the application without attempting to do any case normalization. diff --git a/docs/database/mssql.md b/docs/database/mssql.md index a5b39bbddf..871a3c67c1 100644 --- a/docs/database/mssql.md +++ b/docs/database/mssql.md @@ -76,16 +76,16 @@ Instrumentations SHOULD document how `error.type` is populated. **[6] `db.operation.batch.size`:** Operations are only considered batches when they contain two or more operations, and so `db.operation.batch.size` SHOULD never be `1`. **[7] `db.query.summary`:** `db.query.summary` provides static summary of the query text. It describes a class of database queries and is useful as a grouping key, especially when analyzing telemetry for database calls involving complex queries. -Summary may be available to the instrumentation through instrumentation hooks or other means. If it is not available, instrumentations that support query parsing SHOULD generate a summary following [Generating query summary](../database/database-spans.md#generating-a-summary-of-the-query-text) section. +Summary may be available to the instrumentation through instrumentation hooks or other means. If it is not available, instrumentations that support query parsing SHOULD generate a summary following [Generating query summary](/docs/database/database-spans.md#generating-a-summary-of-the-query-text) section. **[8] `db.query.summary`:** if readily available or if instrumentation supports query summarization. -**[9] `db.query.text`:** For sanitization see [Sanitization of `db.query.text`](../database/database-spans.md#sanitization-of-dbquerytext). +**[9] `db.query.text`:** For sanitization see [Sanitization of `db.query.text`](/docs/database/database-spans.md#sanitization-of-dbquerytext). For batch operations, if the individual operations are known to have the same query text then that query text SHOULD be used, otherwise all of the individual query texts SHOULD be concatenated with separator `; ` or some other database system specific separator if more applicable. Even though parameterized query text can potentially have sensitive data, by using a parameterized query the user is giving a strong signal that any sensitive data will be passed as parameter values, and the benefit to observability of capturing the static part of the query text by default outweighs the risk. -**[10] `db.query.text`:** Non-parameterized query text SHOULD NOT be collected by default unless there is sanitization that excludes sensitive data, e.g. by redacting all literal values present in the query text. See [Sanitization of `db.query.text`](../database/database-spans.md#sanitization-of-dbquerytext). -Parameterized query text SHOULD be collected by default (the query parameter values themselves are opt-in, see [`db.operation.parameter.`](../attributes-registry/db.md)). +**[10] `db.query.text`:** Non-parameterized query text SHOULD NOT be collected by default unless there is sanitization that excludes sensitive data, e.g. by redacting all literal values present in the query text. See [Sanitization of `db.query.text`](/docs/database/database-spans.md#sanitization-of-dbquerytext). +Parameterized query text SHOULD be collected by default (the query parameter values themselves are opt-in, see [`db.operation.parameter.`](/docs/attributes-registry/db.md)). **[11] `db.stored_procedure.name`:** It is RECOMMENDED to capture the value as provided by the application without attempting to do any case normalization. diff --git a/docs/database/mysql.md b/docs/database/mysql.md index a6f9e22bf8..a402a85137 100644 --- a/docs/database/mysql.md +++ b/docs/database/mysql.md @@ -71,16 +71,16 @@ Instrumentations SHOULD document how `error.type` is populated. **[6] `db.operation.batch.size`:** Operations are only considered batches when they contain two or more operations, and so `db.operation.batch.size` SHOULD never be `1`. **[7] `db.query.summary`:** `db.query.summary` provides static summary of the query text. It describes a class of database queries and is useful as a grouping key, especially when analyzing telemetry for database calls involving complex queries. -Summary may be available to the instrumentation through instrumentation hooks or other means. If it is not available, instrumentations that support query parsing SHOULD generate a summary following [Generating query summary](../database/database-spans.md#generating-a-summary-of-the-query-text) section. +Summary may be available to the instrumentation through instrumentation hooks or other means. If it is not available, instrumentations that support query parsing SHOULD generate a summary following [Generating query summary](/docs/database/database-spans.md#generating-a-summary-of-the-query-text) section. **[8] `db.query.summary`:** if readily available or if instrumentation supports query summarization. -**[9] `db.query.text`:** For sanitization see [Sanitization of `db.query.text`](../database/database-spans.md#sanitization-of-dbquerytext). +**[9] `db.query.text`:** For sanitization see [Sanitization of `db.query.text`](/docs/database/database-spans.md#sanitization-of-dbquerytext). For batch operations, if the individual operations are known to have the same query text then that query text SHOULD be used, otherwise all of the individual query texts SHOULD be concatenated with separator `; ` or some other database system specific separator if more applicable. Even though parameterized query text can potentially have sensitive data, by using a parameterized query the user is giving a strong signal that any sensitive data will be passed as parameter values, and the benefit to observability of capturing the static part of the query text by default outweighs the risk. -**[10] `db.query.text`:** Non-parameterized query text SHOULD NOT be collected by default unless there is sanitization that excludes sensitive data, e.g. by redacting all literal values present in the query text. See [Sanitization of `db.query.text`](../database/database-spans.md#sanitization-of-dbquerytext). -Parameterized query text SHOULD be collected by default (the query parameter values themselves are opt-in, see [`db.operation.parameter.`](../attributes-registry/db.md)). +**[10] `db.query.text`:** Non-parameterized query text SHOULD NOT be collected by default unless there is sanitization that excludes sensitive data, e.g. by redacting all literal values present in the query text. See [Sanitization of `db.query.text`](/docs/database/database-spans.md#sanitization-of-dbquerytext). +Parameterized query text SHOULD be collected by default (the query parameter values themselves are opt-in, see [`db.operation.parameter.`](/docs/attributes-registry/db.md)). **[11] `db.stored_procedure.name`:** It is RECOMMENDED to capture the value as provided by the application without attempting to do any case normalization. diff --git a/docs/database/postgresql.md b/docs/database/postgresql.md index 3630736b4b..b75e7c096e 100644 --- a/docs/database/postgresql.md +++ b/docs/database/postgresql.md @@ -78,16 +78,16 @@ Instrumentations SHOULD document how `error.type` is populated. **[6] `db.operation.batch.size`:** Operations are only considered batches when they contain two or more operations, and so `db.operation.batch.size` SHOULD never be `1`. **[7] `db.query.summary`:** `db.query.summary` provides static summary of the query text. It describes a class of database queries and is useful as a grouping key, especially when analyzing telemetry for database calls involving complex queries. -Summary may be available to the instrumentation through instrumentation hooks or other means. If it is not available, instrumentations that support query parsing SHOULD generate a summary following [Generating query summary](../database/database-spans.md#generating-a-summary-of-the-query-text) section. +Summary may be available to the instrumentation through instrumentation hooks or other means. If it is not available, instrumentations that support query parsing SHOULD generate a summary following [Generating query summary](/docs/database/database-spans.md#generating-a-summary-of-the-query-text) section. **[8] `db.query.summary`:** if readily available or if instrumentation supports query summarization. -**[9] `db.query.text`:** For sanitization see [Sanitization of `db.query.text`](../database/database-spans.md#sanitization-of-dbquerytext). +**[9] `db.query.text`:** For sanitization see [Sanitization of `db.query.text`](/docs/database/database-spans.md#sanitization-of-dbquerytext). For batch operations, if the individual operations are known to have the same query text then that query text SHOULD be used, otherwise all of the individual query texts SHOULD be concatenated with separator `; ` or some other database system specific separator if more applicable. Even though parameterized query text can potentially have sensitive data, by using a parameterized query the user is giving a strong signal that any sensitive data will be passed as parameter values, and the benefit to observability of capturing the static part of the query text by default outweighs the risk. -**[10] `db.query.text`:** Non-parameterized query text SHOULD NOT be collected by default unless there is sanitization that excludes sensitive data, e.g. by redacting all literal values present in the query text. See [Sanitization of `db.query.text`](../database/database-spans.md#sanitization-of-dbquerytext). -Parameterized query text SHOULD be collected by default (the query parameter values themselves are opt-in, see [`db.operation.parameter.`](../attributes-registry/db.md)). +**[10] `db.query.text`:** Non-parameterized query text SHOULD NOT be collected by default unless there is sanitization that excludes sensitive data, e.g. by redacting all literal values present in the query text. See [Sanitization of `db.query.text`](/docs/database/database-spans.md#sanitization-of-dbquerytext). +Parameterized query text SHOULD be collected by default (the query parameter values themselves are opt-in, see [`db.operation.parameter.`](/docs/attributes-registry/db.md)). **[11] `db.stored_procedure.name`:** It is RECOMMENDED to capture the value as provided by the application without attempting to do any case normalization. diff --git a/docs/database/redis.md b/docs/database/redis.md index 993445ee81..ac71c85e27 100644 --- a/docs/database/redis.md +++ b/docs/database/redis.md @@ -75,8 +75,8 @@ Instrumentations SHOULD document how `error.type` is populated. **[10] `db.query.text`:** For **Redis**, the value provided for `db.query.text` SHOULD correspond to the syntax of the Redis CLI. If, for example, the [`HMSET` command](https://redis.io/docs/latest/commands/hmset) is invoked, `"HMSET myhash field1 'Hello' field2 'World'"` would be a suitable value for `db.query.text`. **[11] `db.query.text`:** Non-parameterized query text SHOULD NOT be collected by default unless there is sanitization that excludes sensitive data, e.g. by redacting all literal values present in the query text. -See [Sanitization of `db.query.text`](../database/database-spans.md#sanitization-of-dbquerytext). -Parameterized query text SHOULD be collected by default (the query parameter values themselves are opt-in, see [`db.operation.parameter.`](../attributes-registry/db.md)). +See [Sanitization of `db.query.text`](/docs/database/database-spans.md#sanitization-of-dbquerytext). +Parameterized query text SHOULD be collected by default (the query parameter values themselves are opt-in, see [`db.operation.parameter.`](/docs/attributes-registry/db.md)). **[12] `db.stored_procedure.name`:** See [FCALL](https://redis.io/docs/latest/commands/fcall/) and [EVALSHA](https://redis.io/docs/latest/commands/evalsha/). diff --git a/docs/database/sql.md b/docs/database/sql.md index 9488bb3ebd..765cfab1ec 100644 --- a/docs/database/sql.md +++ b/docs/database/sql.md @@ -19,7 +19,9 @@ linkTitle: SQL The SQL databases Semantic Conventions describes how common [Database Semantic Conventions](/docs/database/database-spans.md) apply to SQL databases. -The following database systems (defined in the [`db.system.name`](./database-spans.md#notes-and-well-known-identifiers-for-dbsystemname) set) are known to use SQL as their primary query language: +The following database systems (defined in the +[`db.system.name`](/docs/database/database-spans.md#notes-and-well-known-identifiers-for-dbsystemname) set) +are known to use SQL as their primary query language: - `actian.ingres` - `cockroachdb` @@ -126,16 +128,16 @@ Instrumentations SHOULD document how `error.type` is populated. **[6] `db.operation.batch.size`:** Operations are only considered batches when they contain two or more operations, and so `db.operation.batch.size` SHOULD never be `1`. **[7] `db.query.summary`:** `db.query.summary` provides static summary of the query text. It describes a class of database queries and is useful as a grouping key, especially when analyzing telemetry for database calls involving complex queries. -Summary may be available to the instrumentation through instrumentation hooks or other means. If it is not available, instrumentations that support query parsing SHOULD generate a summary following [Generating query summary](../database/database-spans.md#generating-a-summary-of-the-query-text) section. +Summary may be available to the instrumentation through instrumentation hooks or other means. If it is not available, instrumentations that support query parsing SHOULD generate a summary following [Generating query summary](/docs/database/database-spans.md#generating-a-summary-of-the-query-text) section. **[8] `db.query.summary`:** if readily available or if instrumentation supports query summarization. -**[9] `db.query.text`:** For sanitization see [Sanitization of `db.query.text`](../database/database-spans.md#sanitization-of-dbquerytext). +**[9] `db.query.text`:** For sanitization see [Sanitization of `db.query.text`](/docs/database/database-spans.md#sanitization-of-dbquerytext). For batch operations, if the individual operations are known to have the same query text then that query text SHOULD be used, otherwise all of the individual query texts SHOULD be concatenated with separator `; ` or some other database system specific separator if more applicable. Even though parameterized query text can potentially have sensitive data, by using a parameterized query the user is giving a strong signal that any sensitive data will be passed as parameter values, and the benefit to observability of capturing the static part of the query text by default outweighs the risk. -**[10] `db.query.text`:** Non-parameterized query text SHOULD NOT be collected by default unless there is sanitization that excludes sensitive data, e.g. by redacting all literal values present in the query text. See [Sanitization of `db.query.text`](../database/database-spans.md#sanitization-of-dbquerytext). -Parameterized query text SHOULD be collected by default (the query parameter values themselves are opt-in, see [`db.operation.parameter.`](../attributes-registry/db.md)). +**[10] `db.query.text`:** Non-parameterized query text SHOULD NOT be collected by default unless there is sanitization that excludes sensitive data, e.g. by redacting all literal values present in the query text. See [Sanitization of `db.query.text`](/docs/database/database-spans.md#sanitization-of-dbquerytext). +Parameterized query text SHOULD be collected by default (the query parameter values themselves are opt-in, see [`db.operation.parameter.`](/docs/attributes-registry/db.md)). **[11] `db.stored_procedure.name`:** It is RECOMMENDED to capture the value as provided by the application without attempting to do any case normalization. diff --git a/docs/faas/aws-lambda.md b/docs/faas/aws-lambda.md index 7b8331105e..05b0d17e21 100644 --- a/docs/faas/aws-lambda.md +++ b/docs/faas/aws-lambda.md @@ -139,7 +139,7 @@ configuration for a REST API, in which case only a deserialized body payload is gateway is configured to proxy to the Lambda function, the instrumented request handler will have access to all the information about the HTTP request in the form of an API Gateway Proxy Request Event. -The Lambda span name and the [`http.route` span attribute](/docs/http/http-spans.md#http-server-semantic-conventions) SHOULD +The Lambda span name and the [`http.route` span attribute](/docs/http/http-spans.md#http-server-span) SHOULD be set to the [resource property][] from the proxy request event, which corresponds to the user configured HTTP route instead of the function name. diff --git a/docs/faas/faas-spans.md b/docs/faas/faas-spans.md index 110c48a8b2..a2d82d449f 100644 --- a/docs/faas/faas-spans.md +++ b/docs/faas/faas-spans.md @@ -32,7 +32,7 @@ See also the [additional instructions for instrumenting AWS Lambda](aws-lambda.m ## General attributes -Span `name` should be set to the function name being executed. Depending on the value of the `faas.trigger` attribute, additional attributes MUST be set. For example, an `http` trigger SHOULD follow the [HTTP Server semantic conventions](/docs/http/http-spans.md#http-server-semantic-conventions). For more information, refer to the [Function Trigger Type](#function-trigger-type) section. +Span `name` should be set to the function name being executed. Depending on the value of the `faas.trigger` attribute, additional attributes MUST be set. For example, an `http` trigger SHOULD follow the [HTTP Server semantic conventions](/docs/http/http-spans.md#http-server-span). For more information, refer to the [Function Trigger Type](#function-trigger-type) section. Refer to the [Recording Errors](/docs/general/recording-errors.md) document for details on how to record span status. @@ -294,7 +294,7 @@ This span represents server side if the FaaS invocations triggered in response r ### HTTP -The function responsibility is to provide an answer to an inbound HTTP request. The `faas` span SHOULD follow the recommendations described in the [HTTP Server semantic conventions](/docs/http/http-spans.md#http-server-semantic-conventions). +The function responsibility is to provide an answer to an inbound HTTP request. The `faas` span SHOULD follow the recommendations described in the [HTTP Server semantic conventions](/docs/http/http-spans.md#http-server-span). ### PubSub diff --git a/docs/gen-ai/azure-ai-inference.md b/docs/gen-ai/azure-ai-inference.md index 9d9e575d32..06946a6728 100644 --- a/docs/gen-ai/azure-ai-inference.md +++ b/docs/gen-ai/azure-ai-inference.md @@ -23,7 +23,8 @@ Semantic Conventions for [Azure AI Inference](https://learn.microsoft.com/azure/ `gen_ai.system` MUST be set to `"az.ai.inference"` and SHOULD be provided **at span creation time**. -**Span name** SHOULD follow the general [GenAI span name convention](/docs/gen-ai/spans.md#span-name). +**Span name** SHOULD be `{gen_ai.operation.name} {gen_ai.request.model}` when the +model name is available and `{gen_ai.operation.name}` otherwise. **Span kind** SHOULD be `CLIENT`. diff --git a/docs/gen-ai/openai.md b/docs/gen-ai/openai.md index 972a99e96f..388473d1ea 100644 --- a/docs/gen-ai/openai.md +++ b/docs/gen-ai/openai.md @@ -32,7 +32,7 @@ Semantic Conventions for [OpenAI](https://openai.com/) client spans extend and o `gen_ai.system` MUST be set to `"openai"` and SHOULD be provided **at span creation time**. -**Span name** SHOULD follow the general [GenAI span name convention](/docs/gen-ai/spans.md#span-name). +**Span name** SHOULD be `{gen_ai.operation.name} {gen_ai.request.model}`. **Span kind** SHOULD be `CLIENT`. diff --git a/docs/http/http-spans.md b/docs/http/http-spans.md index 783560e474..cf27fc10d7 100644 --- a/docs/http/http-spans.md +++ b/docs/http/http-spans.md @@ -138,11 +138,11 @@ There are two ways HTTP client spans can be implemented in an instrumentation: instrumentations MAY create an HTTP span for the top-most operation of the HTTP client. In this case, the `url.full` MUST be the absolute URL that was originally requested, before any HTTP-redirects that may happen when executing the request. -**Span name:** refer to the [Span Name](#span-name) section. +**Span name:** refer to the [Span Name](/docs/http/http-spans.md#name) section. **Span kind** MUST be `SERVER`. -**Span status:** refer to the [Span Status](#span-status) section. +**Span status:** refer to the [Span Status](/docs/http/http-spans.md#status) section. | Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | |---|---|---|---|---|---| @@ -400,11 +400,11 @@ Application developers MAY overwrite potentially inaccurate values of `server.*` This span represents an inbound HTTP request. -**Span name:** refer to the [Span Name](#span-name) section. +**Span name:** refer to the [Span Name](/docs/http/http-spans.md#name) section. **Span kind** MUST be `SERVER`. -**Span status:** refer to the [Span Status](#span-status) section. +**Span status:** refer to the [Span Status](/docs/http/http-spans.md#status) section. | Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | |---|---|---|---|---|---| diff --git a/docs/rpc/rpc-spans.md b/docs/rpc/rpc-spans.md index b6812a56ac..c195a7ba92 100644 --- a/docs/rpc/rpc-spans.md +++ b/docs/rpc/rpc-spans.md @@ -71,7 +71,6 @@ Examples of span names: `MyServiceReference.ICalculator/Add` reported by the client for .NET WCF calls - `MyServiceWithNoPackage/theMethod` - ### Service name On the server process receiving and handling the remote procedure call, the service name provided in `rpc.service` does not necessarily have to match the [`service.name`][] resource attribute. diff --git a/model/database/registry.yaml b/model/database/registry.yaml index 06ff639868..8b0253b8d6 100644 --- a/model/database/registry.yaml +++ b/model/database/registry.yaml @@ -61,7 +61,7 @@ groups: brief: > The database query being executed. note: > - For sanitization see [Sanitization of `db.query.text`](../database/database-spans.md#sanitization-of-dbquerytext). + For sanitization see [Sanitization of `db.query.text`](/docs/database/database-spans.md#sanitization-of-dbquerytext). For batch operations, if the individual operations are known to have the same query text then that query text SHOULD be used, otherwise all of the individual query texts SHOULD be concatenated @@ -103,7 +103,7 @@ groups: Summary may be available to the instrumentation through instrumentation hooks or other means. If it is not available, instrumentations that support query parsing SHOULD generate a summary following - [Generating query summary](../database/database-spans.md#generating-a-summary-of-the-query-text) + [Generating query summary](/docs/database/database-spans.md#generating-a-summary-of-the-query-text) section. examples: [ diff --git a/model/database/spans.yaml b/model/database/spans.yaml index c2a708251e..ab7ed1d22d 100644 --- a/model/database/spans.yaml +++ b/model/database/spans.yaml @@ -36,11 +36,11 @@ groups: recommended: > Non-parameterized query text SHOULD NOT be collected by default unless there is sanitization that excludes sensitive data, e.g. by redacting all literal values present in the query text. - See [Sanitization of `db.query.text`](../database/database-spans.md#sanitization-of-dbquerytext). + See [Sanitization of `db.query.text`](/docs/database/database-spans.md#sanitization-of-dbquerytext). Parameterized query text SHOULD be collected by default (the query parameter values themselves are opt-in, - see [`db.operation.parameter.`](../attributes-registry/db.md)). + see [`db.operation.parameter.`](/docs/attributes-registry/db.md)). - ref: db.query.summary sampling_relevant: true - ref: db.operation.parameter @@ -67,11 +67,11 @@ groups: recommended: > Non-parameterized query text SHOULD NOT be collected by default unless there is sanitization that excludes sensitive data, e.g. by redacting all literal values present in the query text. - See [Sanitization of `db.query.text`](../database/database-spans.md#sanitization-of-dbquerytext). + See [Sanitization of `db.query.text`](/docs/database/database-spans.md#sanitization-of-dbquerytext). Parameterized query text SHOULD be collected by default (the query parameter values themselves are opt-in, - see [`db.operation.parameter.`](../attributes-registry/db.md)). + see [`db.operation.parameter.`](/docs/attributes-registry/db.md)). - ref: db.query.summary sampling_relevant: true - ref: db.operation.parameter @@ -459,11 +459,11 @@ groups: Non-parameterized query text SHOULD NOT be collected by default unless there is sanitization that excludes sensitive data, e.g. by redacting all literal values present in the query text. - See [Sanitization of `db.query.text`](../database/database-spans.md#sanitization-of-dbquerytext). + See [Sanitization of `db.query.text`](/docs/database/database-spans.md#sanitization-of-dbquerytext). Parameterized query text SHOULD be collected by default (the query parameter values themselves are opt-in, - see [`db.operation.parameter.`](../attributes-registry/db.md)). + see [`db.operation.parameter.`](/docs/attributes-registry/db.md)). note: > For **Redis**, the value provided for `db.query.text` SHOULD correspond to the syntax of the Redis CLI. If, for example, the [`HMSET` command](https://redis.io/docs/latest/commands/hmset) is invoked, `"HMSET myhash field1 'Hello' field2 'World'"` would be a suitable value for `db.query.text`. @@ -631,7 +631,9 @@ groups: brief: > The SQL databases Semantic Conventions describes how common [Database Semantic Conventions](/docs/database/database-spans.md) apply to SQL databases. note: | - The following database systems (defined in the [`db.system.name`](./database-spans.md#notes-and-well-known-identifiers-for-dbsystemname) set) are known to use SQL as their primary query language: + The following database systems (defined in the + [`db.system.name`](/docs/database/database-spans.md#notes-and-well-known-identifiers-for-dbsystemname) set) + are known to use SQL as their primary query language: - `actian.ingres` - `cockroachdb` diff --git a/model/faas/spans.yaml b/model/faas/spans.yaml index 891951b1c8..9534ab47fd 100644 --- a/model/faas/spans.yaml +++ b/model/faas/spans.yaml @@ -8,10 +8,10 @@ groups: Span `name` should be set to the function name being executed. Depending on the value of the `faas.trigger` attribute, additional attributes MUST be set. - For example, an `http` trigger SHOULD follow the [HTTP Server semantic conventions](/docs/http/http-spans.md#http-server-semantic-conventions). + For example, an `http` trigger SHOULD follow the [HTTP Server semantic conventions](/docs/http/http-spans.md#http-server-span). For more information, refer to the [Function Trigger Type](#function-trigger-type) section. - If Spans following this convention are produced, a Resource of type `faas` MUST exist following the [Resource semantic convention](../resource/faas.md). + If Spans following this convention are produced, a Resource of type `faas` MUST exist following the [Resource semantic convention](/docs/resource/faas.md). attributes: - ref: faas.trigger note: | diff --git a/model/gen-ai/spans.yaml b/model/gen-ai/spans.yaml index 6bec32c7b0..061e7496d4 100644 --- a/model/gen-ai/spans.yaml +++ b/model/gen-ai/spans.yaml @@ -123,7 +123,7 @@ groups: note: | `gen_ai.system` MUST be set to `"openai"` and SHOULD be provided **at span creation time**. - **Span name** SHOULD follow the general [GenAI span name convention](/docs/gen-ai/spans.md#span-name). + **Span name** SHOULD be `{gen_ai.operation.name} {gen_ai.request.model}`. attributes: - ref: gen_ai.request.model requirement_level: required @@ -152,7 +152,8 @@ groups: note: | `gen_ai.system` MUST be set to `"az.ai.inference"` and SHOULD be provided **at span creation time**. - **Span name** SHOULD follow the general [GenAI span name convention](/docs/gen-ai/spans.md#span-name). + **Span name** SHOULD be `{gen_ai.operation.name} {gen_ai.request.model}` when the + model name is available and `{gen_ai.operation.name}` otherwise. attributes: - ref: az.namespace note: > diff --git a/model/http/spans.yaml b/model/http/spans.yaml index 9bffaa3c8a..3265575d60 100644 --- a/model/http/spans.yaml +++ b/model/http/spans.yaml @@ -17,11 +17,11 @@ groups: instrumentations MAY create an HTTP span for the top-most operation of the HTTP client. In this case, the `url.full` MUST be the absolute URL that was originally requested, before any HTTP-redirects that may happen when executing the request. - **Span name:** refer to the [Span Name](#span-name) section. + **Span name:** refer to the [Span Name](/docs/http/http-spans.md#name) section. **Span kind** MUST be `SERVER`. - **Span status:** refer to the [Span Status](#span-status) section. + **Span status:** refer to the [Span Status](/docs/http/http-spans.md#status) section. attributes: - ref: http.request.method sampling_relevant: true @@ -72,11 +72,11 @@ groups: brief: > This span represents an inbound HTTP request. note: | - **Span name:** refer to the [Span Name](#span-name) section. + **Span name:** refer to the [Span Name](/docs/http/http-spans.md#name) section. **Span kind** MUST be `SERVER`. - **Span status:** refer to the [Span Status](#span-status) section. + **Span status:** refer to the [Span Status](/docs/http/http-spans.md#status) section. stability: stable attributes: - ref: http.request.method From 942e72444e662c9334f732afa8d5e44b70c864ce Mon Sep 17 00:00:00 2001 From: Liudmila Molkova Date: Mon, 7 Apr 2025 15:00:35 -0700 Subject: [PATCH 3/5] address feedback: trivial part --- docs/cloud-providers/aws-sdk.md | 4 +- docs/database/cassandra.md | 2 +- docs/database/cosmosdb.md | 2 +- docs/database/couchdb.md | 4 +- docs/database/dynamodb.md | 52 +++++++++++----------- docs/database/elasticsearch.md | 2 +- docs/database/hbase.md | 2 +- docs/database/mariadb.md | 2 +- docs/database/mongodb.md | 2 +- docs/database/mssql.md | 2 +- docs/database/mysql.md | 2 +- docs/database/postgresql.md | 2 +- docs/database/redis.md | 2 +- docs/database/sql.md | 2 +- docs/faas/aws-lambda.md | 2 +- docs/faas/faas-spans.md | 10 ++--- docs/gen-ai/azure-ai-inference.md | 2 +- docs/gen-ai/gen-ai-agent-spans.md | 2 +- docs/gen-ai/gen-ai-spans.md | 12 ++--- docs/gen-ai/openai.md | 2 +- docs/graphql/graphql-spans.md | 4 +- docs/object-stores/s3.md | 2 +- docs/rpc/rpc-spans.md | 14 +++--- model/aws/sdk-spans.yaml | 28 ++++++------ model/database/spans.yaml | 2 +- model/faas/spans.yaml | 2 +- model/gen-ai/spans.yaml | 8 ++-- model/graphql/spans.yml | 2 +- model/rpc/spans.yaml | 10 +++-- templates/registry/markdown/span_macros.j2 | 2 +- 30 files changed, 95 insertions(+), 91 deletions(-) diff --git a/docs/cloud-providers/aws-sdk.md b/docs/cloud-providers/aws-sdk.md index 04ec5b1f89..4ac7f23d8f 100644 --- a/docs/cloud-providers/aws-sdk.md +++ b/docs/cloud-providers/aws-sdk.md @@ -22,7 +22,7 @@ See [compatibility](../non-normative/compatibility/aws.md#context-propagation). **Status:** ![Development](https://img.shields.io/badge/-development-blue) -This span describes AWS SDK client call. +This span describes an AWS SDK client call. **Span name** MUST be of the format `Service.Operation` as per the AWS HTTP API, e.g., `DynamoDB.GetItem`, `S3.ListBuckets`. This is @@ -36,7 +36,7 @@ interesting conventions are found. **Span kind** SHOULD be `CLIENT`. -**Span status** SHOULD follow [Recording Errors](/docs/general/recording-errors.md) document. +**Span status** SHOULD follow the [Recording Errors](/docs/general/recording-errors.md) document. | Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | |---|---|---|---|---|---| diff --git a/docs/database/cassandra.md b/docs/database/cassandra.md index 25143ef8d8..4c17a54604 100644 --- a/docs/database/cassandra.md +++ b/docs/database/cassandra.md @@ -34,7 +34,7 @@ Spans representing calls to a Cassandra database adhere to the general [Semantic **Span kind** SHOULD be `CLIENT`. -**Span status** SHOULD follow [Recording Errors](/docs/general/recording-errors.md) document. +**Span status** SHOULD follow the [Recording Errors](/docs/general/recording-errors.md) document. | Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | |---|---|---|---|---|---| diff --git a/docs/database/cosmosdb.md b/docs/database/cosmosdb.md index c01d756b99..e28ed4595f 100644 --- a/docs/database/cosmosdb.md +++ b/docs/database/cosmosdb.md @@ -43,7 +43,7 @@ Semantic conventions described in this document apply to the call-level spans on **Span kind** SHOULD be `CLIENT`. -**Span status** SHOULD follow [Recording Errors](/docs/general/recording-errors.md) document. +**Span status** SHOULD follow the [Recording Errors](/docs/general/recording-errors.md) document. | Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | |---|---|---|---|---|---| diff --git a/docs/database/couchdb.md b/docs/database/couchdb.md index 40569b5509..5e65ec4df5 100644 --- a/docs/database/couchdb.md +++ b/docs/database/couchdb.md @@ -30,7 +30,7 @@ The following table outlines the span attributes applicable to CouchDB. -**Status:** ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) +**Status:** ![Development](https://img.shields.io/badge/-development-blue) Spans representing calls to CouchDB adhere to the general [Semantic Conventions for Database Client Spans](/docs/database/database-spans.md). @@ -40,7 +40,7 @@ Spans representing calls to CouchDB adhere to the general [Semantic Conventions **Span kind** SHOULD be `CLIENT`. -**Span status** SHOULD follow [Recording Errors](/docs/general/recording-errors.md) document. +**Span status** SHOULD follow the [Recording Errors](/docs/general/recording-errors.md) document. | Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | |---|---|---|---|---|---| diff --git a/docs/database/dynamodb.md b/docs/database/dynamodb.md index d86c58c6bd..6757204994 100644 --- a/docs/database/dynamodb.md +++ b/docs/database/dynamodb.md @@ -44,13 +44,13 @@ Spans representing calls to AWS DynamoDB adhere to the general [Semantic Convent **Status:** ![Development](https://img.shields.io/badge/-development-blue) -This span represents `DynamoDB.BatchGetItem` call. +This span represents a `DynamoDB.BatchGetItem` call. `db.system.name` MUST be set to `"aws.dynamodb"` and SHOULD be provided **at span creation time**. **Span kind** SHOULD be `CLIENT`. -**Span status** SHOULD follow [Recording Errors](/docs/general/recording-errors.md) document. +**Span status** SHOULD follow the [Recording Errors](/docs/general/recording-errors.md) document. | Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | |---|---|---|---|---|---| @@ -94,13 +94,13 @@ This span represents `DynamoDB.BatchGetItem` call. **Status:** ![Development](https://img.shields.io/badge/-development-blue) -This span represents `DynamoDB.BatchWriteItem` call. +This span represents a `DynamoDB.BatchWriteItem` call. `db.system.name` MUST be set to `"aws.dynamodb"` and SHOULD be provided **at span creation time**. **Span kind** SHOULD be `CLIENT`. -**Span status** SHOULD follow [Recording Errors](/docs/general/recording-errors.md) document. +**Span status** SHOULD follow the [Recording Errors](/docs/general/recording-errors.md) document. | Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | |---|---|---|---|---|---| @@ -145,13 +145,13 @@ This span represents `DynamoDB.BatchWriteItem` call. **Status:** ![Development](https://img.shields.io/badge/-development-blue) -This span represents `DynamoDB.CreateTable` call. +This span represents a `DynamoDB.CreateTable` call. `db.system.name` MUST be set to `"aws.dynamodb"` and SHOULD be provided **at span creation time**. **Span kind** SHOULD be `CLIENT`. -**Span status** SHOULD follow [Recording Errors](/docs/general/recording-errors.md) document. +**Span status** SHOULD follow the [Recording Errors](/docs/general/recording-errors.md) document. | Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | |---|---|---|---|---|---| @@ -200,13 +200,13 @@ This span represents `DynamoDB.CreateTable` call. **Status:** ![Development](https://img.shields.io/badge/-development-blue) -This span represents `DynamoDB.DeleteItem` call. +This span represents a `DynamoDB.DeleteItem` call. `db.system.name` MUST be set to `"aws.dynamodb"` and SHOULD be provided **at span creation time**. **Span kind** SHOULD be `CLIENT`. -**Span status** SHOULD follow [Recording Errors](/docs/general/recording-errors.md) document. +**Span status** SHOULD follow the [Recording Errors](/docs/general/recording-errors.md) document. | Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | |---|---|---|---|---|---| @@ -251,13 +251,13 @@ This span represents `DynamoDB.DeleteItem` call. **Status:** ![Development](https://img.shields.io/badge/-development-blue) -This span represents `DynamoDB.DeleteTable` call. +This span represents a `DynamoDB.DeleteTable` call. `db.system.name` MUST be set to `"aws.dynamodb"` and SHOULD be provided **at span creation time**. **Span kind** SHOULD be `CLIENT`. -**Span status** SHOULD follow [Recording Errors](/docs/general/recording-errors.md) document. +**Span status** SHOULD follow the [Recording Errors](/docs/general/recording-errors.md) document. | Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | |---|---|---|---|---|---| @@ -300,13 +300,13 @@ This span represents `DynamoDB.DeleteTable` call. **Status:** ![Development](https://img.shields.io/badge/-development-blue) -This span represents `DynamoDB.DescribeTable` call. +This span represents a `DynamoDB.DescribeTable` call. `db.system.name` MUST be set to `"aws.dynamodb"` and SHOULD be provided **at span creation time**. **Span kind** SHOULD be `CLIENT`. -**Span status** SHOULD follow [Recording Errors](/docs/general/recording-errors.md) document. +**Span status** SHOULD follow the [Recording Errors](/docs/general/recording-errors.md) document. | Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | |---|---|---|---|---|---| @@ -349,13 +349,13 @@ This span represents `DynamoDB.DescribeTable` call. **Status:** ![Development](https://img.shields.io/badge/-development-blue) -This span represents `DynamoDB.GetItem` call. +This span represents a `DynamoDB.GetItem` call. `db.system.name` MUST be set to `"aws.dynamodb"` and SHOULD be provided **at span creation time**. **Span kind** SHOULD be `CLIENT`. -**Span status** SHOULD follow [Recording Errors](/docs/general/recording-errors.md) document. +**Span status** SHOULD follow the [Recording Errors](/docs/general/recording-errors.md) document. | Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | |---|---|---|---|---|---| @@ -401,13 +401,13 @@ This span represents `DynamoDB.GetItem` call. **Status:** ![Development](https://img.shields.io/badge/-development-blue) -This span represents `DynamoDB.ListTables` call. +This span represents a `DynamoDB.ListTables` call. `db.system.name` MUST be set to `"aws.dynamodb"` and SHOULD be provided **at span creation time**. **Span kind** SHOULD be `CLIENT`. -**Span status** SHOULD follow [Recording Errors](/docs/general/recording-errors.md) document. +**Span status** SHOULD follow the [Recording Errors](/docs/general/recording-errors.md) document. | Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | |---|---|---|---|---|---| @@ -452,13 +452,13 @@ This span represents `DynamoDB.ListTables` call. **Status:** ![Development](https://img.shields.io/badge/-development-blue) -This span represents `DynamoDB.PutItem` call. +This span represents a `DynamoDB.PutItem` call. `db.system.name` MUST be set to `"aws.dynamodb"` and SHOULD be provided **at span creation time**. **Span kind** SHOULD be `CLIENT`. -**Span status** SHOULD follow [Recording Errors](/docs/general/recording-errors.md) document. +**Span status** SHOULD follow the [Recording Errors](/docs/general/recording-errors.md) document. | Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | |---|---|---|---|---|---| @@ -503,13 +503,13 @@ This span represents `DynamoDB.PutItem` call. **Status:** ![Development](https://img.shields.io/badge/-development-blue) -This span represents `DynamoDB.Query` call. +This span represents a `DynamoDB.Query` call. `db.system.name` MUST be set to `"aws.dynamodb"` and SHOULD be provided **at span creation time**. **Span kind** SHOULD be `CLIENT`. -**Span status** SHOULD follow [Recording Errors](/docs/general/recording-errors.md) document. +**Span status** SHOULD follow the [Recording Errors](/docs/general/recording-errors.md) document. | Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | |---|---|---|---|---|---| @@ -560,13 +560,13 @@ This span represents `DynamoDB.Query` call. **Status:** ![Development](https://img.shields.io/badge/-development-blue) -This span represents `DynamoDB.Scan` call. +This span represents a `DynamoDB.Scan` call. `db.system.name` MUST be set to `"aws.dynamodb"` and SHOULD be provided **at span creation time**. **Span kind** SHOULD be `CLIENT`. -**Span status** SHOULD follow [Recording Errors](/docs/general/recording-errors.md) document. +**Span status** SHOULD follow the [Recording Errors](/docs/general/recording-errors.md) document. | Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | |---|---|---|---|---|---| @@ -620,13 +620,13 @@ This span represents `DynamoDB.Scan` call. **Status:** ![Development](https://img.shields.io/badge/-development-blue) -This span represents `DynamoDB.UpdateItem` call. +This span represents a `DynamoDB.UpdateItem` call. `db.system.name` MUST be set to `"aws.dynamodb"` and SHOULD be provided **at span creation time**. **Span kind** SHOULD be `CLIENT`. -**Span status** SHOULD follow [Recording Errors](/docs/general/recording-errors.md) document. +**Span status** SHOULD follow the [Recording Errors](/docs/general/recording-errors.md) document. | Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | |---|---|---|---|---|---| @@ -671,13 +671,13 @@ This span represents `DynamoDB.UpdateItem` call. **Status:** ![Development](https://img.shields.io/badge/-development-blue) -This span represents `DynamoDB.UpdateTable` call. +This span represents a `DynamoDB.UpdateTable` call. `db.system.name` MUST be set to `"aws.dynamodb"` and SHOULD be provided **at span creation time**. **Span kind** SHOULD be `CLIENT`. -**Span status** SHOULD follow [Recording Errors](/docs/general/recording-errors.md) document. +**Span status** SHOULD follow the [Recording Errors](/docs/general/recording-errors.md) document. | Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | |---|---|---|---|---|---| diff --git a/docs/database/elasticsearch.md b/docs/database/elasticsearch.md index 4d131d10a0..1a352e0bc3 100644 --- a/docs/database/elasticsearch.md +++ b/docs/database/elasticsearch.md @@ -36,7 +36,7 @@ with the endpoint identifier stored in `db.operation.name`, and the index stored **Span kind** SHOULD be `CLIENT`. -**Span status** SHOULD follow [Recording Errors](/docs/general/recording-errors.md) document. +**Span status** SHOULD follow the [Recording Errors](/docs/general/recording-errors.md) document. | Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | |---|---|---|---|---|---| diff --git a/docs/database/hbase.md b/docs/database/hbase.md index 6d898c6362..229b36e986 100644 --- a/docs/database/hbase.md +++ b/docs/database/hbase.md @@ -34,7 +34,7 @@ Spans representing calls to an HBase database adhere to the general [Semantic Co **Span kind** SHOULD be `CLIENT`. -**Span status** SHOULD follow [Recording Errors](/docs/general/recording-errors.md) document. +**Span status** SHOULD follow the [Recording Errors](/docs/general/recording-errors.md) document. | Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | |---|---|---|---|---|---| diff --git a/docs/database/mariadb.md b/docs/database/mariadb.md index 3eb25f2074..17d23d2eae 100644 --- a/docs/database/mariadb.md +++ b/docs/database/mariadb.md @@ -30,7 +30,7 @@ Spans representing calls to MariaDB adhere to the general [Semantic Conventions **Span kind** SHOULD be `CLIENT`. -**Span status** SHOULD follow [Recording Errors](/docs/general/recording-errors.md) document. +**Span status** SHOULD follow the [Recording Errors](/docs/general/recording-errors.md) document. | Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | |---|---|---|---|---|---| diff --git a/docs/database/mongodb.md b/docs/database/mongodb.md index 9a5b909d98..1ad37d67d5 100644 --- a/docs/database/mongodb.md +++ b/docs/database/mongodb.md @@ -34,7 +34,7 @@ Spans representing calls to MongoDB adhere to the general [Semantic Conventions **Span kind** SHOULD be `CLIENT`. -**Span status** SHOULD follow [Recording Errors](/docs/general/recording-errors.md) document. +**Span status** SHOULD follow the [Recording Errors](/docs/general/recording-errors.md) document. | Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | |---|---|---|---|---|---| diff --git a/docs/database/mssql.md b/docs/database/mssql.md index 871a3c67c1..6ce4ea15aa 100644 --- a/docs/database/mssql.md +++ b/docs/database/mssql.md @@ -32,7 +32,7 @@ Spans representing calls to Microsoft SQL Server adhere to the general [Semantic **Span kind** SHOULD be `CLIENT`. -**Span status** SHOULD follow [Recording Errors](/docs/general/recording-errors.md) document. +**Span status** SHOULD follow the [Recording Errors](/docs/general/recording-errors.md) document. | Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | |---|---|---|---|---|---| diff --git a/docs/database/mysql.md b/docs/database/mysql.md index a402a85137..4507570c3f 100644 --- a/docs/database/mysql.md +++ b/docs/database/mysql.md @@ -32,7 +32,7 @@ Spans representing calls to a MySQL Server adhere to the general [Semantic Conve **Span kind** SHOULD be `CLIENT`. -**Span status** SHOULD follow [Recording Errors](/docs/general/recording-errors.md) document. +**Span status** SHOULD follow the [Recording Errors](/docs/general/recording-errors.md) document. | Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | |---|---|---|---|---|---| diff --git a/docs/database/postgresql.md b/docs/database/postgresql.md index b75e7c096e..85d520ae51 100644 --- a/docs/database/postgresql.md +++ b/docs/database/postgresql.md @@ -32,7 +32,7 @@ Spans representing calls to a PostgreSQL database adhere to the general [Semanti **Span kind** SHOULD be `CLIENT`. -**Span status** SHOULD follow [Recording Errors](/docs/general/recording-errors.md) document. +**Span status** SHOULD follow the [Recording Errors](/docs/general/recording-errors.md) document. | Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | |---|---|---|---|---|---| diff --git a/docs/database/redis.md b/docs/database/redis.md index ac71c85e27..f92e1a045e 100644 --- a/docs/database/redis.md +++ b/docs/database/redis.md @@ -28,7 +28,7 @@ looking confusing. **Span kind** SHOULD be `CLIENT`. -**Span status** SHOULD follow [Recording Errors](/docs/general/recording-errors.md) document. +**Span status** SHOULD follow the [Recording Errors](/docs/general/recording-errors.md) document. | Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | |---|---|---|---|---|---| diff --git a/docs/database/sql.md b/docs/database/sql.md index 765cfab1ec..98e38a44cc 100644 --- a/docs/database/sql.md +++ b/docs/database/sql.md @@ -47,7 +47,7 @@ Instrumentations applied to generic SQL drivers SHOULD adhere to SQL semantic co **Span kind** SHOULD be `CLIENT`. -**Span status** SHOULD follow [Recording Errors](/docs/general/recording-errors.md) document. +**Span status** SHOULD follow the [Recording Errors](/docs/general/recording-errors.md) document. | Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | |---|---|---|---|---|---| diff --git a/docs/faas/aws-lambda.md b/docs/faas/aws-lambda.md index 05b0d17e21..07b55a73b6 100644 --- a/docs/faas/aws-lambda.md +++ b/docs/faas/aws-lambda.md @@ -56,7 +56,7 @@ unless stated otherwise. **Span kind** MUST be set to `SERVER` unless stated otherwise. -**Span status** SHOULD follow [Recording Errors](/docs/general/recording-errors.md) document. +**Span status** SHOULD follow the [Recording Errors](/docs/general/recording-errors.md) document. | Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | |---|---|---|---|---|---| diff --git a/docs/faas/faas-spans.md b/docs/faas/faas-spans.md index a2d82d449f..2c08fbc2ad 100644 --- a/docs/faas/faas-spans.md +++ b/docs/faas/faas-spans.md @@ -142,7 +142,7 @@ This span represents server (incoming) side of the FaaS invocation. **Span kind** SHOULD be `SERVER`. -**Span status** SHOULD follow [Recording Errors](/docs/general/recording-errors.md) document. +**Span status** SHOULD follow the [Recording Errors](/docs/general/recording-errors.md) document. | Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | |---|---|---|---|---|---| @@ -205,7 +205,7 @@ which the invoked FaaS instance reports about itself, if it's instrumented. **Status:** ![Development](https://img.shields.io/badge/-development-blue) -This span represents outgoing call to FaaS service. +This span represents an outgoing call to a FaaS service. The values reported by the client for the attributes listed below SHOULD be equal to the corresponding [FaaS resource attributes][] and [Cloud resource attributes][], @@ -213,7 +213,7 @@ which the invoked FaaS instance reports about itself, if it's instrumented. **Span kind** SHOULD be `CLIENT`. -**Span status** SHOULD follow [Recording Errors](/docs/general/recording-errors.md) document. +**Span status** SHOULD follow the [Recording Errors](/docs/general/recording-errors.md) document. | Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | |---|---|---|---|---|---| @@ -268,7 +268,7 @@ This span represents server side if the FaaS invocations triggered in response r **Span kind** SHOULD be `SERVER`. -**Span status** SHOULD follow [Recording Errors](/docs/general/recording-errors.md) document. +**Span status** SHOULD follow the [Recording Errors](/docs/general/recording-errors.md) document. | Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | |---|---|---|---|---|---| @@ -321,7 +321,7 @@ This span represents server side if the FaaS invocations triggered by a timer. **Span kind** SHOULD be `SERVER`. -**Span status** SHOULD follow [Recording Errors](/docs/general/recording-errors.md) document. +**Span status** SHOULD follow the [Recording Errors](/docs/general/recording-errors.md) document. | Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | |---|---|---|---|---|---| diff --git a/docs/gen-ai/azure-ai-inference.md b/docs/gen-ai/azure-ai-inference.md index 06946a6728..56899edd48 100644 --- a/docs/gen-ai/azure-ai-inference.md +++ b/docs/gen-ai/azure-ai-inference.md @@ -28,7 +28,7 @@ model name is available and `{gen_ai.operation.name}` otherwise. **Span kind** SHOULD be `CLIENT`. -**Span status** SHOULD follow [Recording Errors](/docs/general/recording-errors.md) document. +**Span status** SHOULD follow the [Recording Errors](/docs/general/recording-errors.md) document. | Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | |---|---|---|---|---|---| diff --git a/docs/gen-ai/gen-ai-agent-spans.md b/docs/gen-ai/gen-ai-agent-spans.md index ab8c458a35..4719fcb5fb 100644 --- a/docs/gen-ai/gen-ai-agent-spans.md +++ b/docs/gen-ai/gen-ai-agent-spans.md @@ -46,7 +46,7 @@ Semantic conventions for individual GenAI systems and frameworks MAY specify dif **Span kind** SHOULD be `CLIENT`. -**Span status** SHOULD follow [Recording Errors](/docs/general/recording-errors.md) document. +**Span status** SHOULD follow the [Recording Errors](/docs/general/recording-errors.md) document. | Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | |---|---|---|---|---|---| diff --git a/docs/gen-ai/gen-ai-spans.md b/docs/gen-ai/gen-ai-spans.md index d0118896a0..6da3edf625 100644 --- a/docs/gen-ai/gen-ai-spans.md +++ b/docs/gen-ai/gen-ai-spans.md @@ -37,7 +37,7 @@ so `gen_ai.usage.output_tokens` does not apply to embeddings operations. **Status:** ![Development](https://img.shields.io/badge/-development-blue) -This span represents client call to Generative AI model or service. +This span represents a client call to Generative AI model or service. **Span name** SHOULD be `{gen_ai.operation.name} {gen_ai.request.model}`. Semantic conventions for individual GenAI systems and frameworks MAY specify different span name format @@ -45,10 +45,10 @@ and MUST follow the overall [guidelines for span names](https://github.com/open- **Span kind** SHOULD be `CLIENT`and MAY be set to `INTERNAL` on spans representing call to models running in the same process. It's RECOMMENDED to use `CLIENT` kind -when GenAI system being instrumented usually runs in a different process than its -client or when GenAI call happens over instrumented protocol such as HTTP. +when the GenAI system being instrumented usually runs in a different process than its +client or when the GenAI call happens over instrumented protocol such as HTTP. -**Span status** SHOULD follow [Recording Errors](/docs/general/recording-errors.md) document. +**Span status** SHOULD follow the [Recording Errors](/docs/general/recording-errors.md) document. | Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | |---|---|---|---|---|---| @@ -185,12 +185,12 @@ Describes tool execution span. GenAI instrumentations that are able to instrument tool execution call SHOULD do so. However, it's common for tools to be executed by the application code. It's recommended -for the application developers to follow this semantic conventions for tool invoked +for the application developers to follow this semantic convention for tools invoked by the application code. **Span kind** SHOULD be `INTERNAL`. -**Span status** SHOULD follow [Recording Errors](/docs/general/recording-errors.md) document. +**Span status** SHOULD follow the [Recording Errors](/docs/general/recording-errors.md) document. | Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | |---|---|---|---|---|---| diff --git a/docs/gen-ai/openai.md b/docs/gen-ai/openai.md index 388473d1ea..d531e7310c 100644 --- a/docs/gen-ai/openai.md +++ b/docs/gen-ai/openai.md @@ -36,7 +36,7 @@ Semantic Conventions for [OpenAI](https://openai.com/) client spans extend and o **Span kind** SHOULD be `CLIENT`. -**Span status** SHOULD follow [Recording Errors](/docs/general/recording-errors.md) document. +**Span status** SHOULD follow the [Recording Errors](/docs/general/recording-errors.md) document. | Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | |---|---|---|---|---|---| diff --git a/docs/graphql/graphql-spans.md b/docs/graphql/graphql-spans.md index f5d5e2d3c0..cf8c7dadbc 100644 --- a/docs/graphql/graphql-spans.md +++ b/docs/graphql/graphql-spans.md @@ -15,7 +15,7 @@ linkTitle: GraphQL server **Status:** ![Development](https://img.shields.io/badge/-development-blue) -This span represents incoming operation on GraphQL server implementation. +This span represents an incoming operation on a GraphQL server implementation. **Span name** SHOULD be of the format `{graphql.operation.type}` provided `graphql.operation.type` is available. If `graphql.operation.type` is not available, @@ -32,7 +32,7 @@ the span SHOULD be named `GraphQL Operation`. **Span kind** SHOULD be `SERVER`. -**Span status** SHOULD follow [Recording Errors](/docs/general/recording-errors.md) document. +**Span status** SHOULD follow the [Recording Errors](/docs/general/recording-errors.md) document. | Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | |---|---|---|---|---|---| diff --git a/docs/object-stores/s3.md b/docs/object-stores/s3.md index 10b72a9746..9fe963c98c 100644 --- a/docs/object-stores/s3.md +++ b/docs/object-stores/s3.md @@ -19,7 +19,7 @@ Semantic Conventions for AWS S3 client spans extend the general [AWS SDK Semanti **Span kind** SHOULD be `CLIENT`. -**Span status** SHOULD follow [Recording Errors](/docs/general/recording-errors.md) document. +**Span status** SHOULD follow the [Recording Errors](/docs/general/recording-errors.md) document. | Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | |---|---|---|---|---|---| diff --git a/docs/rpc/rpc-spans.md b/docs/rpc/rpc-spans.md index c195a7ba92..00f0123c3e 100644 --- a/docs/rpc/rpc-spans.md +++ b/docs/rpc/rpc-spans.md @@ -96,16 +96,16 @@ Generally, a user SHOULD NOT set `peer.service` to a fully qualified RPC service **Status:** ![Development](https://img.shields.io/badge/-development-blue) -This span represents an outgoing Remote Procedure (RPC) call. +This span represents an outgoing Remote Procedure Call (RPC). -Remote procedure calls can only be represented with these semantic conventions, +Remote procedure calls can only be represented with these semantic conventions when the names of the called service and method are known and available. **Span name:** refer to the [Span Name](#span-name) section. -**Span kind** SHOULD be `CLIENT`. +**Span kind** MUST be `CLIENT`. -**Span status** SHOULD follow [Recording Errors](/docs/general/recording-errors.md) document. +**Span status** SHOULD follow the [Recording Errors](/docs/general/recording-errors.md) document. | Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | |---|---|---|---|---|---| @@ -188,14 +188,14 @@ different processes could be listening on TCP port 12345 and UDP port 12345. This span represents an incoming Remote Procedure (RPC) call. -Remote procedure calls can only be represented with these semantic conventions, +Remote procedure calls can only be represented with these semantic conventions when the names of the called service and method are known and available. **Span name:** refer to the [Span Name](#span-name) section. -**Span kind** SHOULD be `SERVER`. +**Span kind** MUST be `SERVER`. -**Span status** SHOULD follow [Recording Errors](/docs/general/recording-errors.md) document. +**Span status** SHOULD follow the [Recording Errors](/docs/general/recording-errors.md) document. | Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | |---|---|---|---|---|---| diff --git a/model/aws/sdk-spans.yaml b/model/aws/sdk-spans.yaml index 16bf00e504..78c17ae474 100644 --- a/model/aws/sdk-spans.yaml +++ b/model/aws/sdk-spans.yaml @@ -4,7 +4,7 @@ groups: stability: development span_kind: client brief: > - This span describes AWS SDK client call. + This span describes an AWS SDK client call. note: | **Span name** MUST be of the format `Service.Operation` as per the AWS HTTP API, e.g., `DynamoDB.GetItem`, `S3.ListBuckets`. This is @@ -39,7 +39,7 @@ groups: - id: span.dynamodb.batchgetitem.client brief: > - This span represents `DynamoDB.BatchGetItem` call. + This span represents a `DynamoDB.BatchGetItem` call. note: > `db.system.name` MUST be set to `"aws.dynamodb"` and SHOULD be provided **at span creation time**. extends: span.aws.client @@ -54,7 +54,7 @@ groups: - id: span.dynamodb.batchwriteitem.client brief: > - This span represents `DynamoDB.BatchWriteItem` call. + This span represents a `DynamoDB.BatchWriteItem` call. note: > `db.system.name` MUST be set to `"aws.dynamodb"` and SHOULD be provided **at span creation time**. extends: span.aws.client @@ -71,7 +71,7 @@ groups: - id: span.dynamodb.createtable.client brief: > - This span represents `DynamoDB.CreateTable` call. + This span represents a `DynamoDB.CreateTable` call. note: > `db.system.name` MUST be set to `"aws.dynamodb"` and SHOULD be provided **at span creation time**. extends: span.aws.client @@ -99,7 +99,7 @@ groups: - id: span.dynamodb.deleteitem.client brief: > - This span represents `DynamoDB.DeleteItem` call. + This span represents a `DynamoDB.DeleteItem` call. note: > `db.system.name` MUST be set to `"aws.dynamodb"` and SHOULD be provided **at span creation time**. extends: span.aws.client @@ -119,7 +119,7 @@ groups: - id: span.dynamodb.deletetable.client brief: > - This span represents `DynamoDB.DeleteTable` call. + This span represents a `DynamoDB.DeleteTable` call. note: > `db.system.name` MUST be set to `"aws.dynamodb"` and SHOULD be provided **at span creation time**. extends: span.aws.client @@ -135,7 +135,7 @@ groups: - id: span.dynamodb.describetable.client brief: > - This span represents `DynamoDB.DescribeTable` call. + This span represents a `DynamoDB.DescribeTable` call. note: > `db.system.name` MUST be set to `"aws.dynamodb"` and SHOULD be provided **at span creation time**. extends: span.aws.client @@ -151,7 +151,7 @@ groups: - id: span.dynamodb.getitem.client brief: > - This span represents `DynamoDB.GetItem` call. + This span represents a `DynamoDB.GetItem` call. note: > `db.system.name` MUST be set to `"aws.dynamodb"` and SHOULD be provided **at span creation time**. extends: span.aws.client @@ -173,7 +173,7 @@ groups: - id: span.dynamodb.listtables.client brief: > - This span represents `DynamoDB.ListTables` call. + This span represents a `DynamoDB.ListTables` call. note: > `db.system.name` MUST be set to `"aws.dynamodb"` and SHOULD be provided **at span creation time**. extends: span.aws.client @@ -190,7 +190,7 @@ groups: - id: span.dynamodb.putitem.client brief: > - This span represents `DynamoDB.PutItem` call. + This span represents a `DynamoDB.PutItem` call. note: > `db.system.name` MUST be set to `"aws.dynamodb"` and SHOULD be provided **at span creation time**. extends: span.aws.client @@ -207,7 +207,7 @@ groups: - id: span.dynamodb.query.client brief: > - This span represents `DynamoDB.Query` call. + This span represents a `DynamoDB.Query` call. note: > `db.system.name` MUST be set to `"aws.dynamodb"` and SHOULD be provided **at span creation time**. extends: span.aws.client @@ -239,7 +239,7 @@ groups: - id: span.dynamodb.scan.client brief: > - This span represents `DynamoDB.Scan` call. + This span represents a `DynamoDB.Scan` call. note: > `db.system.name` MUST be set to `"aws.dynamodb"` and SHOULD be provided **at span creation time**. extends: span.aws.client @@ -277,7 +277,7 @@ groups: - id: span.dynamodb.updateitem.client brief: > - This span represents `DynamoDB.UpdateItem` call. + This span represents a `DynamoDB.UpdateItem` call. note: > `db.system.name` MUST be set to `"aws.dynamodb"` and SHOULD be provided **at span creation time**. extends: span.aws.client @@ -297,7 +297,7 @@ groups: - id: span.dynamodb.updatetable.client brief: > - This span represents `DynamoDB.UpdateTable` call. + This span represents a `DynamoDB.UpdateTable` call. note: > `db.system.name` MUST be set to `"aws.dynamodb"` and SHOULD be provided **at span creation time**. extends: span.aws.client diff --git a/model/database/spans.yaml b/model/database/spans.yaml index ab7ed1d22d..03fa4986c3 100644 --- a/model/database/spans.yaml +++ b/model/database/spans.yaml @@ -371,7 +371,7 @@ groups: - id: span.db.couchdb.client type: span span_kind: client - stability: release_candidate + stability: development extends: trace.db.common.minimal brief: > Spans representing calls to CouchDB adhere to the general [Semantic Conventions for Database Client Spans](/docs/database/database-spans.md). diff --git a/model/faas/spans.yaml b/model/faas/spans.yaml index 9534ab47fd..50c10c05c6 100644 --- a/model/faas/spans.yaml +++ b/model/faas/spans.yaml @@ -78,7 +78,7 @@ groups: type: span stability: development brief: > - This span represents outgoing call to FaaS service. + This span represents an outgoing call to a FaaS service. note: | The values reported by the client for the attributes listed below SHOULD be equal to the corresponding [FaaS resource attributes][] and [Cloud resource attributes][], diff --git a/model/gen-ai/spans.yaml b/model/gen-ai/spans.yaml index 061e7496d4..bf0bf05b19 100644 --- a/model/gen-ai/spans.yaml +++ b/model/gen-ai/spans.yaml @@ -70,7 +70,7 @@ groups: stability: development span_kind: client brief: > - This span represents client call to Generative AI model or service. + This span represents a client call to Generative AI model or service. note: | **Span name** SHOULD be `{gen_ai.operation.name} {gen_ai.request.model}`. Semantic conventions for individual GenAI systems and frameworks MAY specify different span name format @@ -78,8 +78,8 @@ groups: **Span kind** SHOULD be `CLIENT`and MAY be set to `INTERNAL` on spans representing call to models running in the same process. It's RECOMMENDED to use `CLIENT` kind - when GenAI system being instrumented usually runs in a different process than its - client or when GenAI call happens over instrumented protocol such as HTTP. + when the GenAI system being instrumented usually runs in a different process than its + client or when the GenAI call happens over instrumented protocol such as HTTP. extends: trace.gen_ai.client.common_attributes attributes: - ref: gen_ai.system @@ -221,7 +221,7 @@ groups: GenAI instrumentations that are able to instrument tool execution call SHOULD do so. However, it's common for tools to be executed by the application code. It's recommended - for the application developers to follow this semantic conventions for tool invoked + for the application developers to follow this semantic convention for tools invoked by the application code. attributes: - ref: gen_ai.tool.name diff --git a/model/graphql/spans.yml b/model/graphql/spans.yml index ea4042a5aa..6b33d3b87c 100644 --- a/model/graphql/spans.yml +++ b/model/graphql/spans.yml @@ -4,7 +4,7 @@ groups: stability: development span_kind: server brief: > - This span represents incoming operation on GraphQL server implementation. + This span represents an incoming operation on a GraphQL server implementation. note: | **Span name** SHOULD be of the format `{graphql.operation.type}` provided `graphql.operation.type` is available. If `graphql.operation.type` is not available, diff --git a/model/rpc/spans.yaml b/model/rpc/spans.yaml index d836bb8e0f..940ba11761 100644 --- a/model/rpc/spans.yaml +++ b/model/rpc/spans.yaml @@ -28,12 +28,14 @@ groups: - id: span.rpc.client type: span stability: development - brief: This span represents an outgoing Remote Procedure (RPC) call. + brief: This span represents an outgoing Remote Procedure Call (RPC). note: | - Remote procedure calls can only be represented with these semantic conventions, + Remote procedure calls can only be represented with these semantic conventions when the names of the called service and method are known and available. **Span name:** refer to the [Span Name](#span-name) section. + + **Span kind** MUST be `CLIENT`. extends: rpc span_kind: client events: [rpc.message] @@ -52,10 +54,12 @@ groups: brief: 'This span represents an incoming Remote Procedure (RPC) call.' events: [rpc.message] note: | - Remote procedure calls can only be represented with these semantic conventions, + Remote procedure calls can only be represented with these semantic conventions when the names of the called service and method are known and available. **Span name:** refer to the [Span Name](#span-name) section. + + **Span kind** MUST be `SERVER`. attributes: - ref: client.address requirement_level: recommended diff --git a/templates/registry/markdown/span_macros.j2 b/templates/registry/markdown/span_macros.j2 index 17fcdc30de..f8e10a2d78 100644 --- a/templates/registry/markdown/span_macros.j2 +++ b/templates/registry/markdown/span_macros.j2 @@ -12,6 +12,6 @@ **Span kind** SHOULD be `{{ span.span_kind | upper }}`.{% endif %} {%- if "**Span status" not in span.note %} -**Span status** SHOULD follow [Recording Errors](/docs/general/recording-errors.md) document.{% endif %} +**Span status** SHOULD follow the [Recording Errors](/docs/general/recording-errors.md) document.{% endif %} {% endmacro %} From 39494a8cab83372612ed10a93f37213b382aeedd Mon Sep 17 00:00:00 2001 From: Liudmila Molkova Date: Mon, 7 Apr 2025 15:05:00 -0700 Subject: [PATCH 4/5] feedback: part 2 --- docs/faas/faas-spans.md | 6 +----- docs/rpc/rpc-spans.md | 2 +- model/rpc/spans.yaml | 2 +- 3 files changed, 3 insertions(+), 7 deletions(-) diff --git a/docs/faas/faas-spans.md b/docs/faas/faas-spans.md index 2c08fbc2ad..33b1f5dfcc 100644 --- a/docs/faas/faas-spans.md +++ b/docs/faas/faas-spans.md @@ -127,7 +127,7 @@ The span attribute `faas.invocation_id` differs from the [resource attribute][Fa This section describes incoming FaaS invocations as they are reported by the FaaS instance itself. -### Incoming FaaS Span attributes +### Incoming FaaS span attributes @@ -192,10 +192,6 @@ In principle, the above considerations apply to any resource attribute that fulf This section describes outgoing FaaS invocations as they are reported by a client calling a FaaS instance. -The values reported by the client for the attributes listed below SHOULD be equal to -the corresponding [FaaS resource attributes][] and [Cloud resource attributes][], -which the invoked FaaS instance reports about itself, if it's instrumented. - diff --git a/docs/rpc/rpc-spans.md b/docs/rpc/rpc-spans.md index 00f0123c3e..b05d123c65 100644 --- a/docs/rpc/rpc-spans.md +++ b/docs/rpc/rpc-spans.md @@ -186,7 +186,7 @@ different processes could be listening on TCP port 12345 and UDP port 12345. **Status:** ![Development](https://img.shields.io/badge/-development-blue) -This span represents an incoming Remote Procedure (RPC) call. +This span represents an incoming Remote Procedure Call (RPC). Remote procedure calls can only be represented with these semantic conventions when the names of the called service and method are known and available. diff --git a/model/rpc/spans.yaml b/model/rpc/spans.yaml index 940ba11761..9d4383766d 100644 --- a/model/rpc/spans.yaml +++ b/model/rpc/spans.yaml @@ -51,7 +51,7 @@ groups: stability: development extends: rpc span_kind: server - brief: 'This span represents an incoming Remote Procedure (RPC) call.' + brief: This span represents an incoming Remote Procedure Call (RPC). events: [rpc.message] note: | Remote procedure calls can only be represented with these semantic conventions From 4a90e2ef39eaf5ca3117f4808905c6489f2b5e0c Mon Sep 17 00:00:00 2001 From: Liudmila Molkova Date: Wed, 9 Apr 2025 09:29:44 -0700 Subject: [PATCH 5/5] update oracle semconv --- docs/database/oracledb.md | 18 +++++++++++------- model/database/spans.yaml | 4 +++- 2 files changed, 14 insertions(+), 8 deletions(-) diff --git a/docs/database/oracledb.md b/docs/database/oracledb.md index 8dfdd4fdd4..a6e4b1ec32 100644 --- a/docs/database/oracledb.md +++ b/docs/database/oracledb.md @@ -17,12 +17,6 @@ The Semantic Conventions for *Oracle Database* extend and override the [Database ## Spans -Spans representing calls to Oracle Database adhere to the general [Semantic Conventions for Database Client Spans](database-spans.md). - -`db.system.name` MUST be set to `"oracle.db"` and SHOULD be provided **at span creation time**. - -The following table outlines the span attributes applicable to Oracle Database. - @@ -30,6 +24,16 @@ The following table outlines the span attributes applicable to Oracle Database. +**Status:** ![Development](https://img.shields.io/badge/-development-blue) + +Spans representing calls to a Oracle SQL Database adhere to the general [Semantic Conventions for Database Client Spans](database-spans.md). + +`db.system.name` MUST be set to `"oracle.db"` and SHOULD be provided **at span creation time**. + +**Span kind** SHOULD be `CLIENT`. + +**Span status** SHOULD follow the [Recording Errors](/docs/general/recording-errors.md) document. + | Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | |---|---|---|---|---|---| | [`db.namespace`](/docs/attributes-registry/db.md) | string | The database associated with the connection, qualified by the instance name, database name and service name. [1] | `ORCL1\|PDB1\|db_high.adb.oraclecloud.com`; `ORCL1\|DB1\|db_low.adb.oraclecloud.com`; `ORCL1\|DB1\|order-processing-service` | `Conditionally Required` If available without an additional network call. | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | @@ -62,7 +66,7 @@ Instrumentations SHOULD document how `error.type` is populated. **[6] `db.operation.batch.size`:** Operations are only considered batches when they contain two or more operations, and so `db.operation.batch.size` SHOULD never be `1`. **[7] `db.query.summary`:** `db.query.summary` provides static summary of the query text. It describes a class of database queries and is useful as a grouping key, especially when analyzing telemetry for database calls involving complex queries. -Summary may be available to the instrumentation through instrumentation hooks or other means. If it is not available, instrumentations that support query parsing SHOULD generate a summary following [Generating query summary](../database/database-spans.md#generating-a-summary-of-the-query-text) section. +Summary may be available to the instrumentation through instrumentation hooks or other means. If it is not available, instrumentations that support query parsing SHOULD generate a summary following [Generating query summary](/docs/database/database-spans.md#generating-a-summary-of-the-query-text) section. **[8] `db.query.summary`:** if readily available or if instrumentation supports query summarization. diff --git a/model/database/spans.yaml b/model/database/spans.yaml index 03fa4986c3..2bb362c619 100644 --- a/model/database/spans.yaml +++ b/model/database/spans.yaml @@ -944,7 +944,9 @@ groups: extends: span.db.sql.client span_kind: client brief: > - Attributes for Oracle Database + Spans representing calls to a Oracle SQL Database adhere to the general [Semantic Conventions for Database Client Spans](database-spans.md). + note: | + `db.system.name` MUST be set to `"oracle.db"` and SHOULD be provided **at span creation time**. attributes: - ref: db.namespace sampling_relevant: true