diff --git a/.chloggen/1393.yaml b/.chloggen/1393.yaml new file mode 100644 index 0000000000..c62971bbc9 --- /dev/null +++ b/.chloggen/1393.yaml @@ -0,0 +1,4 @@ +change_type: enhancement +component: gen_ai +note: Add system-specific conventions for Azure AI Inference. +issues: [1393] diff --git a/.chloggen/update-graphql-span-name.yaml b/.chloggen/update-graphql-span-name.yaml new file mode 100644 index 0000000000..1f0cc3f50e --- /dev/null +++ b/.chloggen/update-graphql-span-name.yaml @@ -0,0 +1,4 @@ +change_type: breaking +component: graphql +note: Update the GraphQL Span name convention +issues: [1361] diff --git a/Makefile b/Makefile index 4e4a64d350..26e7a2cf83 100644 --- a/Makefile +++ b/Makefile @@ -155,7 +155,7 @@ table-check: --templates=/home/weaver/templates \ --target=markdown \ --dry-run \ - /spec + /home/weaver/target .PHONY: schema-check schema-check: diff --git a/README.md b/README.md index 0c0b2d5ce4..6227be7ca2 100644 --- a/README.md +++ b/README.md @@ -34,6 +34,9 @@ Maintainers ([@open-telemetry/specs-semconv-maintainers](https://github.com/orgs - [Johannes Tax](https://github.com/pyohannes), Grafana Labs - [Josh Suereth](https://github.com/jsuereth), Google - [Liudmila Molkova](https://github.com/lmolkova), Microsoft -- [Reiley Yang](https://github.com/reyang), Microsoft + +Emeritus Maintainers: + +- [Reiley Yang](https://github.com/reyang) _Find more about the maintainer role in [community repository](https://github.com/open-telemetry/community/blob/main/guides/contributor/membership.md#maintainer)._ diff --git a/dependencies.Dockerfile b/dependencies.Dockerfile index 9423ce0749..ec9d99157d 100644 --- a/dependencies.Dockerfile +++ b/dependencies.Dockerfile @@ -6,7 +6,7 @@ FROM otel/weaver:v0.10.0 AS weaver # OPA is used to test policies enforced by weaver. -FROM openpolicyagent/opa:0.68.0 AS opa +FROM openpolicyagent/opa:0.69.0 AS opa # Semconv gen is used for backwards compatibility checks. # TODO(jsuereth): Remove this when no longer used. diff --git a/docs/attributes-registry/cloudfoundry.md b/docs/attributes-registry/cloudfoundry.md index 26074805e8..fd3d26194f 100644 --- a/docs/attributes-registry/cloudfoundry.md +++ b/docs/attributes-registry/cloudfoundry.md @@ -28,7 +28,7 @@ CloudFoundry resource attributes. variable `VCAP_APPLICATION.application_id`. This is the same value as reported by `cf app --guid`. -**[2]:** CloudFoundry defines the `instance_id` in the [Loggegator v2 envelope](https://github.com/cloudfoundry/loggregator-api#v2-envelope). +**[2]:** CloudFoundry defines the `instance_id` in the [Loggregator v2 envelope](https://github.com/cloudfoundry/loggregator-api#v2-envelope). It is used for logs and metrics emitted by CloudFoundry. It is supposed to contain the application instance index for applications deployed on the runtime. diff --git a/docs/attributes-registry/gen-ai.md b/docs/attributes-registry/gen-ai.md index 12c5283980..b4e8b64599 100644 --- a/docs/attributes-registry/gen-ai.md +++ b/docs/attributes-registry/gen-ai.md @@ -54,12 +54,13 @@ If none of these options apply, the `gen_ai.system` SHOULD be set to `_OTHER`. `gen_ai.system` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. -| Value | Description | Stability | -| ----------- | ----------- | ---------------------------------------------------------------- | -| `anthropic` | Anthropic | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `cohere` | Cohere | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `openai` | OpenAI | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `vertex_ai` | Vertex AI | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| Value | Description | Stability | +| ----------------- | ------------------ | ---------------------------------------------------------------- | +| `anthropic` | Anthropic | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `az.ai.inference` | Azure AI Inference | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `cohere` | Cohere | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `openai` | OpenAI | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `vertex_ai` | Vertex AI | ![Experimental](https://img.shields.io/badge/-experimental-blue) | `gen_ai.token.type` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. diff --git a/docs/database/cassandra.md b/docs/database/cassandra.md index 0449d0c37e..fa4dc7a04b 100644 --- a/docs/database/cassandra.md +++ b/docs/database/cassandra.md @@ -74,6 +74,7 @@ Instrumentations SHOULD document how `error.type` is populated. **[10]:** If using a port other than the default port for this DBMS and if `server.address` is set. **[11]:** Operations are only considered batches when they contain two or more operations, and so `db.operation.batch.size` SHOULD never be `1`. +This attribute has stability level RELEASE CANDIDATE. **[12]:** 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. diff --git a/docs/database/cosmosdb.md b/docs/database/cosmosdb.md index 465a37d4af..1f3aa255ea 100644 --- a/docs/database/cosmosdb.md +++ b/docs/database/cosmosdb.md @@ -186,6 +186,7 @@ Instrumentations SHOULD document how `error.type` is populated. **[8]:** When `az.namespace` attribute is populated, it MUST be set to `Microsoft.DocumentDB` for all operations performed by Cosmos DB client. **[9]:** Operations are only considered batches when they contain two or more operations, and so `db.operation.batch.size` SHOULD never be `1`. +This attribute has stability level RELEASE CANDIDATE. **[10]:** 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. diff --git a/docs/database/couchdb.md b/docs/database/couchdb.md index f173e74099..bef4cba8e0 100644 --- a/docs/database/couchdb.md +++ b/docs/database/couchdb.md @@ -48,6 +48,7 @@ Instrumentations SHOULD document how `error.type` is populated. **[7]:** If using a port other than the default port for this DBMS and if `server.address` is set. **[8]:** Operations are only considered batches when they contain two or more operations, and so `db.operation.batch.size` SHOULD never be `1`. +This attribute has stability level RELEASE CANDIDATE. **[9]:** 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. diff --git a/docs/database/database-spans.md b/docs/database/database-spans.md index 6f3e6abc69..3a581c20f4 100644 --- a/docs/database/database-spans.md +++ b/docs/database/database-spans.md @@ -141,6 +141,7 @@ Instrumentations SHOULD document how `error.type` is populated. **[11]:** If using a port other than the default port for this DBMS and if `server.address` is set. **[12]:** Operations are only considered batches when they contain two or more operations, and so `db.operation.batch.size` SHOULD never be `1`. +This attribute has stability level RELEASE CANDIDATE. **[13]:** 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. diff --git a/docs/database/elasticsearch.md b/docs/database/elasticsearch.md index 3a09c874ed..289693a830 100644 --- a/docs/database/elasticsearch.md +++ b/docs/database/elasticsearch.md @@ -81,6 +81,7 @@ Instrumentations SHOULD document how `error.type` is populated. **[11]:** When communicating with an Elastic Cloud deployment, this should be collected from the "X-Found-Handling-Cluster" HTTP response header. **[12]:** Operations are only considered batches when they contain two or more operations, and so `db.operation.batch.size` SHOULD never be `1`. +This attribute has stability level RELEASE CANDIDATE. **[13]:** 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. diff --git a/docs/database/hbase.md b/docs/database/hbase.md index d915ce18f9..f8ea96c09f 100644 --- a/docs/database/hbase.md +++ b/docs/database/hbase.md @@ -57,6 +57,7 @@ Instrumentations SHOULD document how `error.type` is populated. **[8]:** If using a port other than the default port for this DBMS and if `server.address` is set. **[9]:** Operations are only considered batches when they contain two or more operations, and so `db.operation.batch.size` SHOULD never be `1`. +This attribute has stability level RELEASE CANDIDATE. **[10]:** 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. diff --git a/docs/database/mariadb.md b/docs/database/mariadb.md index d459947b31..eb049e68ae 100644 --- a/docs/database/mariadb.md +++ b/docs/database/mariadb.md @@ -99,6 +99,7 @@ Instrumentations SHOULD document how `error.type` is populated. **[9]:** If using a port other than the default port for this DBMS and if `server.address` is set. **[10]:** Operations are only considered batches when they contain two or more operations, and so `db.operation.batch.size` SHOULD never be `1`. +This attribute has stability level RELEASE CANDIDATE. **[11]:** 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. diff --git a/docs/database/mongodb.md b/docs/database/mongodb.md index 50b201a7ef..009446422b 100644 --- a/docs/database/mongodb.md +++ b/docs/database/mongodb.md @@ -54,6 +54,7 @@ Instrumentations SHOULD document how `error.type` is populated. **[8]:** If using a port other than the default port for this DBMS and if `server.address` is set. **[9]:** Operations are only considered batches when they contain two or more operations, and so `db.operation.batch.size` SHOULD never be `1`. +This attribute has stability level RELEASE CANDIDATE. **[10]:** 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. diff --git a/docs/database/mssql.md b/docs/database/mssql.md index 12e95b9691..b3bf639195 100644 --- a/docs/database/mssql.md +++ b/docs/database/mssql.md @@ -69,6 +69,7 @@ Instrumentations SHOULD document how `error.type` is populated. **[9]:** If using a port other than the default port for this DBMS and if `server.address` is set. **[10]:** Operations are only considered batches when they contain two or more operations, and so `db.operation.batch.size` SHOULD never be `1`. +This attribute has stability level RELEASE CANDIDATE. **[11]:** 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. diff --git a/docs/database/mysql.md b/docs/database/mysql.md index e6ecc6e222..dc494d78c6 100644 --- a/docs/database/mysql.md +++ b/docs/database/mysql.md @@ -99,6 +99,7 @@ Instrumentations SHOULD document how `error.type` is populated. **[9]:** If using a port other than the default port for this DBMS and if `server.address` is set. **[10]:** Operations are only considered batches when they contain two or more operations, and so `db.operation.batch.size` SHOULD never be `1`. +This attribute has stability level RELEASE CANDIDATE. **[11]:** 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. diff --git a/docs/database/postgresql.md b/docs/database/postgresql.md index fde8480aca..8374a315ef 100644 --- a/docs/database/postgresql.md +++ b/docs/database/postgresql.md @@ -106,6 +106,7 @@ Instrumentations SHOULD document how `error.type` is populated. **[9]:** If using a port other than the default port for this DBMS and if `server.address` is set. **[10]:** Operations are only considered batches when they contain two or more operations, and so `db.operation.batch.size` SHOULD never be `1`. +This attribute has stability level RELEASE CANDIDATE. **[11]:** 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. diff --git a/docs/database/redis.md b/docs/database/redis.md index 6157c40e92..80ef32582b 100644 --- a/docs/database/redis.md +++ b/docs/database/redis.md @@ -63,6 +63,7 @@ Instrumentations SHOULD document how `error.type` is populated. **[8]:** If using a port other than the default port for this DBMS and if `server.address` is set. **[9]:** Operations are only considered batches when they contain two or more operations, and so `db.operation.batch.size` SHOULD never be `1`. +This attribute has stability level RELEASE CANDIDATE. **[10]:** 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/commands/hmset) is invoked, `"HMSET myhash field1 'Hello' field2 'World'"` would be a suitable value for `db.query.text`. diff --git a/docs/database/sql.md b/docs/database/sql.md index a4866d6d03..edd249e0f6 100644 --- a/docs/database/sql.md +++ b/docs/database/sql.md @@ -131,6 +131,7 @@ Instrumentations SHOULD document how `error.type` is populated. **[9]:** If using a port other than the default port for this DBMS and if `server.address` is set. **[10]:** Operations are only considered batches when they contain two or more operations, and so `db.operation.batch.size` SHOULD never be `1`. +This attribute has stability level RELEASE CANDIDATE. **[11]:** 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. diff --git a/docs/gen-ai/README.md b/docs/gen-ai/README.md index 020fd0a4ca..d9fc8d3c69 100644 --- a/docs/gen-ai/README.md +++ b/docs/gen-ai/README.md @@ -20,4 +20,9 @@ Semantic conventions for Generative AI operations are defined for the following * [Metrics](gen-ai-metrics.md): Semantic Conventions for Generative AI operations - *metrics*. * [Spans](gen-ai-spans.md): Semantic Conventions for Generative AI requests - *spans*. +Technology specific semantic conventions are defined for the following GenAI system: + +* [Azure AI Inference](./azure-ai-inference.md): Semantic Conventions for Azure AI Inference. +* [OpenAI](./openai.md): Semantic Conventions for OpenAI. + [DocumentStatus]: https://opentelemetry.io/docs/specs/otel/document-status diff --git a/docs/gen-ai/azure-ai-inference.md b/docs/gen-ai/azure-ai-inference.md new file mode 100644 index 0000000000..60b860cf70 --- /dev/null +++ b/docs/gen-ai/azure-ai-inference.md @@ -0,0 +1,87 @@ + + +# Semantic Conventions for Azure AI Inference + +**Status**: [Experimental][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 + + + + + + + + +| 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` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`error.type`](/docs/attributes-registry/error.md) | string | Describes a class of error the operation ended with. [2] | `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) | +| [`gen_ai.request.model`](/docs/attributes-registry/gen-ai.md) | string | The name of the GenAI model a request is being made to. [3] | `gpt-4` | `Conditionally Required` If available. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`server.port`](/docs/attributes-registry/server.md) | int | GenAI server port. [4] | `80`; `8080`; `443` | `Conditionally Required` If not default (443). | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| [`az.namespace`](/docs/attributes-registry/azure.md) | string | [Azure Resource Provider Namespace](https://learn.microsoft.com/azure/azure-resource-manager/management/azure-services-resource-providers) as recognized by the client. [5] | `Microsoft.CognitiveServices` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`gen_ai.request.frequency_penalty`](/docs/attributes-registry/gen-ai.md) | double | The frequency penalty setting for the GenAI request. | `0.1` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`gen_ai.request.max_tokens`](/docs/attributes-registry/gen-ai.md) | int | The maximum number of tokens the model generates for a request. | `100` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`gen_ai.request.presence_penalty`](/docs/attributes-registry/gen-ai.md) | double | The presence penalty setting for the GenAI request. | `0.1` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`gen_ai.request.stop_sequences`](/docs/attributes-registry/gen-ai.md) | string[] | List of sequences that the model will use to stop generating further tokens. | `["forest", "lived"]` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`gen_ai.request.temperature`](/docs/attributes-registry/gen-ai.md) | double | The temperature setting for the GenAI request. | `0.0` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`gen_ai.request.top_p`](/docs/attributes-registry/gen-ai.md) | double | The top_p sampling setting for the GenAI request. | `1.0` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`gen_ai.response.finish_reasons`](/docs/attributes-registry/gen-ai.md) | string[] | Array of reasons the model stopped generating tokens, corresponding to each generation received. | `["stop"]`; `["stop", "length"]` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`gen_ai.response.id`](/docs/attributes-registry/gen-ai.md) | string | The unique identifier for the completion. | `chatcmpl-123` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`gen_ai.response.model`](/docs/attributes-registry/gen-ai.md) | string | The name of the model that generated the response. [6] | `gpt-4-0613` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`gen_ai.usage.input_tokens`](/docs/attributes-registry/gen-ai.md) | int | The number of prompt tokens as reported in the usage prompt_tokens property of the response. | `100` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`gen_ai.usage.output_tokens`](/docs/attributes-registry/gen-ai.md) | int | The number of completion tokens as reported in the usage completion_tokens property of the response. | `180` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`server.address`](/docs/attributes-registry/server.md) | string | GenAI server address. [7] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | `Recommended` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | + +**[1]:** If one of the predefined values applies, but specific system uses a different name it's RECOMMENDED to document it in the semantic conventions for specific GenAI system and use system-specific name in the instrumentation. If a different name is not documented, instrumentation libraries SHOULD use applicable predefined value. + +**[2]:** The `error.type` SHOULD match the error code returned by the Generative AI provider or the client library, +the canonical name of exception that occurred, or another low-cardinality error identifier. +Instrumentations SHOULD document the list of errors they report. + +**[3]:** The name of the GenAI model a request is being made to. If the model is supplied by a vendor, then the value must be the exact name of the model requested. If the model is a fine-tuned custom model, the value should have a more specific name than the base model that's been fine-tuned. + +**[4]:** When observed from the client side, and when communicating through an intermediary, `server.port` SHOULD represent the server port behind any intermediaries, for example proxies, if it's available. + +**[5]:** When `az.namespace` attribute is populated, it MUST be set to `Microsoft.CognitiveServices` for all operations performed by Azure AI Inference clients. + +**[6]:** If available. The name of the GenAI model that provided the response. If the model is supplied by a vendor, then the value must be the exact name of the model actually used. If the model is a fine-tuned custom model, the value should have a more specific name than the base model that's been fine-tuned. + +**[7]:** 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. + + + +`error.type` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. + +| Value | Description | Stability | +|---|---|---| +| `_OTHER` | A fallback error value to be used when the instrumentation doesn't define a custom value. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | + + +`gen_ai.operation.name` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. + +| Value | Description | Stability | +|---|---|---| +| `chat` | Chat completion operation such as [OpenAI Chat API](https://platform.openai.com/docs/api-reference/chat) | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `text_completion` | Text completions operation such as [OpenAI Completions API (Legacy)](https://platform.openai.com/docs/api-reference/completions) | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + + + + + + + + +## Azure AI Inference Metrics + +Azure AI Inference metrics follow generic [Generative AI metrics](gen-ai-metrics.md). + +[DocumentStatus]: https://opentelemetry.io/docs/specs/otel/document-status diff --git a/docs/gen-ai/gen-ai-events.md b/docs/gen-ai/gen-ai-events.md index e56139b1b7..c63a6e42cc 100644 --- a/docs/gen-ai/gen-ai-events.md +++ b/docs/gen-ai/gen-ai-events.md @@ -82,6 +82,7 @@ If none of these options apply, the `gen_ai.system` SHOULD be set to `_OTHER`. | Value | Description | Stability | |---|---|---| | `anthropic` | Anthropic | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `az.ai.inference` | Azure AI Inference | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `cohere` | Cohere | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `openai` | OpenAI | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `vertex_ai` | Vertex AI | ![Experimental](https://img.shields.io/badge/-experimental-blue) | diff --git a/docs/gen-ai/gen-ai-metrics.md b/docs/gen-ai/gen-ai-metrics.md index 0e6244b62c..a959a856e3 100644 --- a/docs/gen-ai/gen-ai-metrics.md +++ b/docs/gen-ai/gen-ai-metrics.md @@ -32,6 +32,9 @@ The following metric instruments describe Generative AI operations. An operation may be a request to an LLM, a function call, or some other distinct action within a larger Generative AI workflow. +Individual systems may include additional system-specific attributes. +It is recommended to check system-specific documentation, if available. + ### Metric: `gen_ai.client.token.usage` This metric is [recommended][MetricRecommended] when an operation involves the usage @@ -59,9 +62,9 @@ This metric SHOULD be specified with [ExplicitBucketBoundaries] of [1, 4, 16, 64 | 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` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| [`gen_ai.request.model`](/docs/attributes-registry/gen-ai.md) | string | The name of the GenAI model a request is being made to. | `gpt-4` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`gen_ai.system`](/docs/attributes-registry/gen-ai.md) | string | The Generative AI product as identified by the client or server instrumentation. [2] | `openai` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`gen_ai.token.type`](/docs/attributes-registry/gen-ai.md) | string | The type of token being counted. | `input`; `output` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`gen_ai.request.model`](/docs/attributes-registry/gen-ai.md) | string | The name of the GenAI model a request is being made to. | `gpt-4` | `Conditionally Required` If available. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`server.port`](/docs/attributes-registry/server.md) | int | GenAI server port. [3] | `80`; `8080`; `443` | `Conditionally Required` If `server.address` is set. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | | [`gen_ai.response.model`](/docs/attributes-registry/gen-ai.md) | string | The name of the model that generated the response. | `gpt-4-0613` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`server.address`](/docs/attributes-registry/server.md) | string | GenAI server address. [4] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | `Recommended` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | @@ -97,6 +100,7 @@ If none of these options apply, the `gen_ai.system` SHOULD be set to `_OTHER`. | Value | Description | Stability | |---|---|---| | `anthropic` | Anthropic | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `az.ai.inference` | Azure AI Inference | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `cohere` | Cohere | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `openai` | OpenAI | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `vertex_ai` | Vertex AI | ![Experimental](https://img.shields.io/badge/-experimental-blue) | @@ -136,9 +140,9 @@ This metric SHOULD be specified with [ExplicitBucketBoundaries] of [0.01, 0.02, | 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` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| [`gen_ai.request.model`](/docs/attributes-registry/gen-ai.md) | string | The name of the GenAI model a request is being made to. | `gpt-4` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`gen_ai.system`](/docs/attributes-registry/gen-ai.md) | string | The Generative AI product as identified by the client or server instrumentation. [2] | `openai` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`error.type`](/docs/attributes-registry/error.md) | string | Describes a class of error the operation ended with. [3] | `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) | +| [`gen_ai.request.model`](/docs/attributes-registry/gen-ai.md) | string | The name of the GenAI model a request is being made to. | `gpt-4` | `Conditionally Required` If available. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`server.port`](/docs/attributes-registry/server.md) | int | GenAI server port. [4] | `80`; `8080`; `443` | `Conditionally Required` If `server.address` is set. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | | [`gen_ai.response.model`](/docs/attributes-registry/gen-ai.md) | string | The name of the model that generated the response. | `gpt-4-0613` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`server.address`](/docs/attributes-registry/server.md) | string | GenAI server address. [5] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | `Recommended` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | @@ -185,6 +189,7 @@ Instrumentations SHOULD document the list of errors they report. | Value | Description | Stability | |---|---|---| | `anthropic` | Anthropic | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `az.ai.inference` | Azure AI Inference | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `cohere` | Cohere | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `openai` | OpenAI | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `vertex_ai` | Vertex AI | ![Experimental](https://img.shields.io/badge/-experimental-blue) | @@ -223,9 +228,9 @@ This metric SHOULD be specified with [ExplicitBucketBoundaries] of | 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` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| [`gen_ai.request.model`](/docs/attributes-registry/gen-ai.md) | string | The name of the GenAI model a request is being made to. | `gpt-4` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`gen_ai.system`](/docs/attributes-registry/gen-ai.md) | string | The Generative AI product as identified by the client or server instrumentation. [2] | `openai` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`error.type`](/docs/attributes-registry/error.md) | string | Describes a class of error the operation ended with. [3] | `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) | +| [`gen_ai.request.model`](/docs/attributes-registry/gen-ai.md) | string | The name of the GenAI model a request is being made to. | `gpt-4` | `Conditionally Required` If available. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`server.port`](/docs/attributes-registry/server.md) | int | GenAI server port. [4] | `80`; `8080`; `443` | `Conditionally Required` If `server.address` is set. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | | [`gen_ai.response.model`](/docs/attributes-registry/gen-ai.md) | string | The name of the model that generated the response. | `gpt-4-0613` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`server.address`](/docs/attributes-registry/server.md) | string | GenAI server address. [5] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | `Recommended` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | @@ -272,6 +277,7 @@ Instrumentations SHOULD document the list of errors they report. | Value | Description | Stability | |---|---|---| | `anthropic` | Anthropic | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `az.ai.inference` | Azure AI Inference | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `cohere` | Cohere | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `openai` | OpenAI | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `vertex_ai` | Vertex AI | ![Experimental](https://img.shields.io/badge/-experimental-blue) | @@ -310,8 +316,8 @@ This metric SHOULD be specified with [ExplicitBucketBoundaries] of | 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` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| [`gen_ai.request.model`](/docs/attributes-registry/gen-ai.md) | string | The name of the GenAI model a request is being made to. | `gpt-4` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`gen_ai.system`](/docs/attributes-registry/gen-ai.md) | string | The Generative AI product as identified by the client or server instrumentation. [2] | `openai` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`gen_ai.request.model`](/docs/attributes-registry/gen-ai.md) | string | The name of the GenAI model a request is being made to. | `gpt-4` | `Conditionally Required` If available. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`server.port`](/docs/attributes-registry/server.md) | int | GenAI server port. [3] | `80`; `8080`; `443` | `Conditionally Required` If `server.address` is set. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | | [`gen_ai.response.model`](/docs/attributes-registry/gen-ai.md) | string | The name of the model that generated the response. | `gpt-4-0613` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`server.address`](/docs/attributes-registry/server.md) | string | GenAI server address. [4] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | `Recommended` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | @@ -347,6 +353,7 @@ If none of these options apply, the `gen_ai.system` SHOULD be set to `_OTHER`. | Value | Description | Stability | |---|---|---| | `anthropic` | Anthropic | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `az.ai.inference` | Azure AI Inference | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `cohere` | Cohere | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `openai` | OpenAI | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `vertex_ai` | Vertex AI | ![Experimental](https://img.shields.io/badge/-experimental-blue) | @@ -384,8 +391,8 @@ This metric SHOULD be specified with [ExplicitBucketBoundaries] of | 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` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| [`gen_ai.request.model`](/docs/attributes-registry/gen-ai.md) | string | The name of the GenAI model a request is being made to. | `gpt-4` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`gen_ai.system`](/docs/attributes-registry/gen-ai.md) | string | The Generative AI product as identified by the client or server instrumentation. [2] | `openai` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`gen_ai.request.model`](/docs/attributes-registry/gen-ai.md) | string | The name of the GenAI model a request is being made to. | `gpt-4` | `Conditionally Required` If available. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`server.port`](/docs/attributes-registry/server.md) | int | GenAI server port. [3] | `80`; `8080`; `443` | `Conditionally Required` If `server.address` is set. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | | [`gen_ai.response.model`](/docs/attributes-registry/gen-ai.md) | string | The name of the model that generated the response. | `gpt-4-0613` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`server.address`](/docs/attributes-registry/server.md) | string | GenAI server address. [4] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | `Recommended` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | @@ -421,6 +428,7 @@ If none of these options apply, the `gen_ai.system` SHOULD be set to `_OTHER`. | Value | Description | Stability | |---|---|---| | `anthropic` | Anthropic | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `az.ai.inference` | Azure AI Inference | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `cohere` | Cohere | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `openai` | OpenAI | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `vertex_ai` | Vertex AI | ![Experimental](https://img.shields.io/badge/-experimental-blue) | diff --git a/docs/gen-ai/gen-ai-spans.md b/docs/gen-ai/gen-ai-spans.md index a2b4b5f8c6..6887710ccd 100644 --- a/docs/gen-ai/gen-ai-spans.md +++ b/docs/gen-ai/gen-ai-spans.md @@ -30,7 +30,7 @@ Semantic conventions for individual GenAI systems and frameworks MAY specify dif These attributes track input data and metadata for a request to an GenAI model. Each attribute represents a concept that is common to most Generative AI clients. - + @@ -40,9 +40,9 @@ These attributes track input data and metadata for a request to an GenAI model. | 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` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| [`gen_ai.request.model`](/docs/attributes-registry/gen-ai.md) | string | The name of the GenAI model a request is being made to. [2] | `gpt-4` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| [`gen_ai.system`](/docs/attributes-registry/gen-ai.md) | string | The Generative AI product as identified by the client or server instrumentation. [3] | `openai` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| [`error.type`](/docs/attributes-registry/error.md) | string | Describes a class of error the operation ended with. [4] | `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) | +| [`gen_ai.system`](/docs/attributes-registry/gen-ai.md) | string | The Generative AI product as identified by the client or server instrumentation. [2] | `openai` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`error.type`](/docs/attributes-registry/error.md) | string | Describes a class of error the operation ended with. [3] | `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) | +| [`gen_ai.request.model`](/docs/attributes-registry/gen-ai.md) | string | The name of the GenAI model a request is being made to. [4] | `gpt-4` | `Conditionally Required` If available. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`server.port`](/docs/attributes-registry/server.md) | int | GenAI server port. [5] | `80`; `8080`; `443` | `Conditionally Required` If `server.address` is set. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | | [`gen_ai.request.frequency_penalty`](/docs/attributes-registry/gen-ai.md) | double | The frequency penalty setting for the GenAI request. | `0.1` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`gen_ai.request.max_tokens`](/docs/attributes-registry/gen-ai.md) | int | The maximum number of tokens the model generates for a request. | `100` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | @@ -60,9 +60,7 @@ These attributes track input data and metadata for a request to an GenAI model. **[1]:** If one of the predefined values applies, but specific system uses a different name it's RECOMMENDED to document it in the semantic conventions for specific GenAI system and use system-specific name in the instrumentation. If a different name is not documented, instrumentation libraries SHOULD use applicable predefined value. -**[2]:** The name of the GenAI model a request is being made to. If the model is supplied by a vendor, then the value must be the exact name of the model requested. If the model is a fine-tuned custom model, the value should have a more specific name than the base model that's been fine-tuned. - -**[3]:** The `gen_ai.system` describes a family of GenAI models with specific model identified +**[2]:** The `gen_ai.system` describes a family of GenAI models with specific model identified by `gen_ai.request.model` and `gen_ai.response.model` attributes. The actual GenAI product may differ from the one identified by the client. @@ -72,10 +70,12 @@ is set to `openai` based on the instrumentation's best knowledge. For custom model, a custom friendly name SHOULD be used. If none of these options apply, the `gen_ai.system` SHOULD be set to `_OTHER`. -**[4]:** The `error.type` SHOULD match the error code returned by the Generative AI provider or the client library, +**[3]:** The `error.type` SHOULD match the error code returned by the Generative AI provider or the client library, the canonical name of exception that occurred, or another low-cardinality error identifier. Instrumentations SHOULD document the list of errors they report. +**[4]:** The name of the GenAI model a request is being made to. If the model is supplied by a vendor, then the value must be the exact name of the model requested. If the model is a fine-tuned custom model, the value should have a more specific name than the base model that's been fine-tuned. + **[5]:** When observed from the client side, and when communicating through an intermediary, `server.port` SHOULD represent the server port behind any intermediaries, for example proxies, if it's available. **[6]:** If available. The name of the GenAI model that provided the response. If the model is supplied by a vendor, then the value must be the exact name of the model actually used. If the model is a fine-tuned custom model, the value should have a more specific name than the base model that's been fine-tuned. @@ -104,6 +104,7 @@ Instrumentations SHOULD document the list of errors they report. | Value | Description | Stability | |---|---|---| | `anthropic` | Anthropic | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `az.ai.inference` | Azure AI Inference | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `cohere` | Cohere | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `openai` | OpenAI | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `vertex_ai` | Vertex AI | ![Experimental](https://img.shields.io/badge/-experimental-blue) | diff --git a/docs/gen-ai/openai.md b/docs/gen-ai/openai.md index 95a4d93846..22a5cba853 100644 --- a/docs/gen-ai/openai.md +++ b/docs/gen-ai/openai.md @@ -10,8 +10,8 @@ linkTitle: OpenAI traces and metrics -- [OpenAI Span attributes](#openai-span-attributes) -- [OpenAI Metric attributes](#openai-metric-attributes) +- [OpenAI Spans](#openai-spans) +- [OpenAI Metrics](#openai-metrics) - [Metric: `gen_ai.client.token.usage`](#metric-gen_aiclienttokenusage) - [Metric: `gen_ai.client.operation.duration`](#metric-gen_aiclientoperationduration) @@ -22,7 +22,7 @@ for [Gen AI Spans](gen-ai-spans.md) and [Gen AI Metrics](gen-ai-metrics.md). `gen_ai.system` MUST be set to `"openai"`. -## OpenAI Span attributes +## 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. @@ -38,13 +38,12 @@ attributes and ones specific the OpenAI. |---|---|---|---|---|---| | [`gen_ai.operation.name`](/docs/attributes-registry/gen-ai.md) | string | The name of the operation being performed. [1] | `chat`; `text_completion` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`gen_ai.request.model`](/docs/attributes-registry/gen-ai.md) | string | The name of the GenAI model a request is being made to. [2] | `gpt-4` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| [`gen_ai.system`](/docs/attributes-registry/gen-ai.md) | string | The Generative AI product as identified by the client or server instrumentation. [3] | `openai` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| [`error.type`](/docs/attributes-registry/error.md) | string | Describes a class of error the operation ended with. [4] | `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) | +| [`error.type`](/docs/attributes-registry/error.md) | string | Describes a class of error the operation ended with. [3] | `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) | | [`gen_ai.openai.request.response_format`](/docs/attributes-registry/gen-ai.md) | string | The response format that is requested. | `json` | `Conditionally Required` if the request includes a response_format | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`gen_ai.openai.request.seed`](/docs/attributes-registry/gen-ai.md) | int | Requests with same seed value more likely to return same result. | `100` | `Conditionally Required` if the request includes a seed | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| [`gen_ai.openai.request.service_tier`](/docs/attributes-registry/gen-ai.md) | string | The service tier requested. May be a specific tier, detault, or auto. | `auto`; `default` | `Conditionally Required` [5] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| [`gen_ai.openai.response.service_tier`](/docs/attributes-registry/gen-ai.md) | string | The service tier used for the response. | `scale`; `detault` | `Conditionally Required` [6] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| [`server.port`](/docs/attributes-registry/server.md) | int | GenAI server port. [7] | `80`; `8080`; `443` | `Conditionally Required` If `server.address` is set. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| [`gen_ai.openai.request.service_tier`](/docs/attributes-registry/gen-ai.md) | string | The service tier requested. May be a specific tier, detault, or auto. | `auto`; `default` | `Conditionally Required` [4] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`gen_ai.openai.response.service_tier`](/docs/attributes-registry/gen-ai.md) | string | The service tier used for the response. | `scale`; `detault` | `Conditionally Required` [5] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`server.port`](/docs/attributes-registry/server.md) | int | GenAI server port. [6] | `80`; `8080`; `443` | `Conditionally Required` If `server.address` is set. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | | [`gen_ai.request.frequency_penalty`](/docs/attributes-registry/gen-ai.md) | double | The frequency penalty setting for the GenAI request. | `0.1` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`gen_ai.request.max_tokens`](/docs/attributes-registry/gen-ai.md) | int | The maximum number of tokens the model generates for a request. | `100` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`gen_ai.request.presence_penalty`](/docs/attributes-registry/gen-ai.md) | double | The presence penalty setting for the GenAI request. | `0.1` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | @@ -53,38 +52,28 @@ attributes and ones specific the OpenAI. | [`gen_ai.request.top_p`](/docs/attributes-registry/gen-ai.md) | double | The top_p sampling setting for the GenAI request. | `1.0` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`gen_ai.response.finish_reasons`](/docs/attributes-registry/gen-ai.md) | string[] | Array of reasons the model stopped generating tokens, corresponding to each generation received. | `["stop"]`; `["stop", "length"]` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`gen_ai.response.id`](/docs/attributes-registry/gen-ai.md) | string | The unique identifier for the completion. | `chatcmpl-123` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| [`gen_ai.response.model`](/docs/attributes-registry/gen-ai.md) | string | The name of the model that generated the response. [8] | `gpt-4-0613` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`gen_ai.response.model`](/docs/attributes-registry/gen-ai.md) | string | The name of the model that generated the response. [7] | `gpt-4-0613` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`gen_ai.usage.input_tokens`](/docs/attributes-registry/gen-ai.md) | int | The number of tokens used in the prompt sent to OpenAI. | `100` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`gen_ai.usage.output_tokens`](/docs/attributes-registry/gen-ai.md) | int | The number of tokens used in the completions from OpenAI. | `180` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| [`server.address`](/docs/attributes-registry/server.md) | string | GenAI server address. [9] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | `Recommended` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| [`server.address`](/docs/attributes-registry/server.md) | string | GenAI server address. [8] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | `Recommended` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | **[1]:** If one of the predefined values applies, but specific system uses a different name it's RECOMMENDED to document it in the semantic conventions for specific GenAI system and use system-specific name in the instrumentation. If a different name is not documented, instrumentation libraries SHOULD use applicable predefined value. **[2]:** The name of the GenAI model a request is being made to. If the model is supplied by a vendor, then the value must be the exact name of the model requested. If the model is a fine-tuned custom model, the value should have a more specific name than the base model that's been fine-tuned. -**[3]:** The `gen_ai.system` describes a family of GenAI models with specific model identified -by `gen_ai.request.model` and `gen_ai.response.model` attributes. - -The actual GenAI product may differ from the one identified by the client. -For example, when using OpenAI client libraries to communicate with Mistral, the `gen_ai.system` -is set to `openai` based on the instrumentation's best knowledge. - -For custom model, a custom friendly name SHOULD be used. -If none of these options apply, the `gen_ai.system` SHOULD be set to `_OTHER`. - -**[4]:** The `error.type` SHOULD match the error code returned by the Generative AI provider or the client library, +**[3]:** The `error.type` SHOULD match the error code returned by the Generative AI provider or the client library, the canonical name of exception that occurred, or another low-cardinality error identifier. Instrumentations SHOULD document the list of errors they report. -**[5]:** if the request includes a service_tier and the value is not 'auto' +**[4]:** if the request includes a service_tier and the value is not 'auto' -**[6]:** if the response was received and includes a service_tier +**[5]:** if the response was received and includes a service_tier -**[7]:** When observed from the client side, and when communicating through an intermediary, `server.port` SHOULD represent the server port behind any intermediaries, for example proxies, if it's available. +**[6]:** When observed from the client side, and when communicating through an intermediary, `server.port` SHOULD represent the server port behind any intermediaries, for example proxies, if it's available. -**[8]:** If available. The name of the GenAI model that provided the response. If the model is supplied by a vendor, then the value must be the exact name of the model actually used. If the model is a fine-tuned custom model, the value should have a more specific name than the base model that's been fine-tuned. +**[7]:** If available. The name of the GenAI model that provided the response. If the model is supplied by a vendor, then the value must be the exact name of the model actually used. If the model is a fine-tuned custom model, the value should have a more specific name than the base model that's been fine-tuned. -**[9]:** 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. +**[8]:** 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. @@ -120,23 +109,13 @@ Instrumentations SHOULD document the list of errors they report. | `text_completion` | Text completions operation such as [OpenAI Completions API (Legacy)](https://platform.openai.com/docs/api-reference/completions) | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -`gen_ai.system` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. - -| Value | Description | Stability | -|---|---|---| -| `anthropic` | Anthropic | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `cohere` | Cohere | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `openai` | OpenAI | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `vertex_ai` | Vertex AI | ![Experimental](https://img.shields.io/badge/-experimental-blue) | - - -## OpenAI Metric attributes +## OpenAI 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 ed193571b3..f8c5db65a7 100644 --- a/docs/graphql/graphql-spans.md +++ b/docs/graphql/graphql-spans.md @@ -9,10 +9,18 @@ linkTitle: GraphQL Server This document defines semantic conventions to apply when instrumenting the GraphQL implementation. They map GraphQL operations to attributes on a Span. -The **span name** MUST be of the format ` ` provided that -`graphql.operation.type` and `graphql.operation.name` are available. If `graphql.operation.name` is not available, the -span SHOULD be named ``. When `` is not available, `GraphQL Operation` -MAY be used as span name. +The **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. diff --git a/docs/messaging/azure-messaging.md b/docs/messaging/azure-messaging.md index 5ec7aa0812..729fc3cf97 100644 --- a/docs/messaging/azure-messaging.md +++ b/docs/messaging/azure-messaging.md @@ -29,7 +29,7 @@ The following additional attributes are defined: | [`messaging.batch.message_count`](/docs/attributes-registry/messaging.md) | int | The number of messages sent, received, or processed in the scope of the batching operation. [3] | `0`; `1`; `2` | `Conditionally Required` [4] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`messaging.destination.name`](/docs/attributes-registry/messaging.md) | string | The message destination name [5] | `MyQueue`; `MyTopic` | `Conditionally Required` [6] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`messaging.destination.subscription.name`](/docs/attributes-registry/messaging.md) | string | Azure Service Bus [subscription name](https://learn.microsoft.com/azure/service-bus-messaging/service-bus-queues-topics-subscriptions#topics-and-subscriptions). | `subscription-a` | `Conditionally Required` If messages are received from the subscription. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| [`messaging.operation.type`](/docs/attributes-registry/messaging.md) | string | A string identifying the type of the messaging operation. [7] | `send`; `create`; `receive` | `Conditionally Required` If applicable. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`messaging.operation.type`](/docs/attributes-registry/messaging.md) | string | A string identifying the type of the messaging operation. [7] | `create`; `send`; `receive` | `Conditionally Required` If applicable. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`messaging.servicebus.disposition_status`](/docs/attributes-registry/messaging.md) | string | Describes the [settlement type](https://learn.microsoft.com/azure/service-bus-messaging/message-transfers-locks-settlement#peeklock). | `complete`; `abandon`; `dead_letter` | `Conditionally Required` if and only if `messaging.operation` is `settle`. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`messaging.servicebus.message.delivery_count`](/docs/attributes-registry/messaging.md) | int | Number of deliveries that have been attempted for this message. | `2` | `Conditionally Required` [8] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`server.address`](/docs/attributes-registry/server.md) | string | Server domain name if available without reverse DNS lookup; otherwise, IP address or Unix domain socket name. [9] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | `Conditionally Required` If available. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | @@ -154,7 +154,7 @@ The following additional attributes are defined: | [`messaging.consumer.group.name`](/docs/attributes-registry/messaging.md) | string | Azure Event Hubs [consumer group name](https://learn.microsoft.com/en-us/azure/event-hubs/event-hubs-features#consumer-groups). | `my-group`; `indexer` | `Conditionally Required` On consumer spans. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`messaging.destination.name`](/docs/attributes-registry/messaging.md) | string | The message destination name [5] | `MyQueue`; `MyTopic` | `Conditionally Required` [6] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`messaging.destination.partition.id`](/docs/attributes-registry/messaging.md) | string | String representation of the partition id messages are sent to or received from, unique within the Event Hub. | `1` | `Conditionally Required` If available. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| [`messaging.operation.type`](/docs/attributes-registry/messaging.md) | string | A string identifying the type of the messaging operation. [7] | `send`; `create`; `receive` | `Conditionally Required` If applicable. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`messaging.operation.type`](/docs/attributes-registry/messaging.md) | string | A string identifying the type of the messaging operation. [7] | `create`; `send`; `receive` | `Conditionally Required` If applicable. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`server.address`](/docs/attributes-registry/server.md) | string | Server domain name if available without reverse DNS lookup; otherwise, IP address or Unix domain socket name. [8] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | `Conditionally Required` If available. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | | [`messaging.eventhubs.message.enqueued_time`](/docs/attributes-registry/messaging.md) | int | The UTC epoch seconds at which the message has been accepted and stored in the entity. | `1701393730` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`messaging.message.id`](/docs/attributes-registry/messaging.md) | string | A value used by the messaging system as an identifier for the message, represented as a string. | `452a7c7c7c7048c2f887f61572b18fc2` | `Recommended` If span describes operation on a single message. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | diff --git a/docs/messaging/gcp-pubsub.md b/docs/messaging/gcp-pubsub.md index 764b8545a9..261d32264b 100644 --- a/docs/messaging/gcp-pubsub.md +++ b/docs/messaging/gcp-pubsub.md @@ -28,7 +28,7 @@ For Google Cloud Pub/Sub, the following additional attributes are defined: | [`messaging.batch.message_count`](/docs/attributes-registry/messaging.md) | int | The number of messages sent, received, or processed in the scope of the batching operation. [3] | `0`; `1`; `2` | `Conditionally Required` [4] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`messaging.destination.name`](/docs/attributes-registry/messaging.md) | string | The message destination name [5] | `MyQueue`; `MyTopic` | `Conditionally Required` [6] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`messaging.gcp_pubsub.message.ordering_key`](/docs/attributes-registry/messaging.md) | string | The ordering key for a given message. If the attribute is not present, the message does not have an ordering key. | `ordering_key` | `Conditionally Required` If the message type has an ordering key set. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| [`messaging.operation.type`](/docs/attributes-registry/messaging.md) | string | A string identifying the type of the messaging operation. [7] | `send`; `create`; `receive` | `Conditionally Required` If applicable. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`messaging.operation.type`](/docs/attributes-registry/messaging.md) | string | A string identifying the type of the messaging operation. [7] | `create`; `send`; `receive` | `Conditionally Required` If applicable. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`server.address`](/docs/attributes-registry/server.md) | string | Server domain name if available without reverse DNS lookup; otherwise, IP address or Unix domain socket name. [8] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | `Conditionally Required` If available. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | | [`messaging.destination.subscription.name`](/docs/attributes-registry/messaging.md) | string | Google Pub/Sub [subscription name](https://cloud.google.com/pubsub/docs/subscription-overview). | `subscription-a` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`messaging.gcp_pubsub.message.ack_deadline`](/docs/attributes-registry/messaging.md) | int | The ack deadline in seconds set for the modify ack deadline request. | `10` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | diff --git a/docs/messaging/kafka.md b/docs/messaging/kafka.md index afa6264301..85856fa947 100644 --- a/docs/messaging/kafka.md +++ b/docs/messaging/kafka.md @@ -36,7 +36,7 @@ For Apache Kafka, the following additional attributes are defined: | [`messaging.batch.message_count`](/docs/attributes-registry/messaging.md) | int | The number of messages sent, received, or processed in the scope of the batching operation. [2] | `0`; `1`; `2` | `Conditionally Required` [3] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`messaging.destination.name`](/docs/attributes-registry/messaging.md) | string | The message destination name [4] | `MyQueue`; `MyTopic` | `Conditionally Required` [5] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`messaging.kafka.message.tombstone`](/docs/attributes-registry/messaging.md) | boolean | A boolean that is true if the message is a tombstone. | | `Conditionally Required` [6] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| [`messaging.operation.type`](/docs/attributes-registry/messaging.md) | string | A string identifying the type of the messaging operation. [7] | `send`; `create`; `receive` | `Conditionally Required` If applicable. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`messaging.operation.type`](/docs/attributes-registry/messaging.md) | string | A string identifying the type of the messaging operation. [7] | `create`; `send`; `receive` | `Conditionally Required` If applicable. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`server.address`](/docs/attributes-registry/server.md) | string | Server domain name if available without reverse DNS lookup; otherwise, IP address or Unix domain socket name. [8] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | `Conditionally Required` If available. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | | [`messaging.client.id`](/docs/attributes-registry/messaging.md) | string | A unique identifier for the client that consumes or produces a message. | `client-5`; `myhost@8742@s8083jm` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`messaging.consumer.group.name`](/docs/attributes-registry/messaging.md) | string | Kafka [consumer group id](https://docs.confluent.io/platform/current/clients/consumer.html). | `my-group`; `indexer` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | diff --git a/docs/messaging/messaging-metrics.md b/docs/messaging/messaging-metrics.md index 8ba501d626..5bfe6c5d1a 100644 --- a/docs/messaging/messaging-metrics.md +++ b/docs/messaging/messaging-metrics.md @@ -59,7 +59,7 @@ of `[ 0.005, 0.01, 0.025, 0.05, 0.075, 0.1, 0.25, 0.5, 0.75, 1, 2.5, 5, 7.5, 10 | [`messaging.destination.name`](/docs/attributes-registry/messaging.md) | string | The message destination name [4] | `MyQueue`; `MyTopic` | `Conditionally Required` [5] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`messaging.destination.subscription.name`](/docs/attributes-registry/messaging.md) | string | The name of the destination subscription from which a message is consumed. [6] | `subscription-a` | `Conditionally Required` if applicable. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`messaging.destination.template`](/docs/attributes-registry/messaging.md) | string | Low cardinality representation of the messaging destination name [7] | `/customers/{customerId}` | `Conditionally Required` if available. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| [`messaging.operation.type`](/docs/attributes-registry/messaging.md) | string | A string identifying the type of the messaging operation. [8] | `send`; `create`; `receive` | `Conditionally Required` If applicable. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`messaging.operation.type`](/docs/attributes-registry/messaging.md) | string | A string identifying the type of the messaging operation. [8] | `create`; `send`; `receive` | `Conditionally Required` If applicable. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`server.address`](/docs/attributes-registry/server.md) | string | Server domain name if available without reverse DNS lookup; otherwise, IP address or Unix domain socket name. [9] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | `Conditionally Required` If available. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | | [`messaging.destination.partition.id`](/docs/attributes-registry/messaging.md) | string | The identifier of the partition messages are sent to or received from, unique within the `messaging.destination.name`. | `1` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`server.port`](/docs/attributes-registry/server.md) | int | Server port number. [10] | `80`; `8080`; `443` | `Recommended` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | diff --git a/docs/messaging/messaging-spans.md b/docs/messaging/messaging-spans.md index 6527a2bf2e..149b77e71d 100644 --- a/docs/messaging/messaging-spans.md +++ b/docs/messaging/messaging-spans.md @@ -353,7 +353,7 @@ Messaging system-specific attributes MUST be defined in the corresponding `messa | [`messaging.destination.subscription.name`](/docs/attributes-registry/messaging.md) | string | The name of the destination subscription from which a message is consumed. [9] | `subscription-a` | `Conditionally Required` If applicable. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`messaging.destination.template`](/docs/attributes-registry/messaging.md) | string | Low cardinality representation of the messaging destination name [10] | `/customers/{customerId}` | `Conditionally Required` [11] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`messaging.destination.temporary`](/docs/attributes-registry/messaging.md) | boolean | A boolean that is true if the message destination is temporary and might not exist anymore after messages are processed. | | `Conditionally Required` [12] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| [`messaging.operation.type`](/docs/attributes-registry/messaging.md) | string | A string identifying the type of the messaging operation. [13] | `send`; `create`; `receive` | `Conditionally Required` If applicable. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`messaging.operation.type`](/docs/attributes-registry/messaging.md) | string | A string identifying the type of the messaging operation. [13] | `create`; `send`; `receive` | `Conditionally Required` If applicable. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`server.address`](/docs/attributes-registry/server.md) | string | Server domain name if available without reverse DNS lookup; otherwise, IP address or Unix domain socket name. [14] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | `Conditionally Required` If available. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | | [`messaging.client.id`](/docs/attributes-registry/messaging.md) | string | A unique identifier for the client that consumes or produces a message. | `client-5`; `myhost@8742@s8083jm` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`messaging.destination.partition.id`](/docs/attributes-registry/messaging.md) | string | The identifier of the partition messages are sent to or received from, unique within the `messaging.destination.name`. | `1` | `Recommended` When applicable. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | diff --git a/docs/messaging/rabbitmq.md b/docs/messaging/rabbitmq.md index 07c3a56249..4c808619d2 100644 --- a/docs/messaging/rabbitmq.md +++ b/docs/messaging/rabbitmq.md @@ -27,7 +27,7 @@ In RabbitMQ, the destination is defined by an *exchange* and a *routing key*. | [`messaging.operation.name`](/docs/attributes-registry/messaging.md) | string | The system-specific name of the messaging operation. | `ack`; `nack`; `send` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`error.type`](/docs/attributes-registry/error.md) | string | Describes a class of error the operation ended with. [1] | `amqp:decode-error`; `KAFKA_STORAGE_ERROR`; `channel-error` | `Conditionally Required` If and only if the messaging operation has failed. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | | [`messaging.destination.name`](/docs/attributes-registry/messaging.md) | string | The message destination name [2] | `MyQueue`; `MyTopic` | `Conditionally Required` [3] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| [`messaging.operation.type`](/docs/attributes-registry/messaging.md) | string | A string identifying the type of the messaging operation. [4] | `send`; `create`; `receive` | `Conditionally Required` If applicable. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`messaging.operation.type`](/docs/attributes-registry/messaging.md) | string | A string identifying the type of the messaging operation. [4] | `create`; `send`; `receive` | `Conditionally Required` If applicable. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`messaging.rabbitmq.destination.routing_key`](/docs/attributes-registry/messaging.md) | string | RabbitMQ message routing key. | `myKey` | `Conditionally Required` If not empty. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`messaging.rabbitmq.message.delivery_tag`](/docs/attributes-registry/messaging.md) | int | RabbitMQ message delivery tag | `123` | `Conditionally Required` When available. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`server.address`](/docs/attributes-registry/server.md) | string | Server domain name if available without reverse DNS lookup; otherwise, IP address or Unix domain socket name. [5] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | `Conditionally Required` If available. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | diff --git a/docs/messaging/rocketmq.md b/docs/messaging/rocketmq.md index 0dc0564a44..ddbd2f514b 100644 --- a/docs/messaging/rocketmq.md +++ b/docs/messaging/rocketmq.md @@ -29,7 +29,7 @@ Specific attributes for Apache RocketMQ are defined below. | [`error.type`](/docs/attributes-registry/error.md) | string | Describes a class of error the operation ended with. [1] | `amqp:decode-error`; `KAFKA_STORAGE_ERROR`; `channel-error` | `Conditionally Required` If and only if the messaging operation has failed. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | | [`messaging.batch.message_count`](/docs/attributes-registry/messaging.md) | int | The number of messages sent, received, or processed in the scope of the batching operation. [2] | `0`; `1`; `2` | `Conditionally Required` [3] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`messaging.destination.name`](/docs/attributes-registry/messaging.md) | string | The message destination name [4] | `MyQueue`; `MyTopic` | `Conditionally Required` [5] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| [`messaging.operation.type`](/docs/attributes-registry/messaging.md) | string | A string identifying the type of the messaging operation. [6] | `send`; `create`; `receive` | `Conditionally Required` If applicable. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`messaging.operation.type`](/docs/attributes-registry/messaging.md) | string | A string identifying the type of the messaging operation. [6] | `create`; `send`; `receive` | `Conditionally Required` If applicable. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`messaging.rocketmq.message.delay_time_level`](/docs/attributes-registry/messaging.md) | int | The delay time level for delay message, which determines the message delay time. | `3` | `Conditionally Required` [7] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`messaging.rocketmq.message.delivery_timestamp`](/docs/attributes-registry/messaging.md) | int | The timestamp in milliseconds that the delay message is expected to be delivered to consumer. | `1665987217045` | `Conditionally Required` [8] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`messaging.rocketmq.message.group`](/docs/attributes-registry/messaging.md) | string | It is essential for FIFO message. Messages that belong to the same message group are always processed one by one within the same consumer group. | `myMessageGroup` | `Conditionally Required` If the message type is FIFO. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | diff --git a/docs/non-normative/db-migration.md b/docs/non-normative/db-migration.md new file mode 100644 index 0000000000..eee1011900 --- /dev/null +++ b/docs/non-normative/db-migration.md @@ -0,0 +1,251 @@ +# Database semantic convention stability migration guide + +Due to the significant number of modifications and the extensive user base +affected by them, existing database instrumentations published by +OpenTelemetry are required to implement a migration plan that will assist users in +transitioning to the stable database semantic conventions. + +Specifically, when existing database instrumentations published by OpenTelemetry are +updated to the stable database semantic conventions, they: + +- SHOULD introduce an environment variable `OTEL_SEMCONV_STABILITY_OPT_IN` in + their existing major version, which accepts: + - `database` - emit the stable database conventions, and stop emitting + the old database conventions that the instrumentation emitted previously. + - `database/dup` - emit both the old and the stable database conventions, + allowing for a phased rollout of the stable semantic conventions. + - The default behavior (in the absence of one of these values) is to continue + emitting whatever version of the old database conventions the + instrumentation was emitting previously. +- Need to maintain (security patching at a minimum) their existing major version + for at least six months after it starts emitting both sets of conventions. +- May drop the environment variable in their next major version and emit only + the stable database conventions. + +## Summary of changes + +This section summarizes the changes made to the HTTP semantic conventions +from +[v1.24.0](https://github.com/open-telemetry/semantic-conventions/blob/v1.24.0/docs/database/README.md). +to +[v1.28.0 (RC)](https://github.com/open-telemetry/semantic-conventions/blob/v1.28.0/docs/database/README.md). + +### Database client span attributes + + +| Change | Comments | +|-----------------------------------------------------|-------------------------------------------------------------------------------------------------------------| +| `db.connection_string` | Removed | +| `db.user` | Removed | +| `network.transport` | Removed | +| `network.type` | Removed | +| `db.name` | Removed, integrated into the new `db.namespace` | +| `db.redis.database_index` | Removed, integrated into the new `db.namespace` | +| `db.mssql.instance_name` | Removed, integrated into the new `db.namespace` | +| `db.instance.id` | Removed, replaced by `server.address` or integrated into `db.namespace` as appropriate | +| `db.statement` → `db.query.text` | Clarified, SHOULD be collected by default only if there is sanitization that excludes sensitive information | +| `db.operation` → `db.operation.name` | | +| `db.sql.table` → `db.collection.name` | | +| `db.cassandra.table` → `db.collection.name` | | +| `db.mongodb.collection` → `db.collection.name` | | +| `db.cosmosdb.container` → `db.collection.name` | | +| New: `db.operation.batch.size` | | +| New: `db.response.status_code` | | +| New: `db.query.parameter.` | Opt-In | +| New: `error.type` | | + + +References: + +- [Database client span attributes v1.24.0](https://github.com/open-telemetry/semantic-conventions/blob/v1.24.0/docs/database/database-spans.md) +- [Database client span attributes v1.28.0 (RC)](https://github.com/open-telemetry/semantic-conventions/blob/v1.28.0/docs/database/database-spans.md) + +### Database client span names + +The recommended span name has changed to `{db.operation.name} {target}`, where the `{target}` SHOULD describe the entity +that the operation is performed against and SHOULD adhere to one of the following values, provided they are accessible: + +- `db.collection.name` SHOULD be used for data manipulation operations or operations on database collections +- `db.namespace` SHOULD be used for operations on a specific database namespace +- `server.address:server.port` SHOULD be used for other operations not targeting any specific database(s) or collection(s) + +References: + +- [Database client span names v1.24.0](https://github.com/open-telemetry/semantic-conventions/blob/v1.24.0/docs/database/database-spans.md) +- [Database client span names v1.28.0 (RC)](https://github.com/open-telemetry/semantic-conventions/blob/v1.28.0/docs/database/database-spans.md#name) + +### Database client operation duration metric + +This is a required metric. There was no similar metric previously. + +See [Metric `db.client.operation.duration` v1.28.0 (RC)](https://github.com/open-telemetry/semantic-conventions/blob/v1.28.0/docs/database/database-metrics.md#metric-dbclientoperationduration). + +### Experimental connection metrics + +Database connection metrics are still experimental, but there have been several changes in the latest release. + +#### Database client connection count + +Metric changes: + +- **Name**: `db.client.connections.usage` → `db.client.connection.count` +- **Attributes**: see table below + + +| Attribute change | Comments | +|-----------------------------------------------------|----------| +| `pool.name` → `db.client.connection.pool.name` | | +| `state` → `db.client.connection.state` | | + + +References: + +- [Metric `db.client.connections.usage` v1.24.0](https://github.com/open-telemetry/semantic-conventions/blob/v1.24.0/docs/database/database-metrics.md#metric-dbclientconnectionsusage) +- [Metric `db.client.connection.count` v1.28.0 (RC)](https://github.com/open-telemetry/semantic-conventions/blob/v1.28.0/docs/database/database-metrics.md#metric-dbclientconnectioncount) + +#### Database client connection idle max + +Metric changes: + +- **Name**: `db.client.connections.idle.max` → `db.client.connection.idle.max` +- **Attributes**: see table below + + +| Attribute change | Comments | +|-----------------------------------------------------|----------| +| `pool.name` → `db.client.connection.pool.name` | | + + +References: + +- [Metric `db.client.connections.idle.max` v1.24.0](https://github.com/open-telemetry/semantic-conventions/blob/v1.24.0/docs/database/database-metrics.md#metric-dbclientconnectionsidlemax) +- [Metric `db.client.connection.idle.max` v1.28.0 (RC)](https://github.com/open-telemetry/semantic-conventions/blob/v1.28.0/docs/database/database-metrics.md#metric-dbclientconnectionidlemax) + +#### Database client connection idle min + +Metric changes: + +- **Name**: `db.client.connections.idle.min` → `db.client.connection.idle.min` +- **Attributes**: see table below + + +| Attribute change | Comments | +|-----------------------------------------------------|----------| +| `pool.name` → `db.client.connection.pool.name` | | + + +References: + +- [Metric `db.client.connections.idle.min` v1.24.0](https://github.com/open-telemetry/semantic-conventions/blob/v1.24.0/docs/database/database-metrics.md#metric-dbclientconnectionsidlemin) +- [Metric `db.client.connection.idle.min` v1.28.0 (RC)](https://github.com/open-telemetry/semantic-conventions/blob/v1.28.0/docs/database/database-metrics.md#metric-dbclientconnectionidlemin) + +#### Database client connection max + +Metric changes: + +- **Name**: `db.client.connections.max` → `db.client.connection.max` +- **Attributes**: see table below + + +| Attribute change | Comments | +|-----------------------------------------------------|----------| +| `pool.name` → `db.client.connection.pool.name` | | + + +References: + +- [Metric `db.client.connections.max` v1.24.0](https://github.com/open-telemetry/semantic-conventions/blob/v1.24.0/docs/database/database-metrics.md#metric-dbclientconnectionsmax) +- [Metric `db.client.connection.max` v1.28.0 (RC)](https://github.com/open-telemetry/semantic-conventions/blob/v1.28.0/docs/database/database-metrics.md#metric-dbclientconnectionmax) + +#### Database client connection pending requests + +Metric changes: + +- **Name**: `db.client.connections.pending_requests` → `db.client.connection.pending_requests` +- **Attributes**: see table below + + +| Attribute change | Comments | +|-----------------------------------------------------|----------| +| `pool.name` → `db.client.connection.pool.name` | | + + +References: + +- [Metric `db.client.connections.pending_requests` v1.24.0](https://github.com/open-telemetry/semantic-conventions/blob/v1.24.0/docs/database/database-metrics.md#metric-dbclientconnectionspending_requests) +- [Metric `db.client.connection.pending_requests` v1.28.0 (RC)](https://github.com/open-telemetry/semantic-conventions/blob/v1.28.0/docs/database/database-metrics.md#metric-dbclientconnectionpending_requests) + +#### Database client connection timeouts + +Metric changes: + +- **Name**: `db.client.connections.timeouts` → `db.client.connection.timeouts` +- **Attributes**: see table below + + +| Attribute change | Comments | +|-----------------------------------------------------|----------| +| `pool.name` → `db.client.connection.pool.name` | | + + +References: + +- [Metric `db.client.connections.timeouts` v1.24.0](https://github.com/open-telemetry/semantic-conventions/blob/v1.24.0/docs/database/database-metrics.md#metric-dbclientconnectionstimeouts) +- [Metric `db.client.connection.timeouts` v1.28.0 (RC)](https://github.com/open-telemetry/semantic-conventions/blob/v1.28.0/docs/database/database-metrics.md#metric-dbclientconnectiontimeouts) + +#### Database client connection create time + +Metric changes: + +- **Name**: `db.client.connections.create_time` → `db.client.connection.create_time` +- **Unit**: `ms` → `s` +- **Attributes**: see table below + + +| Attribute change | Comments | +|-----------------------------------------------------|----------| +| `pool.name` → `db.client.connection.pool.name` | | + + +References: + +- [Metric `db.client.connections.create_time` v1.24.0](https://github.com/open-telemetry/semantic-conventions/blob/v1.24.0/docs/database/database-metrics.md#metric-dbclientconnectionscreate_time) +- [Metric `db.client.connection.create_time` v1.28.0 (RC)](https://github.com/open-telemetry/semantic-conventions/blob/v1.28.0/docs/database/database-metrics.md#metric-dbclientconnectioncreate_time) + +#### Database client connection wait time + +Metric changes: + +- **Name**: `db.client.connections.wait_time` → `db.client.connection.wait_time` +- **Unit**: `ms` → `s` +- **Attributes**: see table below + + +| Attribute change | Comments | +|-----------------------------------------------------|----------| +| `pool.name` → `db.client.connection.pool.name` | | + + +References: + +- [Metric `db.client.connections.wait_time` v1.24.0](https://github.com/open-telemetry/semantic-conventions/blob/v1.24.0/docs/database/database-metrics.md#metric-dbclientconnectionswait_time) +- [Metric `db.client.connection.wait_time` v1.28.0 (RC)](https://github.com/open-telemetry/semantic-conventions/blob/v1.28.0/docs/database/database-metrics.md#metric-dbclientconnectionwait_time) + +#### Database client connection use time + +Metric changes: + +- **Name**: `db.client.connections.use_time` → `db.client.connection.use_time` +- **Unit**: `ms` → `s` +- **Attributes**: see table below + + +| Attribute change | Comments | +|-----------------------------------------------------|----------| +| `pool.name` → `db.client.connection.pool.name` | | + + +References: + +- [Metric `db.client.connections.use_time` v1.24.0](https://github.com/open-telemetry/semantic-conventions/blob/v1.24.0/docs/database/database-metrics.md#metric-dbclientconnectionsuse_time) +- [Metric `db.client.connection.use_time` v1.28.0 (RC)](https://github.com/open-telemetry/semantic-conventions/blob/v1.28.0/docs/database/database-metrics.md#metric-dbclientconnectionuse_time) diff --git a/model/cloudfoundry/registry.yaml b/model/cloudfoundry/registry.yaml index c360d69335..cf1a2f65b6 100644 --- a/model/cloudfoundry/registry.yaml +++ b/model/cloudfoundry/registry.yaml @@ -62,7 +62,7 @@ groups: brief: > The index of the application instance. 0 when just one instance is active. note: | - CloudFoundry defines the `instance_id` in the [Loggegator v2 envelope](https://github.com/cloudfoundry/loggregator-api#v2-envelope). + CloudFoundry defines the `instance_id` in the [Loggregator v2 envelope](https://github.com/cloudfoundry/loggregator-api#v2-envelope). It is used for logs and metrics emitted by CloudFoundry. It is supposed to contain the application instance index for applications deployed on the runtime. diff --git a/model/gen-ai/metrics.yaml b/model/gen-ai/metrics.yaml index cbd22ebc70..35b5c979bc 100644 --- a/model/gen-ai/metrics.yaml +++ b/model/gen-ai/metrics.yaml @@ -13,7 +13,8 @@ groups: - ref: gen_ai.response.model requirement_level: recommended - ref: gen_ai.request.model - requirement_level: required + requirement_level: + conditionally_required: If available. - ref: gen_ai.system requirement_level: required - ref: gen_ai.operation.name diff --git a/model/gen-ai/registry.yaml b/model/gen-ai/registry.yaml index 816f457093..a1e86b75fc 100644 --- a/model/gen-ai/registry.yaml +++ b/model/gen-ai/registry.yaml @@ -25,6 +25,10 @@ groups: stability: experimental value: "cohere" brief: 'Cohere' + - id: az.ai.inference + stability: experimental + value: "az.ai.inference" + brief: 'Azure AI Inference' brief: The Generative AI product as identified by the client or server instrumentation. note: | The `gen_ai.system` describes a family of GenAI models with specific model identified diff --git a/model/gen-ai/spans.yaml b/model/gen-ai/spans.yaml index 86ddfc4a82..79909f0f3c 100644 --- a/model/gen-ai/spans.yaml +++ b/model/gen-ai/spans.yaml @@ -1,13 +1,13 @@ groups: - - id: trace.gen_ai.client.common - type: span + - id: trace.gen_ai.client.common_attributes + type: attribute_group + stability: experimental brief: > Describes GenAI operation span. attributes: - - ref: gen_ai.system - requirement_level: required - ref: gen_ai.request.model - requirement_level: required + requirement_level: + conditionally_required: If available. note: > The name of the GenAI model a request is being made to. If the model is supplied by a vendor, then the value must be the exact name of the model requested. If the model is a fine-tuned @@ -54,20 +54,30 @@ groups: The `error.type` SHOULD match the error code returned by the Generative AI provider or the client library, the canonical name of exception that occurred, or another low-cardinality error identifier. Instrumentations SHOULD document the list of errors they report. - - - id: trace.gen_ai.client - extends: trace.gen_ai.client.common + - id: trace.gen_ai.client.span + type: span + stability: experimental brief: > - Describes a GenAI operation span. + Describes GenAI operation span. + extends: trace.gen_ai.client.common_attributes attributes: + - ref: gen_ai.system + # TODO: Not adding to trace.gen_ai.client.common_attributes because of https://github.com/open-telemetry/build-tools/issues/192 + requirement_level: required - ref: gen_ai.request.top_k requirement_level: recommended + events: + - gen_ai.content.prompt + - gen_ai.content.completion - id: trace.gen_ai.openai.client - extends: trace.gen_ai.client.common + extends: trace.gen_ai.client.common_attributes + stability: experimental brief: > Describes an OpenAI operation span. attributes: + - ref: gen_ai.request.model + requirement_level: required - ref: gen_ai.openai.request.seed requirement_level: conditionally_required: if the request includes a seed @@ -84,3 +94,25 @@ groups: brief: The number of tokens used in the prompt sent to OpenAI. - ref: gen_ai.usage.output_tokens brief: The number of tokens used in the completions from OpenAI. + + - id: trace.gen_ai.az.ai.inference.client + extends: trace.gen_ai.client.common_attributes + stability: experimental + type: attribute_group + brief: > + Describes Azure AI Inference span attributes. + attributes: + - ref: az.namespace + note: > + When `az.namespace` attribute is populated, it MUST be set to `Microsoft.CognitiveServices` for all + operations performed by Azure AI Inference clients. + examples: ["Microsoft.CognitiveServices"] + - ref: gen_ai.usage.input_tokens + brief: > + The number of prompt tokens as reported in the usage prompt_tokens property of the response. + - ref: gen_ai.usage.output_tokens + brief: > + The number of completion tokens as reported in the usage completion_tokens property of the response. + - ref: server.port + requirement_level: + conditionally_required: If not default (443).