diff --git a/.chloggen/1469.yaml b/.chloggen/1469.yaml new file mode 100644 index 0000000000..7d7b4ba5cc --- /dev/null +++ b/.chloggen/1469.yaml @@ -0,0 +1,5 @@ +change_type: 'enhancement' +component: gen_ai +note: Yamlify gen_ai events and clean up examples. + +issues: [1469] diff --git a/.chloggen/1646.yaml b/.chloggen/1646.yaml new file mode 100644 index 0000000000..778acd9c9a --- /dev/null +++ b/.chloggen/1646.yaml @@ -0,0 +1,4 @@ +change_type: breaking +component: event +note: Deprecate `event.name` attribute in favor of the top level event name property on the log record +issues: [1646] diff --git a/.chloggen/aws.extended_request_id.yaml b/.chloggen/aws.extended_request_id.yaml new file mode 100644 index 0000000000..3b0e7bd0f5 --- /dev/null +++ b/.chloggen/aws.extended_request_id.yaml @@ -0,0 +1,22 @@ +# Use this changelog template to create an entry for release notes. +# +# If your change doesn't affect end users you should instead start +# your pull request title with [chore] or use the "Skip Changelog" label. + +# One of 'breaking', 'deprecation', 'new_component', 'enhancement', 'bug_fix' +change_type: enhancement + +# The name of the area of concern in the attributes-registry, (e.g. http, cloud, db) +component: aws + +# A brief description of the change. Surround your text with quotes ("") if it needs to start with a backtick (`). +note: Add extended request ID to general AWS attributes as `aws.extended_request_id` + +# Mandatory: One or more tracking issues related to the change. You can use the PR number here if no issue exists. +# The values here must be integers. +issues: [1670] + +# (Optional) One or more lines of additional information to render under the primary note. +# These lines will be padded with 2 spaces and then inserted directly into the document. +# Use pipe (|) for multiline entries. +subtext: diff --git a/.chloggen/clarify-temporary-destination.yaml b/.chloggen/clarify-temporary-destination.yaml new file mode 100644 index 0000000000..fb6d9e52b9 --- /dev/null +++ b/.chloggen/clarify-temporary-destination.yaml @@ -0,0 +1,5 @@ +change_type: enhancement +component: messaging +note: Further clarify `{destination}` value on span names +issues: [1635] +subtext: diff --git a/.github/ISSUE_TEMPLATE/bug_report.yaml b/.github/ISSUE_TEMPLATE/bug_report.yaml index d65a7ffc55..43a6c3c748 100644 --- a/.github/ISSUE_TEMPLATE/bug_report.yaml +++ b/.github/ISSUE_TEMPLATE/bug_report.yaml @@ -42,7 +42,6 @@ body: - area:dns - area:dotnet - area:error - - area:event - area:exception - area:faas - area:feature-flag diff --git a/.github/ISSUE_TEMPLATE/change_proposal.yaml b/.github/ISSUE_TEMPLATE/change_proposal.yaml index 920ab75c84..bb0d28736a 100644 --- a/.github/ISSUE_TEMPLATE/change_proposal.yaml +++ b/.github/ISSUE_TEMPLATE/change_proposal.yaml @@ -34,7 +34,6 @@ body: - area:dns - area:dotnet - area:error - - area:event - area:exception - area:faas - area:feature-flag diff --git a/.github/ISSUE_TEMPLATE/new-conventions.yaml b/.github/ISSUE_TEMPLATE/new-conventions.yaml index e63b412b75..eb43279195 100644 --- a/.github/ISSUE_TEMPLATE/new-conventions.yaml +++ b/.github/ISSUE_TEMPLATE/new-conventions.yaml @@ -43,7 +43,6 @@ body: - area:dns - area:dotnet - area:error - - area:event - area:exception - area:faas - area:feature-flag diff --git a/.markdown_link_check_config.json b/.markdown_link_check_config.json index e85f6c0b20..980cc95414 100644 --- a/.markdown_link_check_config.json +++ b/.markdown_link_check_config.json @@ -6,6 +6,9 @@ { "pattern": "^https://github\\.com/open-telemetry/semantic-conventions/(issues|pull|actions)" }, + { + "pattern": "^https://blogs.oracle.com/linux/post/understanding-linux-kernel-memory-statistics$" + }, { "pattern": "^#" } diff --git a/.vscode/settings.json b/.vscode/settings.json index 20f2b1ea67..069acb27c7 100644 --- a/.vscode/settings.json +++ b/.vscode/settings.json @@ -10,7 +10,7 @@ "MD040": false, }, "yaml.schemas": { - "https://raw.githubusercontent.com/open-telemetry/weaver/v0.11.0/schemas/semconv.schema.json": [ + "https://raw.githubusercontent.com/open-telemetry/weaver/v0.12.0/schemas/semconv.schema.json": [ "model/**/*.yaml" ] }, diff --git a/dependencies.Dockerfile b/dependencies.Dockerfile index a73ff3d3a2..18b420c661 100644 --- a/dependencies.Dockerfile +++ b/dependencies.Dockerfile @@ -3,7 +3,7 @@ # Dependabot can keep this file up to date with latest containers. # Weaver is used to generate markdown docs, and enforce policies on the model. -FROM otel/weaver:v0.11.0 AS weaver +FROM otel/weaver:v0.12.0 AS weaver # OPA is used to test policies enforced by weaver. FROM openpolicyagent/opa:0.70.0 AS opa diff --git a/docs/attributes-registry/aws.md b/docs/attributes-registry/aws.md index 536abd31fb..ed5fdca4e2 100644 --- a/docs/attributes-registry/aws.md +++ b/docs/attributes-registry/aws.md @@ -20,6 +20,7 @@ This document defines generic attributes for AWS services. | Attribute | Type | Description | Examples | Stability | |---|---|---|---|---| +| `aws.extended_request_id` | string | The AWS extended request ID as returned in the response header `x-amz-id-2`. | `wzHcyEWfmOGDIE5QOhTAqFDoDWP3y8IUvpNINCwL9N4TEHbUw0/gZJ+VZTmCNCWR7fezEN3eCiQ=` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `aws.request_id` | string | The AWS request ID as returned in the response headers `x-amz-request-id` or `x-amz-requestid`. | `79b9da39-b7ae-508a-a6bc-864b2829c622`; `C9ER4AJX75574TDJ` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | ## Amazon DynamoDB Attributes diff --git a/docs/attributes-registry/azure.md b/docs/attributes-registry/azure.md index 78cd3a030d..2ebfa58cfc 100644 --- a/docs/attributes-registry/azure.md +++ b/docs/attributes-registry/azure.md @@ -6,7 +6,7 @@ # Azure -## Azure Sdk Attributes +## Azure SDK Attributes This document defines generic attributes for Azure SDK. diff --git a/docs/attributes-registry/cicd.md b/docs/attributes-registry/cicd.md index e42bf16360..8b585d8fe4 100644 --- a/docs/attributes-registry/cicd.md +++ b/docs/attributes-registry/cicd.md @@ -6,7 +6,7 @@ # CICD -## CICD Pipeline Attributes +## CI/CD Pipeline Attributes This group describes attributes specific to pipelines within a Continuous Integration and Continuous Deployment (CI/CD) system. A [pipeline](https://wikipedia.org/wiki/Pipeline_(computing)) in this case is a series of steps that are performed in order to deliver a new version of software. This aligns with the [Britannica](https://www.britannica.com/dictionary/pipeline) definition of a pipeline where a **pipeline** is the system for developing and producing something. In the context of CI/CD, a pipeline produces or delivers software. diff --git a/docs/attributes-registry/event.md b/docs/attributes-registry/event.md index 4489039554..7b00cb83c5 100644 --- a/docs/attributes-registry/event.md +++ b/docs/attributes-registry/event.md @@ -12,6 +12,4 @@ Attributes for Events represented using Log Records. | Attribute | Type | Description | Examples | Stability | |---|---|---|---|---| -| `event.name` | string | Identifies the class / type of event. [1] | `browser.mouse.click`; `device.app.lifecycle` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | - -**[1] `event.name`:** Event names are subject to the same rules as [attribute names](/docs/general/attribute-naming.md). Notably, event names are namespaced to avoid collisions and provide a clean separation of semantics for events in separate domains like browser, mobile, and kubernetes. +| `event.name` | string | Identifies the class / type of event. | `browser.mouse.click`; `device.app.lifecycle` | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Replaced by EventName top-level field on the LogRecord | diff --git a/docs/attributes-registry/process.md b/docs/attributes-registry/process.md index 31ef1a611a..4ba9cdb3aa 100644 --- a/docs/attributes-registry/process.md +++ b/docs/attributes-registry/process.md @@ -81,7 +81,7 @@ Describes Linux Process attributes |---|---|---|---|---| | `process.linux.cgroup` | string | The control group associated with the process. [4] | `1:name=systemd:/user.slice/user-1000.slice/session-3.scope`; `0::/user.slice/user-1000.slice/user@1000.service/tmux-spawn-0267755b-4639-4a27-90ed-f19f88e53748.scope` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -**[4] `process.linux.cgroup`:** Control groups (cgroups) are a kernel feature used to organize and manage process resources. This attribute provides the path(s) to the cgroup(s) associated with the process, which should match the contents of the [/proc//cgroup](https://man7.org/linux/man-pages/man7/cgroups.7.html) file. +**[4] `process.linux.cgroup`:** Control groups (cgroups) are a kernel feature used to organize and manage process resources. This attribute provides the path(s) to the cgroup(s) associated with the process, which should match the contents of the [/proc/\[PID\]/cgroup](https://man7.org/linux/man-pages/man7/cgroups.7.html) file. ## Deprecated Process Attributes diff --git a/docs/cloud-providers/aws-sdk.md b/docs/cloud-providers/aws-sdk.md index 8be12e8172..498f6c77a0 100644 --- a/docs/cloud-providers/aws-sdk.md +++ b/docs/cloud-providers/aws-sdk.md @@ -34,6 +34,7 @@ with the naming guidelines for RPC client spans. | Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | |---|---|---|---|---|---| | [`rpc.system`](/docs/attributes-registry/rpc.md) | string | The value `aws-api`. | `aws-api` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`aws.extended_request_id`](/docs/attributes-registry/aws.md) | string | The AWS extended request ID as returned in the response header `x-amz-id-2`. | `wzHcyEWfmOGDIE5QOhTAqFDoDWP3y8IUvpNINCwL9N4TEHbUw0/gZJ+VZTmCNCWR7fezEN3eCiQ=` | `Conditionally Required` If available. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`aws.request_id`](/docs/attributes-registry/aws.md) | string | The AWS request ID as returned in the response headers `x-amz-request-id` or `x-amz-requestid`. | `79b9da39-b7ae-508a-a6bc-864b2829c622`; `C9ER4AJX75574TDJ` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`rpc.method`](/docs/attributes-registry/rpc.md) | string | The name of the operation corresponding to the request, as returned by the AWS SDK [1] | `GetItem`; `PutItem` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`rpc.service`](/docs/attributes-registry/rpc.md) | string | The name of the service to which a request is made, as returned by the AWS SDK. [2] | `DynamoDB`; `S3` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | diff --git a/docs/database/dynamodb.md b/docs/database/dynamodb.md index 14d7ce3425..e5547f9338 100644 --- a/docs/database/dynamodb.md +++ b/docs/database/dynamodb.md @@ -23,6 +23,7 @@ The Semantic Conventions for [AWS DynamoDB](https://aws.amazon.com/dynamodb/) ex | Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | |---|---|---|---|---|---| | [`rpc.system`](/docs/attributes-registry/rpc.md) | string | The value `aws-api`. | `aws-api` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`aws.extended_request_id`](/docs/attributes-registry/aws.md) | string | The AWS extended request ID as returned in the response header `x-amz-id-2`. | `wzHcyEWfmOGDIE5QOhTAqFDoDWP3y8IUvpNINCwL9N4TEHbUw0/gZJ+VZTmCNCWR7fezEN3eCiQ=` | `Conditionally Required` If available. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`aws.dynamodb.consumed_capacity`](/docs/attributes-registry/aws.md) | string[] | The JSON-serialized value of each item in the `ConsumedCapacity` response field. | `["{ \"CapacityUnits\": number, \"GlobalSecondaryIndexes\": { \"string\" : { \"CapacityUnits\": number, \"ReadCapacityUnits\": number, \"WriteCapacityUnits\": number } }, \"LocalSecondaryIndexes\": { \"string\" : { \"CapacityUnits\": number, \"ReadCapacityUnits\": number, \"WriteCapacityUnits\": number } }, \"ReadCapacityUnits\": number, \"Table\": { \"CapacityUnits\": number, \"ReadCapacityUnits\": number, \"WriteCapacityUnits\": number }, \"TableName\": \"string\", \"WriteCapacityUnits\": number }"]` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`aws.dynamodb.table_names`](/docs/attributes-registry/aws.md) | string[] | The keys in the `RequestItems` object field. | `["Users", "Cats"]` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`aws.request_id`](/docs/attributes-registry/aws.md) | string | The AWS request ID as returned in the response headers `x-amz-request-id` or `x-amz-requestid`. | `79b9da39-b7ae-508a-a6bc-864b2829c622`; `C9ER4AJX75574TDJ` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | @@ -62,6 +63,7 @@ The Semantic Conventions for [AWS DynamoDB](https://aws.amazon.com/dynamodb/) ex | Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | |---|---|---|---|---|---| | [`rpc.system`](/docs/attributes-registry/rpc.md) | string | The value `aws-api`. | `aws-api` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`aws.extended_request_id`](/docs/attributes-registry/aws.md) | string | The AWS extended request ID as returned in the response header `x-amz-id-2`. | `wzHcyEWfmOGDIE5QOhTAqFDoDWP3y8IUvpNINCwL9N4TEHbUw0/gZJ+VZTmCNCWR7fezEN3eCiQ=` | `Conditionally Required` If available. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`aws.dynamodb.consumed_capacity`](/docs/attributes-registry/aws.md) | string[] | The JSON-serialized value of each item in the `ConsumedCapacity` response field. | `["{ \"CapacityUnits\": number, \"GlobalSecondaryIndexes\": { \"string\" : { \"CapacityUnits\": number, \"ReadCapacityUnits\": number, \"WriteCapacityUnits\": number } }, \"LocalSecondaryIndexes\": { \"string\" : { \"CapacityUnits\": number, \"ReadCapacityUnits\": number, \"WriteCapacityUnits\": number } }, \"ReadCapacityUnits\": number, \"Table\": { \"CapacityUnits\": number, \"ReadCapacityUnits\": number, \"WriteCapacityUnits\": number }, \"TableName\": \"string\", \"WriteCapacityUnits\": number }"]` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`aws.dynamodb.item_collection_metrics`](/docs/attributes-registry/aws.md) | string | The JSON-serialized value of the `ItemCollectionMetrics` response field. | `{ "string" : [ { "ItemCollectionKey": { "string" : { "B": blob, "BOOL": boolean, "BS": [ blob ], "L": [ "AttributeValue" ], "M": { "string" : "AttributeValue" }, "N": "string", "NS": [ "string" ], "NULL": boolean, "S": "string", "SS": [ "string" ] } }, "SizeEstimateRangeGB": [ number ] } ] }` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`aws.dynamodb.table_names`](/docs/attributes-registry/aws.md) | string[] | The keys in the `RequestItems` object field. | `["Users", "Cats"]` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | @@ -102,6 +104,7 @@ The Semantic Conventions for [AWS DynamoDB](https://aws.amazon.com/dynamodb/) ex | Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | |---|---|---|---|---|---| | [`rpc.system`](/docs/attributes-registry/rpc.md) | string | The value `aws-api`. | `aws-api` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`aws.extended_request_id`](/docs/attributes-registry/aws.md) | string | The AWS extended request ID as returned in the response header `x-amz-id-2`. | `wzHcyEWfmOGDIE5QOhTAqFDoDWP3y8IUvpNINCwL9N4TEHbUw0/gZJ+VZTmCNCWR7fezEN3eCiQ=` | `Conditionally Required` If available. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`aws.dynamodb.consumed_capacity`](/docs/attributes-registry/aws.md) | string[] | The JSON-serialized value of each item in the `ConsumedCapacity` response field. | `["{ \"CapacityUnits\": number, \"GlobalSecondaryIndexes\": { \"string\" : { \"CapacityUnits\": number, \"ReadCapacityUnits\": number, \"WriteCapacityUnits\": number } }, \"LocalSecondaryIndexes\": { \"string\" : { \"CapacityUnits\": number, \"ReadCapacityUnits\": number, \"WriteCapacityUnits\": number } }, \"ReadCapacityUnits\": number, \"Table\": { \"CapacityUnits\": number, \"ReadCapacityUnits\": number, \"WriteCapacityUnits\": number }, \"TableName\": \"string\", \"WriteCapacityUnits\": number }"]` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`aws.dynamodb.global_secondary_indexes`](/docs/attributes-registry/aws.md) | string[] | The JSON-serialized value of each item of the `GlobalSecondaryIndexes` request field | `["{ \"IndexName\": \"string\", \"KeySchema\": [ { \"AttributeName\": \"string\", \"KeyType\": \"string\" } ], \"Projection\": { \"NonKeyAttributes\": [ \"string\" ], \"ProjectionType\": \"string\" }, \"ProvisionedThroughput\": { \"ReadCapacityUnits\": number, \"WriteCapacityUnits\": number } }"]` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`aws.dynamodb.item_collection_metrics`](/docs/attributes-registry/aws.md) | string | The JSON-serialized value of the `ItemCollectionMetrics` response field. | `{ "string" : [ { "ItemCollectionKey": { "string" : { "B": blob, "BOOL": boolean, "BS": [ blob ], "L": [ "AttributeValue" ], "M": { "string" : "AttributeValue" }, "N": "string", "NS": [ "string" ], "NULL": boolean, "S": "string", "SS": [ "string" ] } }, "SizeEstimateRangeGB": [ number ] } ] }` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | @@ -146,6 +149,7 @@ The Semantic Conventions for [AWS DynamoDB](https://aws.amazon.com/dynamodb/) ex | Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | |---|---|---|---|---|---| | [`rpc.system`](/docs/attributes-registry/rpc.md) | string | The value `aws-api`. | `aws-api` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`aws.extended_request_id`](/docs/attributes-registry/aws.md) | string | The AWS extended request ID as returned in the response header `x-amz-id-2`. | `wzHcyEWfmOGDIE5QOhTAqFDoDWP3y8IUvpNINCwL9N4TEHbUw0/gZJ+VZTmCNCWR7fezEN3eCiQ=` | `Conditionally Required` If available. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`aws.dynamodb.consumed_capacity`](/docs/attributes-registry/aws.md) | string[] | The JSON-serialized value of each item in the `ConsumedCapacity` response field. | `["{ \"CapacityUnits\": number, \"GlobalSecondaryIndexes\": { \"string\" : { \"CapacityUnits\": number, \"ReadCapacityUnits\": number, \"WriteCapacityUnits\": number } }, \"LocalSecondaryIndexes\": { \"string\" : { \"CapacityUnits\": number, \"ReadCapacityUnits\": number, \"WriteCapacityUnits\": number } }, \"ReadCapacityUnits\": number, \"Table\": { \"CapacityUnits\": number, \"ReadCapacityUnits\": number, \"WriteCapacityUnits\": number }, \"TableName\": \"string\", \"WriteCapacityUnits\": number }"]` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`aws.dynamodb.item_collection_metrics`](/docs/attributes-registry/aws.md) | string | The JSON-serialized value of the `ItemCollectionMetrics` response field. | `{ "string" : [ { "ItemCollectionKey": { "string" : { "B": blob, "BOOL": boolean, "BS": [ blob ], "L": [ "AttributeValue" ], "M": { "string" : "AttributeValue" }, "N": "string", "NS": [ "string" ], "NULL": boolean, "S": "string", "SS": [ "string" ] } }, "SizeEstimateRangeGB": [ number ] } ] }` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`aws.dynamodb.table_names`](/docs/attributes-registry/aws.md) | string[] | A single-element array with the value of the TableName request parameter. | `["Users"]` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | @@ -186,6 +190,7 @@ The Semantic Conventions for [AWS DynamoDB](https://aws.amazon.com/dynamodb/) ex | Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | |---|---|---|---|---|---| | [`rpc.system`](/docs/attributes-registry/rpc.md) | string | The value `aws-api`. | `aws-api` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`aws.extended_request_id`](/docs/attributes-registry/aws.md) | string | The AWS extended request ID as returned in the response header `x-amz-id-2`. | `wzHcyEWfmOGDIE5QOhTAqFDoDWP3y8IUvpNINCwL9N4TEHbUw0/gZJ+VZTmCNCWR7fezEN3eCiQ=` | `Conditionally Required` If available. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`aws.dynamodb.table_names`](/docs/attributes-registry/aws.md) | string[] | A single-element array with the value of the TableName request parameter. | `["Users"]` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`aws.request_id`](/docs/attributes-registry/aws.md) | string | The AWS request ID as returned in the response headers `x-amz-request-id` or `x-amz-requestid`. | `79b9da39-b7ae-508a-a6bc-864b2829c622`; `C9ER4AJX75574TDJ` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`rpc.method`](/docs/attributes-registry/rpc.md) | string | The name of the operation corresponding to the request, as returned by the AWS SDK [1] | `GetItem`; `PutItem` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | @@ -224,6 +229,7 @@ The Semantic Conventions for [AWS DynamoDB](https://aws.amazon.com/dynamodb/) ex | Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | |---|---|---|---|---|---| | [`rpc.system`](/docs/attributes-registry/rpc.md) | string | The value `aws-api`. | `aws-api` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`aws.extended_request_id`](/docs/attributes-registry/aws.md) | string | The AWS extended request ID as returned in the response header `x-amz-id-2`. | `wzHcyEWfmOGDIE5QOhTAqFDoDWP3y8IUvpNINCwL9N4TEHbUw0/gZJ+VZTmCNCWR7fezEN3eCiQ=` | `Conditionally Required` If available. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`aws.dynamodb.table_names`](/docs/attributes-registry/aws.md) | string[] | A single-element array with the value of the TableName request parameter. | `["Users"]` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`aws.request_id`](/docs/attributes-registry/aws.md) | string | The AWS request ID as returned in the response headers `x-amz-request-id` or `x-amz-requestid`. | `79b9da39-b7ae-508a-a6bc-864b2829c622`; `C9ER4AJX75574TDJ` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`rpc.method`](/docs/attributes-registry/rpc.md) | string | The name of the operation corresponding to the request, as returned by the AWS SDK [1] | `GetItem`; `PutItem` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | @@ -262,6 +268,7 @@ The Semantic Conventions for [AWS DynamoDB](https://aws.amazon.com/dynamodb/) ex | Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | |---|---|---|---|---|---| | [`rpc.system`](/docs/attributes-registry/rpc.md) | string | The value `aws-api`. | `aws-api` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`aws.extended_request_id`](/docs/attributes-registry/aws.md) | string | The AWS extended request ID as returned in the response header `x-amz-id-2`. | `wzHcyEWfmOGDIE5QOhTAqFDoDWP3y8IUvpNINCwL9N4TEHbUw0/gZJ+VZTmCNCWR7fezEN3eCiQ=` | `Conditionally Required` If available. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`aws.dynamodb.consistent_read`](/docs/attributes-registry/aws.md) | boolean | The value of the `ConsistentRead` request parameter. | | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`aws.dynamodb.consumed_capacity`](/docs/attributes-registry/aws.md) | string[] | The JSON-serialized value of each item in the `ConsumedCapacity` response field. | `["{ \"CapacityUnits\": number, \"GlobalSecondaryIndexes\": { \"string\" : { \"CapacityUnits\": number, \"ReadCapacityUnits\": number, \"WriteCapacityUnits\": number } }, \"LocalSecondaryIndexes\": { \"string\" : { \"CapacityUnits\": number, \"ReadCapacityUnits\": number, \"WriteCapacityUnits\": number } }, \"ReadCapacityUnits\": number, \"Table\": { \"CapacityUnits\": number, \"ReadCapacityUnits\": number, \"WriteCapacityUnits\": number }, \"TableName\": \"string\", \"WriteCapacityUnits\": number }"]` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`aws.dynamodb.projection`](/docs/attributes-registry/aws.md) | string | The value of the `ProjectionExpression` request parameter. | `Title`; `Title, Price, Color`; `Title, Description, RelatedItems, ProductReviews` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | @@ -303,6 +310,7 @@ The Semantic Conventions for [AWS DynamoDB](https://aws.amazon.com/dynamodb/) ex | Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | |---|---|---|---|---|---| | [`rpc.system`](/docs/attributes-registry/rpc.md) | string | The value `aws-api`. | `aws-api` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`aws.extended_request_id`](/docs/attributes-registry/aws.md) | string | The AWS extended request ID as returned in the response header `x-amz-id-2`. | `wzHcyEWfmOGDIE5QOhTAqFDoDWP3y8IUvpNINCwL9N4TEHbUw0/gZJ+VZTmCNCWR7fezEN3eCiQ=` | `Conditionally Required` If available. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`aws.dynamodb.exclusive_start_table`](/docs/attributes-registry/aws.md) | string | The value of the `ExclusiveStartTableName` request parameter. | `Users`; `CatsTable` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`aws.dynamodb.limit`](/docs/attributes-registry/aws.md) | int | The value of the `Limit` request parameter. | `10` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`aws.dynamodb.table_count`](/docs/attributes-registry/aws.md) | int | The number of items in the `TableNames` response parameter. | `20` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | @@ -343,6 +351,7 @@ The Semantic Conventions for [AWS DynamoDB](https://aws.amazon.com/dynamodb/) ex | Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | |---|---|---|---|---|---| | [`rpc.system`](/docs/attributes-registry/rpc.md) | string | The value `aws-api`. | `aws-api` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`aws.extended_request_id`](/docs/attributes-registry/aws.md) | string | The AWS extended request ID as returned in the response header `x-amz-id-2`. | `wzHcyEWfmOGDIE5QOhTAqFDoDWP3y8IUvpNINCwL9N4TEHbUw0/gZJ+VZTmCNCWR7fezEN3eCiQ=` | `Conditionally Required` If available. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`aws.dynamodb.consumed_capacity`](/docs/attributes-registry/aws.md) | string[] | The JSON-serialized value of each item in the `ConsumedCapacity` response field. | `["{ \"CapacityUnits\": number, \"GlobalSecondaryIndexes\": { \"string\" : { \"CapacityUnits\": number, \"ReadCapacityUnits\": number, \"WriteCapacityUnits\": number } }, \"LocalSecondaryIndexes\": { \"string\" : { \"CapacityUnits\": number, \"ReadCapacityUnits\": number, \"WriteCapacityUnits\": number } }, \"ReadCapacityUnits\": number, \"Table\": { \"CapacityUnits\": number, \"ReadCapacityUnits\": number, \"WriteCapacityUnits\": number }, \"TableName\": \"string\", \"WriteCapacityUnits\": number }"]` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`aws.dynamodb.item_collection_metrics`](/docs/attributes-registry/aws.md) | string | The JSON-serialized value of the `ItemCollectionMetrics` response field. | `{ "string" : [ { "ItemCollectionKey": { "string" : { "B": blob, "BOOL": boolean, "BS": [ blob ], "L": [ "AttributeValue" ], "M": { "string" : "AttributeValue" }, "N": "string", "NS": [ "string" ], "NULL": boolean, "S": "string", "SS": [ "string" ] } }, "SizeEstimateRangeGB": [ number ] } ] }` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`aws.dynamodb.table_names`](/docs/attributes-registry/aws.md) | string[] | The keys in the `RequestItems` object field. | `["Users", "Cats"]` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | @@ -383,6 +392,7 @@ The Semantic Conventions for [AWS DynamoDB](https://aws.amazon.com/dynamodb/) ex | Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | |---|---|---|---|---|---| | [`rpc.system`](/docs/attributes-registry/rpc.md) | string | The value `aws-api`. | `aws-api` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`aws.extended_request_id`](/docs/attributes-registry/aws.md) | string | The AWS extended request ID as returned in the response header `x-amz-id-2`. | `wzHcyEWfmOGDIE5QOhTAqFDoDWP3y8IUvpNINCwL9N4TEHbUw0/gZJ+VZTmCNCWR7fezEN3eCiQ=` | `Conditionally Required` If available. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`aws.dynamodb.attributes_to_get`](/docs/attributes-registry/aws.md) | string[] | The value of the `AttributesToGet` request parameter. | `["lives", "id"]` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`aws.dynamodb.consistent_read`](/docs/attributes-registry/aws.md) | boolean | The value of the `ConsistentRead` request parameter. | | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`aws.dynamodb.consumed_capacity`](/docs/attributes-registry/aws.md) | string[] | The JSON-serialized value of each item in the `ConsumedCapacity` response field. | `["{ \"CapacityUnits\": number, \"GlobalSecondaryIndexes\": { \"string\" : { \"CapacityUnits\": number, \"ReadCapacityUnits\": number, \"WriteCapacityUnits\": number } }, \"LocalSecondaryIndexes\": { \"string\" : { \"CapacityUnits\": number, \"ReadCapacityUnits\": number, \"WriteCapacityUnits\": number } }, \"ReadCapacityUnits\": number, \"Table\": { \"CapacityUnits\": number, \"ReadCapacityUnits\": number, \"WriteCapacityUnits\": number }, \"TableName\": \"string\", \"WriteCapacityUnits\": number }"]` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | @@ -429,6 +439,7 @@ The Semantic Conventions for [AWS DynamoDB](https://aws.amazon.com/dynamodb/) ex | Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | |---|---|---|---|---|---| | [`rpc.system`](/docs/attributes-registry/rpc.md) | string | The value `aws-api`. | `aws-api` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`aws.extended_request_id`](/docs/attributes-registry/aws.md) | string | The AWS extended request ID as returned in the response header `x-amz-id-2`. | `wzHcyEWfmOGDIE5QOhTAqFDoDWP3y8IUvpNINCwL9N4TEHbUw0/gZJ+VZTmCNCWR7fezEN3eCiQ=` | `Conditionally Required` If available. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`aws.dynamodb.attributes_to_get`](/docs/attributes-registry/aws.md) | string[] | The value of the `AttributesToGet` request parameter. | `["lives", "id"]` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`aws.dynamodb.consistent_read`](/docs/attributes-registry/aws.md) | boolean | The value of the `ConsistentRead` request parameter. | | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`aws.dynamodb.consumed_capacity`](/docs/attributes-registry/aws.md) | string[] | The JSON-serialized value of each item in the `ConsumedCapacity` response field. | `["{ \"CapacityUnits\": number, \"GlobalSecondaryIndexes\": { \"string\" : { \"CapacityUnits\": number, \"ReadCapacityUnits\": number, \"WriteCapacityUnits\": number } }, \"LocalSecondaryIndexes\": { \"string\" : { \"CapacityUnits\": number, \"ReadCapacityUnits\": number, \"WriteCapacityUnits\": number } }, \"ReadCapacityUnits\": number, \"Table\": { \"CapacityUnits\": number, \"ReadCapacityUnits\": number, \"WriteCapacityUnits\": number }, \"TableName\": \"string\", \"WriteCapacityUnits\": number }"]` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | @@ -478,6 +489,7 @@ The Semantic Conventions for [AWS DynamoDB](https://aws.amazon.com/dynamodb/) ex | Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | |---|---|---|---|---|---| | [`rpc.system`](/docs/attributes-registry/rpc.md) | string | The value `aws-api`. | `aws-api` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`aws.extended_request_id`](/docs/attributes-registry/aws.md) | string | The AWS extended request ID as returned in the response header `x-amz-id-2`. | `wzHcyEWfmOGDIE5QOhTAqFDoDWP3y8IUvpNINCwL9N4TEHbUw0/gZJ+VZTmCNCWR7fezEN3eCiQ=` | `Conditionally Required` If available. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`aws.dynamodb.consumed_capacity`](/docs/attributes-registry/aws.md) | string[] | The JSON-serialized value of each item in the `ConsumedCapacity` response field. | `["{ \"CapacityUnits\": number, \"GlobalSecondaryIndexes\": { \"string\" : { \"CapacityUnits\": number, \"ReadCapacityUnits\": number, \"WriteCapacityUnits\": number } }, \"LocalSecondaryIndexes\": { \"string\" : { \"CapacityUnits\": number, \"ReadCapacityUnits\": number, \"WriteCapacityUnits\": number } }, \"ReadCapacityUnits\": number, \"Table\": { \"CapacityUnits\": number, \"ReadCapacityUnits\": number, \"WriteCapacityUnits\": number }, \"TableName\": \"string\", \"WriteCapacityUnits\": number }"]` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`aws.dynamodb.item_collection_metrics`](/docs/attributes-registry/aws.md) | string | The JSON-serialized value of the `ItemCollectionMetrics` response field. | `{ "string" : [ { "ItemCollectionKey": { "string" : { "B": blob, "BOOL": boolean, "BS": [ blob ], "L": [ "AttributeValue" ], "M": { "string" : "AttributeValue" }, "N": "string", "NS": [ "string" ], "NULL": boolean, "S": "string", "SS": [ "string" ] } }, "SizeEstimateRangeGB": [ number ] } ] }` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`aws.dynamodb.table_names`](/docs/attributes-registry/aws.md) | string[] | A single-element array with the value of the TableName request parameter. | `["Users"]` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | @@ -518,6 +530,7 @@ The Semantic Conventions for [AWS DynamoDB](https://aws.amazon.com/dynamodb/) ex | Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | |---|---|---|---|---|---| | [`rpc.system`](/docs/attributes-registry/rpc.md) | string | The value `aws-api`. | `aws-api` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`aws.extended_request_id`](/docs/attributes-registry/aws.md) | string | The AWS extended request ID as returned in the response header `x-amz-id-2`. | `wzHcyEWfmOGDIE5QOhTAqFDoDWP3y8IUvpNINCwL9N4TEHbUw0/gZJ+VZTmCNCWR7fezEN3eCiQ=` | `Conditionally Required` If available. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`aws.dynamodb.attribute_definitions`](/docs/attributes-registry/aws.md) | string[] | The JSON-serialized value of each item in the `AttributeDefinitions` request field. | `["{ \"AttributeName\": \"string\", \"AttributeType\": \"string\" }"]` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`aws.dynamodb.consumed_capacity`](/docs/attributes-registry/aws.md) | string[] | The JSON-serialized value of each item in the `ConsumedCapacity` response field. | `["{ \"CapacityUnits\": number, \"GlobalSecondaryIndexes\": { \"string\" : { \"CapacityUnits\": number, \"ReadCapacityUnits\": number, \"WriteCapacityUnits\": number } }, \"LocalSecondaryIndexes\": { \"string\" : { \"CapacityUnits\": number, \"ReadCapacityUnits\": number, \"WriteCapacityUnits\": number } }, \"ReadCapacityUnits\": number, \"Table\": { \"CapacityUnits\": number, \"ReadCapacityUnits\": number, \"WriteCapacityUnits\": number }, \"TableName\": \"string\", \"WriteCapacityUnits\": number }"]` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`aws.dynamodb.global_secondary_index_updates`](/docs/attributes-registry/aws.md) | string[] | The JSON-serialized value of each item in the `GlobalSecondaryIndexUpdates` request field. | `["{ \"Create\": { \"IndexName\": \"string\", \"KeySchema\": [ { \"AttributeName\": \"string\", \"KeyType\": \"string\" } ], \"Projection\": { \"NonKeyAttributes\": [ \"string\" ], \"ProjectionType\": \"string\" }, \"ProvisionedThroughput\": { \"ReadCapacityUnits\": number, \"WriteCapacityUnits\": number } }"]` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | diff --git a/docs/gen-ai/gen-ai-events.md b/docs/gen-ai/gen-ai-events.md index e786696f29..cc77890c73 100644 --- a/docs/gen-ai/gen-ai-events.md +++ b/docs/gen-ai/gen-ai-events.md @@ -10,15 +10,11 @@ linkTitle: Generative AI events -- [Common attributes](#common-attributes) -- [System event](#system-event) -- [User event](#user-event) -- [Assistant event](#assistant-event) - - [`ToolCall` object](#toolcall-object) - - [`Function` object](#function-object) -- [Tool event](#tool-event) -- [Choice event](#choice-event) - - [`Message` object](#message-object) +- [Event: `gen_ai.system.message`](#event-gen_aisystemmessage) +- [Event: `gen_ai.user.message`](#event-gen_aiusermessage) +- [Event: `gen_ai.assistant.message`](#event-gen_aiassistantmessage) +- [Event: `gen_ai.tool.message`](#event-gen_aitoolmessage) +- [Event: `gen_ai.choice`](#event-gen_aichoice) - [Custom events](#custom-events) - [Examples](#examples) - [Chat completion](#chat-completion) @@ -27,10 +23,15 @@ linkTitle: Generative AI events -GenAI instrumentations MAY capture user inputs sent to the model and responses received from it as [events](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.39.0/specification/logs/event-api.md). +GenAI instrumentations MAY capture user inputs sent to the model and responses received from it as [events](https://github.com/open-telemetry/opentelemetry-specification/blob/v1.40.0/specification/logs/api.md#emit-an-event). -> Note: +<<<<<<< HEAD +> [!NOTE] > Event API is experimental and not yet available in some languages. Check [spec-compliance matrix](https://github.com/open-telemetry/opentelemetry-specification/blob/main/spec-compliance-matrix.md#events) to see the implementation status in corresponding language. +======= +> Note: +> Event API is experimental and not yet available in some languages. Check [spec-compliance matrix](https://github.com/open-telemetry/opentelemetry-specification/blob/v1.40.0/spec-compliance-matrix.md#logs) to see the implementation status in corresponding language. +>>>>>>> 75746bc9 (reword) Instrumentations MAY capture inputs and outputs if and only if application has enabled the collection of this data. This is for three primary reasons: @@ -50,17 +51,21 @@ Telemetry consumers SHOULD expect to receive unknown body fields. Instrumentations SHOULD NOT capture undocumented body fields and MUST follow the documented defaults for known fields. Instrumentations MAY offer configuration options allowing to disable events or allowing to capture all fields. -## Common attributes +## Event: `gen_ai.system.message` -The following attributes apply to all GenAI events. - - + +**Status:** ![Experimental](https://img.shields.io/badge/-experimental-blue) + +The event name MUST be `gen_ai.system.message`. + +This event describes the system instructions passed to the GenAI model. + | Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | |---|---|---|---|---|---| | [`gen_ai.system`](/docs/attributes-registry/gen-ai.md) | string | The Generative AI product as identified by the client or server instrumentation. [1] | `openai` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | @@ -89,97 +94,281 @@ If none of these options apply, the `gen_ai.system` SHOULD be set to `_OTHER`. | `openai` | OpenAI | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `vertex_ai` | Vertex AI | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +**Body fields:** + +| Body Field | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | +|---|---|---|---|---|---| +| `content` | undefined | The contents of the system message. | `You're a helpful bot` | `Opt-In` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `role` | string | The actual role of the message author as passed in the message. | `system`; `instruction` | `Conditionally Required` if available and not equal to `system`. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + -## System event +## Event: `gen_ai.user.message` -This event describes the instructions passed to the GenAI model. + + + + + + -The event name MUST be `gen_ai.system.message`. +**Status:** ![Experimental](https://img.shields.io/badge/-experimental-blue) -| Body Field | Type | Description | Examples | Requirement Level | -|---|---|---|---|---| -| `role` | string | The actual role of the message author as passed in the message. | `"system"`, `"instructions"` | `Conditionally Required`: if available and not equal to `system` | -| `content` | `AnyValue` | The contents of the system message. | `"You're a friendly bot that answers questions about OpenTelemetry."` | `Opt-In` | +The event name MUST be `gen_ai.user.message`. + +This event describes the user message passed to the GenAI model. -## User event +| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | +|---|---|---|---|---|---| +| [`gen_ai.system`](/docs/attributes-registry/gen-ai.md) | string | The Generative AI product as identified by the client or server instrumentation. [1] | `openai` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -This event describes the prompt message specified by the user. +**[1] `gen_ai.system`:** 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 event name MUST be `gen_ai.user.message`. +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`. + +--- + +`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) | +| `aws.bedrock` | AWS Bedrock | ![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) | +| `ibm.watsonx.ai` | IBM Watsonx AI | ![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) | + +**Body fields:** + +| Body Field | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | +|---|---|---|---|---|---| +| `content` | undefined | The contents of the user message. | `What's the weather in Paris?` | `Opt-In` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `role` | string | The actual role of the message author as passed in the message. | `user`; `customer` | `Conditionally Required` if available and not equal to `user`. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + + + + + -| Body Field | Type | Description | Examples | Requirement Level | -|---|---|---|---|---| -| `role` | string | The actual role of the message author as passed in the message. | `"user"`, `"customer"` | `Conditionally Required`: if available and if not equal to `user` | -| `content` | `AnyValue` | The contents of the user message. | `What telemetry is reported by OpenAI instrumentations?` | `Opt-In` | +## Event: `gen_ai.assistant.message` -## Assistant event + + + + + + -This event describes the assistant message. +**Status:** ![Experimental](https://img.shields.io/badge/-experimental-blue) The event name MUST be `gen_ai.assistant.message`. -| Body Field | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | -|--------------|--------------------------------|----------------------------------------|-------------------------------------------------|-------------------| -| `role` | string | The actual role of the message author as passed in the message. | `"assistant"`, `"bot"` | `Conditionally Required`: if available and if not equal to `assistant` | -| `content` | `AnyValue` | The contents of the assistant message. | `Spans, events, metrics defined by the GenAI semantic conventions.` | `Opt-In` | -| `tool_calls` | [ToolCall](#toolcall-object)[] | The tool calls generated by the model, such as function calls. | `[{"id":"call_mszuSIzqtI65i1wAUOE8w5H4", "function":{"name":"get_link_to_otel_semconv", "arguments":{"semconv":"gen_ai"}}, "type":"function"}]` | `Conditionally Required`: if available | +This event describes the assistant message passed to GenAI system. + +| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | +|---|---|---|---|---|---| +| [`gen_ai.system`](/docs/attributes-registry/gen-ai.md) | string | The Generative AI product as identified by the client or server instrumentation. [1] | `openai` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + +**[1] `gen_ai.system`:** 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`. + +--- + +`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) | +| `aws.bedrock` | AWS Bedrock | ![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) | +| `ibm.watsonx.ai` | IBM Watsonx AI | ![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) | -### `ToolCall` object +**Body fields:** -| Body Field | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | -|------------|-----------------------------|------------------------------------|-------------------------------------------------|-------------------| -| `id` | string | The id of the tool call | `call_mszuSIzqtI65i1wAUOE8w5H4` | `Required` | -| `type` | string | The type of the tool | `function` | `Required` | -| `function` | [Function](#function-object)| The function that the model called | `{"name":"get_link_to_otel_semconv", "arguments":{"semconv":"gen_ai"}}` | `Required` | +| Body Field | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | +|---|---|---|---|---|---| +| `content` | undefined | The contents of the tool message. | `The weather in Paris is rainy and overcast, with temperatures around 57°F` | `Opt-In` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `role` | string | The actual role of the message author as passed in the message. | `assistant`; `bot` | `Conditionally Required` if available and not equal to `assistant`. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `tool_calls`: | map[] | The tool calls generated by the model, such as function calls. | | `Conditionally Required` if available | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +|   `function`: | map | The function call. | | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +|     `arguments` | undefined | The arguments of the function as provided in the LLM response. [1] | `{\"location\": \"Paris\"}` | `Opt-In` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +|     `name` | string | The name of the function. | `get_weather` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +|   `id` | string | The id of the tool call. | `call_mszuSIzqtI65i1wAUOE8w5H4` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +|   `type` | enum | The type of the tool. | `function` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -### `Function` object +**[1]:** Models usually return arguments as a JSON string. In this case, it's RECOMMENDED to provide arguments as is without attempting to deserialize them. +Semantic conventions for individual systems MAY specify a different type for arguments field. -| Body Field | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | -|-------------|------------|----------------------------------------|----------------------------|-------------------| -| `name` | string | The name of the function to call | `get_link_to_otel_semconv` | `Required` | -| `arguments` | `AnyValue` | The arguments to pass the the function | `{"semconv": "gen_ai"}` | `Opt-In` | +`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. -## Tool event +| Value | Description | Stability | +|---|---|---| +| `function` | Function | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + + + + + + +## Event: `gen_ai.tool.message` + + + + + + + -This event describes the output of the tool or function submitted back to the model. +**Status:** ![Experimental](https://img.shields.io/badge/-experimental-blue) The event name MUST be `gen_ai.tool.message`. -| Body Field | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | -|----------------|--------|-----------------------------------------------|---------------------------------|-------------------| -| `role` | string | The actual role of the message author as passed in the message. | `"tool"`, `"function"` | `Conditionally Required`: if available and if not equal to `tool` | -| `content` | AnyValue | The contents of the tool message. | `opentelemetry.io` | `Opt-In` | -| `id` | string | Tool call that this message is responding to. | `call_mszuSIzqtI65i1wAUOE8w5H4` | `Required` | +This event describes the response from a tool or function call passed to the GenAI model. -## Choice event +| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | +|---|---|---|---|---|---| +| [`gen_ai.system`](/docs/attributes-registry/gen-ai.md) | string | The Generative AI product as identified by the client or server instrumentation. [1] | `openai` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + +**[1] `gen_ai.system`:** 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`. + +--- + +`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) | +| `aws.bedrock` | AWS Bedrock | ![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) | +| `ibm.watsonx.ai` | IBM Watsonx AI | ![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) | -This event describes model-generated individual chat response (choice). -If GenAI model returns multiple choices, each choice SHOULD be recorded as an individual event. +**Body fields:** -When response is streamed, instrumentations that report response events MUST reconstruct and report the full message and MUST NOT report individual chunks as events. -If the request to GenAI model fails with an error before content is received, instrumentation SHOULD report an event with truncated content (if enabled). If `finish_reason` was not received, it MUST be set to `error`. +| Body Field | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | +|---|---|---|---|---|---| +| `content` | undefined | The contents of the tool message. | `rainy, 57°F` | `Opt-In` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `id` | string | Tool call id that this message is responding to. | `call_mszuSIzqtI65i1wAUOE8w5H4` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `role` | string | The actual role of the message author as passed in the message. | `tool`; `function` | `Conditionally Required` if available and not equal to `tool`. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + + + + + + +## Event: `gen_ai.choice` + + + + + + + + +**Status:** ![Experimental](https://img.shields.io/badge/-experimental-blue) The event name MUST be `gen_ai.choice`. -Choice event body has the following fields: +This event describes the Gen AI response message. -| Body Field | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | -|-----------------|----------------------------|-------------------------------------------------|----------------------------------------|-------------------| -| `finish_reason` | string | The reason the model stopped generating tokens. | `stop`, `tool_calls`, `content_filter` | `Required` | -| `index` | int | The index of the choice in the list of choices. | `1` | `Required` | -| `message` | [Message](#message-object) | GenAI response message | `{"content":"The OpenAI semantic conventions are available at opentelemetry.io"}` | `Recommended` | +| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | +|---|---|---|---|---|---| +| [`gen_ai.system`](/docs/attributes-registry/gen-ai.md) | string | The Generative AI product as identified by the client or server instrumentation. [1] | `openai` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -### `Message` object +**[1] `gen_ai.system`:** 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. -| Body Field | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | -|----------------|--------------------------------|-----------------------------------------------|---------------------------------|-------------------| -| `role` | string | The actual role of the message author as passed in the message. | `"assistant"`, `"bot"` | `Conditionally Required`: if available and if not equal to `assistant` | -| `content` | `AnyValue` | The contents of the assistant message. | `Spans, events, metrics defined by the GenAI semantic conventions.` | `Opt-In` | -| `tool_calls` | [ToolCall](#toolcall-object)[] | The tool calls generated by the model, such as function calls. | `[{"id":"call_mszuSIzqtI65i1wAUOE8w5H4", "function":{"name":"get_link_to_otel_semconv", "arguments":"{\"semconv\":\"gen_ai\"}"}, "type":"function"}]` | `Conditionally Required`: if available | +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`. + +--- + +`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) | +| `aws.bedrock` | AWS Bedrock | ![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) | +| `ibm.watsonx.ai` | IBM Watsonx AI | ![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) | + +**Body fields:** + +| Body Field | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | +|---|---|---|---|---|---| +| `finish_reason` | enum | The reason the model stopped generating tokens. | `stop`; `tool_calls`; `content_filter` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `index` | int | The index of the choice in the list of choices. | `0`; `1` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `message`: | map | GenAI response message. | | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +|   `content` | undefined | The contents of the assistant message. | `The weather in Paris is rainy and overcast, with temperatures around 57°F` | `Opt-In` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +|   `role` | string | The actual role of the message author as passed in the message. | `assistant`; `bot` | `Conditionally Required` if available and not equal to `assistant`. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `tool_calls`: | map[] | The tool calls generated by the model, such as function calls. | | `Conditionally Required` if available | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +|   `function`: | map | The function that the model called. | | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +|     `arguments` | undefined | The arguments of the function as provided in the LLM response. [1] | `{\"location\": \"Paris\"}` | `Opt-In` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +|     `name` | string | The name of the function. | `get_weather` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +|   `id` | string | The id of the tool call. | `call_mszuSIzqtI65i1wAUOE8w5H4` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +|   `type` | enum | The type of the tool. | `function` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + +**[1]:** Models usually return arguments as a JSON string. In this case, it's RECOMMENDED to provide arguments as is without attempting to deserialize them. +Semantic conventions for individual systems MAY specify a different type for arguments field. + +`finish_reason` 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 | +|---|---|---| +| `content_filter` | Content Filter | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `error` | Error | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `length` | Length | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `stop` | Stop | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `tool_calls` | Tool Calls | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + +`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 | +|---|---|---| +| `function` | Function | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + + + + + ## Custom events @@ -190,15 +379,27 @@ SHOULD follow `gen_ai.{gen_ai.system}.*` naming pattern for system-specific even ### Chat completion -This example covers the following scenario: - -- user requests chat completion from OpenAI GPT-4 model for the following prompt: - - System message: `You're a friendly bot that answers questions about OpenTelemetry.` - - User message: `How to instrument GenAI library with OTel?` - -- The model responds with `"Follow GenAI semantic conventions available at opentelemetry.io."` message - -Span: +This is an example of telemetry generated for a chat completion call with system and user messages. + +```mermaid +%%{init: +{ + "sequence": { "messageAlign": "left", "htmlLabels":true }, + "themeVariables": { "noteBkgColor" : "green", "noteTextColor": "black", "activationBkgColor": "green", "htmlLabels":true } +} +}%% +sequenceDiagram + participant A as Application + participant I as Instrumented Client + participant M as Model + A->>+I: #U+200D + I->>M: gen_ai.system.message: You are a helpful bot
gen_ai.user.message: Tell me a joke about OpenTelemetry + Note left of I: GenAI Client span + I-->M: gen_ai.choice: Why did the developer bring OpenTelemetry to the party? Because it always knows how to trace the fun! + I-->>-A: #U+200D +``` + +**GenAI Client span:** | Attribute name | Value | |---------------------------------|--------------------------------------------| @@ -213,79 +414,97 @@ Span: | `gen_ai.usage.input_tokens` | `52` | | `gen_ai.response.finish_reasons`| `["stop"]` | -Events: +**Events:** -1. `gen_ai.system.message`. +1. `gen_ai.system.message` | Property | Value | |---------------------|-------------------------------------------------------| | `gen_ai.system` | `"openai"` | - | Event body | `{"content": "You're a friendly bot that answers questions about OpenTelemetry."}` | + | Event body (with content enabled) | `{"content": "You're a helpful bot"}` | 2. `gen_ai.user.message` | Property | Value | |---------------------|-------------------------------------------------------| | `gen_ai.system` | `"openai"` | - | Event body | `{"content":"How to instrument GenAI library with OTel?"}` | + | Event body (with content enabled) | `{"content":"Tell me a joke about OpenTelemetry"}` | 3. `gen_ai.choice` | Property | Value | |---------------------|-------------------------------------------------------| | `gen_ai.system` | `"openai"` | - | Event body (with content enabled) | `{"index":0,"finish_reason":"stop","message":{"content":"Follow GenAI semantic conventions available at opentelemetry.io."}}` | + | Event body (with content enabled) | `{"index":0,"finish_reason":"stop","message":{"content":"Why did the developer bring OpenTelemetry to the party? Because it always knows how to trace the fun!"}}` | | Event body (without content) | `{"index":0,"finish_reason":"stop","message":{}}` | ### Tools -This example covers the following scenario: - -1. Application requests chat completion from OpenAI GPT-4 model and provides a function definition. - - - Application provides the following prompt: - - User message: `How to instrument GenAI library with OTel?` - - Application defines a tool (a function) names `get_link_to_otel_semconv` with single string argument named `semconv` - -2. The model responds with a tool call request which application executes -3. The application requests chat completion again now with the tool execution result +This is an example of telemetry generated for a chat completion call with user message and function definition +that results in a model requesting application to call provided function. Application executes a function and +requests another completion now with the tool response. + +```mermaid +%%{init: +{ + "sequence": { "messageAlign": "left", "htmlLabels":true }, + "themeVariables": { "noteBkgColor" : "green", "noteTextColor": "black", "activationBkgColor": "green", "htmlLabels":true } +} +}%% +sequenceDiagram + participant A as Application + participant I as Instrumented Client + participant M as Model + A->>+I: #U+200D + I->>M: gen_ai.user.message: What's the weather in Paris? + Note left of I: GenAI Client span 1 + I-->M: gen_ai.choice: Call to the get_weather tool with Paris as the location argument. + I-->>-A: #U+200D + A -->> A: parse tool parameters
execute tool
update chat history + A->>+I: #U+200D + I->>M: gen_ai.user.message: What's the weather in Paris?
gen_ai.assistant.message: get_weather tool call
gen_ai.tool.message: rainy, 57°F + Note left of I: GenAI Client span 2 + I-->M: gen_ai.choice: The weather in Paris is rainy and overcast, with temperatures around 57°F + I-->>-A: #U+200D +``` Here's the telemetry generated for each step in this scenario: -1. Chat completion resulting in a tool call. +**GenAI Client span 1:** - | Attribute name | Value | - |---------------------|-------------------------------------------------------| - | Span name | `"chat gpt-4"` | - | `gen_ai.system` | `"openai"` | - | `gen_ai.request.model`| `"gpt-4"` | - | `gen_ai.request.max_tokens`| `200` | - | `gen_ai.request.top_p`| `1.0` | - | `gen_ai.response.id`| `"chatcmpl-9J3uIL87gldCFtiIbyaOvTeYBRA3l"` | - | `gen_ai.response.model`| `"gpt-4-0613"` | - | `gen_ai.usage.output_tokens`| `17` | - | `gen_ai.usage.input_tokens`| `47` | - | `gen_ai.response.finish_reasons`| `["tool_calls"]` | +| Attribute name | Value | +|---------------------|-------------------------------------------------------| +| Span name | `"chat gpt-4"` | +| `gen_ai.system` | `"openai"` | +| `gen_ai.request.model`| `"gpt-4"` | +| `gen_ai.request.max_tokens`| `200` | +| `gen_ai.request.top_p`| `1.0` | +| `gen_ai.response.id`| `"chatcmpl-9J3uIL87gldCFtiIbyaOvTeYBRA3l"` | +| `gen_ai.response.model`| `"gpt-4-0613"` | +| `gen_ai.usage.output_tokens`| `17` | +| `gen_ai.usage.input_tokens`| `47` | +| `gen_ai.response.finish_reasons`| `["tool_calls"]` | - Events parented to this span: + **Events**: - - `gen_ai.user.message` (not reported when capturing content is disabled) + All the following events are parented to the **GenAI chat span 1**. + + 1. `gen_ai.user.message` (not reported when capturing content is disabled) | Property | Value | |---------------------|-------------------------------------------------------| | `gen_ai.system` | `"openai"` | - | Event body | `{"content":"How to instrument GenAI library with OTel?"}` | + | Event body | `{"content":"What's the weather in Paris?"}` | - - `gen_ai.choice` + 2. `gen_ai.choice` | Property | Value | |---------------------|-------------------------------------------------------| | `gen_ai.system` | `"openai"` | - | Event body (with content) | `{"index":0,"finish_reason":"tool_calls","message":{"tool_calls":[{"id":"call_VSPygqKTWdrhaFErNvMV18Yl","function":{"name":"get_link_to_otel_semconv","arguments":"{\"semconv\":\"GenAI\"}"},"type":"function"}]}` | - | Event body (without content) | `{"index":0,"finish_reason":"tool_calls","message":{"tool_calls":[{"id":"call_VSPygqKTWdrhaFErNvMV18Yl","function":{"name":"get_link_to_otel_semconv"},"type":"function"}]}` | + | Event body (with content) | `{"index":0,"finish_reason":"tool_calls","message":{"tool_calls":[{"id":"call_VSPygqKTWdrhaFErNvMV18Yl","function":{"name":"get_weather","arguments":"{\"location\":\"Paris\"}"},"type":"function"}]}` | + | Event body (without content) | `{"index":0,"finish_reason":"tool_calls","message":{"tool_calls":[{"id":"call_VSPygqKTWdrhaFErNvMV18Yl","function":{"name":"get_weather"},"type":"function"}]}` | -2. Application executes the tool call. Application may create span which is not covered by this semantic convention. -3. Final chat completion call +**GenAI Client span 2:** | Attribute name | Value | |---------------------------------|-------------------------------------------------------| @@ -300,55 +519,66 @@ Here's the telemetry generated for each step in this scenario: | `gen_ai.usage.input_tokens` | `47` | | `gen_ai.response.finish_reasons`| `["stop"]` | - Events parented to this span: - (in this example, the event content matches the original messages, but applications may also drop messages or change their content) + **Events**: + + All the following events are parented to the **GenAI chat span 2**. + + In this example, the event content matches the original messages, but applications may also drop messages or change their content. - - `gen_ai.user.message` (not reported when capturing content is not enabled) + 1. `gen_ai.user.message` | Property | Value | |----------------------------------|------------------------------------------------------------| | `gen_ai.system` | `"openai"` | - | Event body | `{"content":"How to instrument GenAI library with OTel?"}` | + | Event body | `{"content":"What's the weather in Paris?"}` | - - `gen_ai.assistant.message` + 2. `gen_ai.assistant.message` | Property | Value | |----------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------| | `gen_ai.system` | `"openai"` | - | Event body (content enabled) | `{"tool_calls":[{"id":"call_VSPygqKTWdrhaFErNvMV18Yl","function":{"name":"get_link_to_otel_semconv","arguments":"{\"semconv\":\"GenAI\"}"},"type":"function"}]}` | - | Event body (content not enabled) | `{"tool_calls":[{"id":"call_VSPygqKTWdrhaFErNvMV18Yl","function":{"name":"get_link_to_otel_semconv"},"type":"function"}]}` | + | Event body (content enabled) | `{"tool_calls":[{"id":"call_VSPygqKTWdrhaFErNvMV18Yl","function":{"name":"get_weather","arguments":"{\"location\":\"Paris\"}"},"type":"function"}]}` | + | Event body (content not enabled) | `{"tool_calls":[{"id":"call_VSPygqKTWdrhaFErNvMV18Yl","function":{"name":"get_weather"},"type":"function"}]}` | - - `gen_ai.tool.message` + 3. `gen_ai.tool.message` | Property | Value | |----------------------------------|------------------------------------------------------------------------------------------------| | `gen_ai.system` | `"openai"` | - | Event body (content enabled) | `{"content":"opentelemetry.io/semconv/gen-ai","id":"call_VSPygqKTWdrhaFErNvMV18Yl"}` | + | Event body (content enabled) | `{"content":"rainy, 57°F","id":"call_VSPygqKTWdrhaFErNvMV18Yl"}` | | Event body (content not enabled) | `{"id":"call_VSPygqKTWdrhaFErNvMV18Yl"}` | - - `gen_ai.choice` + 4. `gen_ai.choice` | Property | Value | |----------------------------------|-------------------------------------------------------------------------------------------------------------------------------| | `gen_ai.system` | `"openai"` | - | Event body (content enabled) | `{"index":0,"finish_reason":"stop","message":{"content":"Follow OTel semconv available at opentelemetry.io/semconv/gen-ai"}}` | + | Event body (content enabled) | `{"index":0,"finish_reason":"stop","message":{"content":"The weather in Paris is rainy and overcast, with temperatures around 57°F"}}` | | Event body (content not enabled) | `{"index":0,"finish_reason":"stop","message":{}}` | ### Chat completion with multiple choices -This example covers the following scenario: - -- user requests 2 chat completion from OpenAI GPT-4 model for the following prompt: - - - System message: `You're a friendly bot that answers questions about OpenTelemetry.` - - User message: `How to instrument GenAI library with OTel?` - -- The model responds with two choices - - - `"Follow GenAI semantic conventions available at opentelemetry.io."` message - - `"Use OpenAI instrumentation library."` message - -Span: +This example covers the scenario when user requests model to generate two completions for the same prompt : + +```mermaid +%%{init: +{ + "sequence": { "messageAlign": "left", "htmlLabels":true }, + "themeVariables": { "noteBkgColor" : "green", "noteTextColor": "black", "activationBkgColor": "green", "htmlLabels":true } +} +}%% +sequenceDiagram + participant A as Application + participant I as Instrumented Client + participant M as Model + A->>+I: #U+200D + I->>M: gen_ai.system.message - "You are a helpful bot"
gen_ai.user.message - "Tell me a joke about OpenTelemetry" + Note left of I: GenAI Client span + I-->M: gen_ai.choice - Why did the developer bring OpenTelemetry to the party? Because it always knows how to trace the fun!
gen_ai.choice - Why did OpenTelemetry get promoted? It had great span of control! + I-->>-A: #U+200D +``` + +**GenAI Client Span**: | Attribute name | Value | |---------------------|--------------------------------------------| @@ -361,24 +591,26 @@ Span: | `gen_ai.response.model`| `"gpt-4-0613"` | | `gen_ai.usage.output_tokens`| `77` | | `gen_ai.usage.input_tokens`| `52` | -| `gen_ai.response.finish_reasons`| `["stop"]` | +| `gen_ai.response.finish_reasons`| `["stop", "stop"]` | + +**Events**: -Events: +All events are parented to the GenAI chat span above. 1. `gen_ai.system.message`: the same as in the [Chat Completion](#chat-completion) example -2. `gen_ai.user.message`: the same as in the previous example +2. `gen_ai.user.message`: the same as in the [Chat Completion](#chat-completion) example 3. `gen_ai.choice` | Property | Value | |------------------------------|-------------------------------------------------------| | `gen_ai.system` | `"openai"` | - | Event body (content enabled) | `{"index":0,"finish_reason":"stop","message":{"content":"Follow GenAI semantic conventions available at opentelemetry.io."}}` | + | Event body (content enabled) | `{"index":0,"finish_reason":"stop","message":{"content":"Why did the developer bring OpenTelemetry to the party? Because it always knows how to trace the fun!"}}` | 4. `gen_ai.choice` | Property | Value | |------------------------------|-------------------------------------------------------| | `gen_ai.system` | `"openai"` | - | Event body (content enabled) | `{"index":1,"finish_reason":"stop","message":{"content":"Use OpenAI instrumentation library."}}` | + | Event body (content enabled) | `{"index":1,"finish_reason":"stop","message":{"content":"Why did OpenTelemetry get promoted? It had great span of control!"}}` | [DocumentStatus]: https://opentelemetry.io/docs/specs/otel/document-status diff --git a/docs/general/events.md b/docs/general/events.md index 15ae55be53..c63aa5904a 100644 --- a/docs/general/events.md +++ b/docs/general/events.md @@ -5,7 +5,7 @@ aliases: [events-general] # Semantic Conventions for Events -**Status**: [Experimental][DocumentStatus] +**Status**: [Development][DocumentStatus] This document describes the characteristics of standalone Events that are represented in the data model by `LogRecord`s. @@ -15,11 +15,7 @@ Semantically, an Event is a named occurrence at an instant in time. It signals t Examples of Events might include things like uncaught exceptions, button clicks, user logout, network connection severed, etc. -In OpenTelemetry, Events are implemented as a specific type of `LogRecord` that conforms to -the conventions included here, and Events -[have their own API](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/logs/event-api.md). -The API abstracts away knowledge of `LogRecord` so that users only deal with Event -semantics. +In OpenTelemetry, Events are implemented as a specific type of [`LogRecord`](https://github.com/open-telemetry/opentelemetry-specification/blob/v1.39.0/specification/logs/api.md) that conforms to the conventions included here. In addition to a required name, an Event may contain a _payload_ (body) of any type permitted by the [LogRecord body](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/logs/data-model.md#field-body). @@ -32,30 +28,11 @@ field semantics, and stability and requirement levels. Other events may be user- bespoke user semantics. When an Event name exists in the semantic conventions, its _payload_ structure and semantics will also be defined. -## Event definition +## General event semantics - - - - - - - -| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | -|---|---|---|---|---|---| -| [`event.name`](/docs/attributes-registry/event.md) | string | Identifies the class / type of event. [1] | `browser.mouse.click`; `device.app.lifecycle` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | - -**[1] `event.name`:** Event names are subject to the same rules as [attribute names](/docs/general/attribute-naming.md). Notably, event names are namespaced to avoid collisions and provide a clean separation of semantics for events in separate domains like browser, mobile, and kubernetes. - - - - - - -### General event semantics - -* An event MUST have an `event.name` attribute that uniquely identifies the event. -* It MAY have [standard](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.39.0/specification/common#attribute) +* An event MUST have an [Event name property](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.40.0/specification/logs/data-model.md#field-eventname) + that uniquely identifies the event. Event names are subject to the same rules as [attribute names](/docs/general/attribute-naming.md). +* Event MAY have [standard](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.39.0/specification/common#attribute) attributes that provide additional context about the event. * It MAY contain a _payload_ (body) that describes the specific details of the named event. @@ -73,21 +50,22 @@ Recommendations for defining events: collection of [standard](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.39.0/specification/common#attribute) attributes. * Events SHOULD be generated / produced / recorded using the - [Event API](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/logs/event-api.md) + [Emit Event API](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.40.0/specification/logs/api.md#emit-an-event) to ensure that the event is created using the configured SDK instance. - * The Event API is not yet available in all OpenTelemetry SDKs. - * TODO: Add deep link to the [compliance matrix of the Event API](https://github.com/open-telemetry/opentelemetry-specification/blob/main/spec-compliance-matrix.md) - when it exists. -* It's NOT RECOMMENDED to prefix the _payload_ (body) _fields_ with the `event.name` to + * The Emit Event API is not yet available in all OpenTelemetry SDKs. Check [spec-compliance matrix](https://github.com/open-telemetry/opentelemetry-specification/blob/v1.40.0/spec-compliance-matrix.md#logs) to see the implementation status in corresponding language. +* It's NOT RECOMMENDED to prefix the _payload_ (body) _fields_ with the `EventName` to avoid redundancy and to keep the event definition clean. * The events SHOULD document their semantic conventions including event name, attributes, and the payload. Recommendations on using attributes vs. body fields: -* If the field should be comparable across every type of record, it should be an attribute. +* If the field should be comparable across events with different `EventName` (or between an event and other telemetry items), + it should be an attribute. * If the field is specific to the event itself, then it should be a body field. -* Unless the same `event.name` exists on two events, anything in two event bodies is not comparable to each other. +* Body fields that belong to events with different event names are not comparable. + For example, body field `id` on event `my_company.order_submitted` is semantically different from + field `id` on an event with name `session.start`. ### Event payload (body) @@ -95,7 +73,7 @@ Recommendations on using attributes vs. body fields: requirements don't apply to event payload fields. * The definition for OpenTelemetry defined events supports describing individual _fields_ (Body Fields) - * The _fields_ are unique to the named event (`event.name`) and different events + * The _fields_ are unique to the named event ([EventName](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.40.0/specification/logs/data-model.md#field-eventname)) and different events may use the same _field_ name to represent different data, due to the unique nature of the event. diff --git a/docs/general/session.md b/docs/general/session.md index 8302097127..18c0c447cf 100644 --- a/docs/general/session.md +++ b/docs/general/session.md @@ -40,7 +40,7 @@ backends can link the two sessions (see [Session Start Event](#session-start-eve ![Experimental](https://img.shields.io/badge/-experimental-blue) -`event.name` MUST be`session.start` +[EventName](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.40.0/specification/logs/data-model.md#field-eventname) MUST be`session.start` For instrumentation that tracks user behavior during user sessions, a `session.start` event MUST be emitted every time a session is created. When a new session is created as a continuation of a prior session, @@ -61,7 +61,7 @@ that the previous session has ended. If the session ID in `session.previous_id` ![Experimental](https://img.shields.io/badge/-experimental-blue) -`event.name` MUST be `session.end` +[EventName](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.40.0/specification/logs/data-model.md#field-eventname) MUST be `session.end` For instrumentation that tracks user behavior during user sessions, a `session.end` event SHOULD be emitted every time a session ends. When a session ends and continues as a new session, this event SHOULD be diff --git a/docs/hardware/common.md b/docs/hardware/common.md index 1cd19a999b..8cf4f354cc 100644 --- a/docs/hardware/common.md +++ b/docs/hardware/common.md @@ -246,7 +246,7 @@ This metric is [recommended][MetricRecommended]. | -------- | --------------- | ----------- | -------------- | --------- | | `hw.status` | UpDownCounter | `1` | Operational status: `1` (true) or `0` (false) for each of the possible states [1] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -**[1]:** `hw.status` is currently specified as an *UpDownCounter* but would ideally be represented using a [*StateSet* as defined in OpenMetrics](https://github.com/OpenObservability/OpenMetrics/blob/main/specification/OpenMetrics.md#stateset). This semantic convention will be updated once *StateSet* is specified in OpenTelemetry. This planned change is not expected to have any consequence on the way users query their timeseries backend to retrieve the values of `hw.status` over time. +**[1]:** `hw.status` is currently specified as an *UpDownCounter* but would ideally be represented using a [*StateSet* as defined in OpenMetrics](https://github.com/prometheus/OpenMetrics/blob/v1.0.0/specification/OpenMetrics.md#stateset). This semantic convention will be updated once *StateSet* is specified in OpenTelemetry. This planned change is not expected to have any consequence on the way users query their timeseries backend to retrieve the values of `hw.status` over time. | Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | |---|---|---|---|---|---| diff --git a/docs/messaging/messaging-spans.md b/docs/messaging/messaging-spans.md index 73a90bdd81..cda4fcfa54 100644 --- a/docs/messaging/messaging-spans.md +++ b/docs/messaging/messaging-spans.md @@ -191,19 +191,24 @@ Messaging spans SHOULD follow the overall [guidelines for span names](https://gi -The **span name** SHOULD be `{messaging.operation.name} {destination}` (see below for the exact definition of the [`{destination}`](#destination-placeholder) placeholder). +The **span name** SHOULD be `{messaging.operation.name} {destination}` +(see below for the exact definition of the [`{destination}`](#destination-placeholder) placeholder). -Semantic conventions for individual messaging systems MAY specify different span name format and then MUST document it in semantic conventions for specific messaging technologies. +Semantic conventions for individual messaging systems MAY specify different +span name format and then MUST document it in semantic conventions +for specific messaging technologies. -The `{destination}` SHOULD describe the entity that the operation is performed against +The `{destination}` +SHOULD describe the entity that the operation is performed against and SHOULD adhere to one of the following values, provided they are accessible: 1. `messaging.destination.template` SHOULD be used when it is available. 2. `messaging.destination.name` SHOULD be used when the destination is known to be neither [temporary nor anonymous](#temporary-and-anonymous-destinations). 3. `server.address:server.port` SHOULD be used only for operations not targeting any specific destination(s). -If a corresponding `{destination}` value is not available for a specific operation, the instrumentation SHOULD omit the `{destination}`. +If a (low-cardinality) corresponding `{destination}` value is not available for +a specific operation, the instrumentation SHOULD omit the `{destination}`. Examples: diff --git a/docs/mobile/events.md b/docs/mobile/events.md index df2e4bb7e2..e81a7da8b2 100644 --- a/docs/mobile/events.md +++ b/docs/mobile/events.md @@ -4,7 +4,7 @@ This document defines semantic conventions for instrumentations that emit events on mobile platforms. All mobile events MUST use a namespace of -`device` in the `event.name` property. +`device` in the EventName LogRecord property. diff --git a/docs/object-stores/s3.md b/docs/object-stores/s3.md index 67ce9cd98b..9624771191 100644 --- a/docs/object-stores/s3.md +++ b/docs/object-stores/s3.md @@ -21,6 +21,7 @@ described on this page. | Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | |---|---|---|---|---|---| | [`rpc.system`](/docs/attributes-registry/rpc.md) | string | The value `aws-api`. | `aws-api` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`aws.extended_request_id`](/docs/attributes-registry/aws.md) | string | The AWS extended request ID as returned in the response header `x-amz-id-2`. | `wzHcyEWfmOGDIE5QOhTAqFDoDWP3y8IUvpNINCwL9N4TEHbUw0/gZJ+VZTmCNCWR7fezEN3eCiQ=` | `Conditionally Required` If available. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`aws.request_id`](/docs/attributes-registry/aws.md) | string | The AWS request ID as returned in the response headers `x-amz-request-id` or `x-amz-requestid`. | `79b9da39-b7ae-508a-a6bc-864b2829c622`; `C9ER4AJX75574TDJ` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`aws.s3.bucket`](/docs/attributes-registry/aws.md) | string | The S3 bucket name the request refers to. Corresponds to the `--bucket` parameter of the [S3 API](https://docs.aws.amazon.com/cli/latest/reference/s3api/index.html) operations. [1] | `some-bucket-name` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`aws.s3.copy_source`](/docs/attributes-registry/aws.md) | string | The source object (in the form `bucket`/`key`) for the copy operation. [2] | `someFile.yml` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | diff --git a/docs/resource/process.md b/docs/resource/process.md index 52623f2a50..87689be8bd 100644 --- a/docs/resource/process.md +++ b/docs/resource/process.md @@ -57,7 +57,7 @@ **[5] `process.executable.path`:** See [Selecting process attributes](#selecting-process-attributes) for details. -**[6] `process.linux.cgroup`:** Control groups (cgroups) are a kernel feature used to organize and manage process resources. This attribute provides the path(s) to the cgroup(s) associated with the process, which should match the contents of the [/proc//cgroup](https://man7.org/linux/man-pages/man7/cgroups.7.html) file. +**[6] `process.linux.cgroup`:** Control groups (cgroups) are a kernel feature used to organize and manage process resources. This attribute provides the path(s) to the cgroup(s) associated with the process, which should match the contents of the [/proc/\[PID\]/cgroup](https://man7.org/linux/man-pages/man7/cgroups.7.html) file. diff --git a/model/artifact/registry.yaml b/model/artifact/registry.yaml index 11cb388eb6..4f6dd98419 100644 --- a/model/artifact/registry.yaml +++ b/model/artifact/registry.yaml @@ -1,6 +1,7 @@ groups: - id: registry.artifact type: attribute_group + display_name: Artifact Attributes brief: > This group describes attributes specific to artifacts. Artifacts are files or other immutable objects that are intended for distribution. This diff --git a/model/aws/registry.yaml b/model/aws/registry.yaml index 43e736725a..4c8a39ae7b 100644 --- a/model/aws/registry.yaml +++ b/model/aws/registry.yaml @@ -12,6 +12,12 @@ groups: examples: - 79b9da39-b7ae-508a-a6bc-864b2829c622 - C9ER4AJX75574TDJ + - id: aws.extended_request_id + type: string + stability: experimental + brief: "The AWS extended request ID as returned in the response header `x-amz-id-2`." + examples: + - wzHcyEWfmOGDIE5QOhTAqFDoDWP3y8IUvpNINCwL9N4TEHbUw0/gZJ+VZTmCNCWR7fezEN3eCiQ= - id: registry.aws.dynamodb type: attribute_group display_name: Amazon DynamoDB Attributes diff --git a/model/aws/sdk-spans.yml b/model/aws/sdk-spans.yml index 59f8c5b783..da6082f5e8 100644 --- a/model/aws/sdk-spans.yml +++ b/model/aws/sdk-spans.yml @@ -29,6 +29,9 @@ groups: - PutItem - ref: aws.request_id requirement_level: recommended + - ref: aws.extended_request_id + requirement_level: + conditionally_required: If available. - id: span.dynamodb.batchgetitem.client brief: DynamoDB.BatchGetItem diff --git a/model/azure/registry.yaml b/model/azure/registry.yaml index 2fdd5c9501..dea2e1dd83 100644 --- a/model/azure/registry.yaml +++ b/model/azure/registry.yaml @@ -1,6 +1,7 @@ groups: - id: registry.azure.sdk type: attribute_group + display_name: Azure SDK Attributes brief: > This document defines generic attributes for Azure SDK. attributes: diff --git a/model/cicd/registry.yaml b/model/cicd/registry.yaml index b01ff09c72..a63903d2c6 100644 --- a/model/cicd/registry.yaml +++ b/model/cicd/registry.yaml @@ -1,6 +1,7 @@ groups: - id: registry.cicd.pipeline type: attribute_group + display_name: CI/CD Pipeline Attributes brief: > This group describes attributes specific to pipelines within a Continuous Integration and Continuous Deployment (CI/CD) system. A diff --git a/model/cloudfoundry/registry.yaml b/model/cloudfoundry/registry.yaml index cf1a2f65b6..bdd701c818 100644 --- a/model/cloudfoundry/registry.yaml +++ b/model/cloudfoundry/registry.yaml @@ -1,6 +1,7 @@ groups: - id: registry.cloudfoundry type: attribute_group + display_name: CloudFoundry Attributes brief: > CloudFoundry resource attributes. attributes: diff --git a/model/event/common.yaml b/model/event/common.yaml deleted file mode 100644 index 8e68c5a909..0000000000 --- a/model/event/common.yaml +++ /dev/null @@ -1,9 +0,0 @@ -groups: - - id: event - type: attribute_group - stability: experimental - brief: > - This document defines attributes for Events represented using Log Records. - attributes: - - ref: event.name - requirement_level: required diff --git a/model/event/registry.yaml b/model/event/deprecated/registry-deprecated.yaml similarity index 51% rename from model/event/registry.yaml rename to model/event/deprecated/registry-deprecated.yaml index c8c540e052..37f2da56b3 100644 --- a/model/event/registry.yaml +++ b/model/event/deprecated/registry-deprecated.yaml @@ -1,5 +1,5 @@ groups: - - id: registry.event + - id: registry.event.deprecated type: attribute_group display_name: Event Attributes brief: > @@ -8,11 +8,7 @@ groups: - id: event.name type: string stability: experimental + deprecated: "Replaced by EventName top-level field on the LogRecord" brief: > Identifies the class / type of event. - note: > - Event names are subject to the same rules as [attribute names](/docs/general/attribute-naming.md). - Notably, event names are namespaced to avoid collisions and provide a clean - separation of semantics for events in separate domains like browser, mobile, and - kubernetes. examples: ["browser.mouse.click", "device.app.lifecycle"] diff --git a/model/gen-ai/events.yaml b/model/gen-ai/events.yaml index e8e3b40967..ac97d5402c 100644 --- a/model/gen-ai/events.yaml +++ b/model/gen-ai/events.yaml @@ -12,32 +12,172 @@ groups: type: event stability: experimental brief: > - This event describes the instructions passed to the GenAI system inside the prompt. + This event describes the system instructions passed to the GenAI model. extends: gen_ai.common.event.attributes + body: + id: gen_ai.system.message + requirement_level: opt_in + type: map + fields: + - id: content + type: undefined + stability: experimental + brief: > + The contents of the system message. + examples: ["You're a helpful bot"] + requirement_level: opt_in + - id: role + type: string + stability: experimental + brief: > + The actual role of the message author as passed in the message. + examples: ["system", "instruction"] + requirement_level: + conditionally_required: if available and not equal to `system`. - id: event.gen_ai.user.message name: gen_ai.user.message type: event stability: experimental brief: > - This event describes the prompt message specified by the user. + This event describes the user message passed to the GenAI model. extends: gen_ai.common.event.attributes + body: + id: gen_ai.user.message + requirement_level: opt_in + type: map + fields: + - id: content + type: undefined + stability: experimental + brief: > + The contents of the user message. + examples: ["What's the weather in Paris?"] + requirement_level: opt_in + - id: role + type: string + stability: experimental + brief: > + The actual role of the message author as passed in the message. + examples: ["user", "customer"] + requirement_level: + conditionally_required: if available and not equal to `user`. - id: event.gen_ai.assistant.message name: gen_ai.assistant.message type: event stability: experimental brief: > - This event describes the assistant message passed to GenAI system or received from it. + This event describes the assistant message passed to GenAI system. extends: gen_ai.common.event.attributes + body: + id: gen_ai.assistant.message + requirement_level: opt_in + type: map + fields: + - id: content + type: undefined + stability: experimental + brief: > + The contents of the tool message. + examples: ["The weather in Paris is rainy and overcast, with temperatures around 57°F"] + requirement_level: opt_in + - id: role + type: string + stability: experimental + brief: > + The actual role of the message author as passed in the message. + examples: ["assistant", "bot"] + requirement_level: + conditionally_required: if available and not equal to `assistant`. + - id: tool_calls + type: map[] + stability: experimental + brief: > + The tool calls generated by the model, such as function calls. + requirement_level: + conditionally_required: if available + fields: + - id: id + type: string + stability: experimental + brief: > + The id of the tool call. + examples: ["call_mszuSIzqtI65i1wAUOE8w5H4"] + requirement_level: required + - id: type + type: enum + members: + - id: function + value: 'function' + brief: Function + stability: experimental + brief: > + The type of the tool. + examples: ["function"] + requirement_level: required + - id: function + type: map + stability: experimental + brief: > + The function call. + requirement_level: required + fields: + - id: name + type: string + stability: experimental + brief: > + The name of the function. + examples: ["get_weather"] + requirement_level: required + - id: arguments + type: undefined + stability: experimental + brief: > + The arguments of the function as provided in the LLM response. + note: > + Models usually return arguments as a JSON string. In this case, it's + RECOMMENDED to provide arguments as is without attempting to deserialize them. + + Semantic conventions for individual systems MAY specify a different type for + arguments field. + examples: ['{\"location\": \"Paris\"}'] + requirement_level: opt_in - id: event.gen_ai.tool.message name: gen_ai.tool.message type: event stability: experimental brief: > - This event describes the tool or function response message. + This event describes the response from a tool or function call passed to the GenAI model. extends: gen_ai.common.event.attributes + body: + id: gen_ai.tool.message + requirement_level: opt_in + type: map + fields: + - id: content + type: undefined + stability: experimental + brief: > + The contents of the tool message. + examples: ["rainy, 57°F"] + requirement_level: opt_in + - id: role + type: string + stability: experimental + brief: > + The actual role of the message author as passed in the message. + examples: ["tool", "function"] + requirement_level: + conditionally_required: if available and not equal to `tool`. + - id: id + type: string + stability: experimental + brief: > + Tool call id that this message is responding to. + examples: ["call_mszuSIzqtI65i1wAUOE8w5H4"] + requirement_level: required - id: event.gen_ai.choice name: gen_ai.choice @@ -46,3 +186,123 @@ groups: brief: > This event describes the Gen AI response message. extends: gen_ai.common.event.attributes + body: + id: gen_ai.choice + requirement_level: opt_in + type: map + note: > + If GenAI model returns multiple choices, each choice SHOULD be recorded as an individual event. + When response is streamed, instrumentations that report response events MUST reconstruct and report + the full message and MUST NOT report individual chunks as events. + If the request to GenAI model fails with an error before content is received, + instrumentation SHOULD report an event with truncated content (if enabled). + If `finish_reason` was not received, it MUST be set to `error`. + fields: + - id: index + type: int + stability: experimental + brief: > + The index of the choice in the list of choices. + examples: [0, 1] + requirement_level: required + - id: finish_reason + type: enum + members: + - id: stop + value: 'stop' + stability: experimental + brief: Stop + - id: tool_calls + value: 'tool_calls' + stability: experimental + brief: Tool Calls + - id: content_filter + value: 'content_filter' + stability: experimental + brief: Content Filter + - id: length + value: 'length' + stability: experimental + brief: Length + - id: error + value: 'error' + stability: experimental + brief: Error + stability: experimental + brief: > + The reason the model stopped generating tokens. + requirement_level: required + - id: message + type: map + stability: experimental + brief: > + GenAI response message. + requirement_level: recommended + fields: + - id: content + type: undefined + stability: experimental + brief: > + The contents of the assistant message. + examples: ["The weather in Paris is rainy and overcast, with temperatures around 57°F"] + requirement_level: opt_in + - id: role + type: string + stability: experimental + brief: > + The actual role of the message author as passed in the message. + examples: ["assistant", "bot"] + requirement_level: + conditionally_required: if available and not equal to `assistant`. + - id: tool_calls + type: map[] + stability: experimental + brief: > + The tool calls generated by the model, such as function calls. + requirement_level: + conditionally_required: if available + fields: + - id: id + type: string + stability: experimental + brief: > + The id of the tool call. + examples: ["call_mszuSIzqtI65i1wAUOE8w5H4"] + requirement_level: required + - id: type + type: enum + members: + - id: function + value: 'function' + brief: Function + stability: experimental + brief: > + The type of the tool. + requirement_level: required + - id: function + type: map + stability: experimental + brief: > + The function that the model called. + requirement_level: required + fields: + - id: name + type: string + stability: experimental + brief: > + The name of the function. + examples: ["get_weather"] + requirement_level: required + - id: arguments + type: undefined + stability: experimental + brief: > + The arguments of the function as provided in the LLM response. + note: > + Models usually return arguments as a JSON string. In this case, it's + RECOMMENDED to provide arguments as is without attempting to deserialize them. + + Semantic conventions for individual systems MAY specify a different type for + arguments field. + examples: ['{\"location\": \"Paris\"}'] + requirement_level: opt_in diff --git a/model/hardware/common-metrics.yaml b/model/hardware/common-metrics.yaml index 9ae9de1cd8..d57ea702e1 100644 --- a/model/hardware/common-metrics.yaml +++ b/model/hardware/common-metrics.yaml @@ -56,7 +56,7 @@ groups: extends: metric.hw.attributes note: > `hw.status` is currently specified as an *UpDownCounter* but would ideally be represented using a - [*StateSet* as defined in OpenMetrics](https://github.com/OpenObservability/OpenMetrics/blob/main/specification/OpenMetrics.md#stateset). + [*StateSet* as defined in OpenMetrics](https://github.com/prometheus/OpenMetrics/blob/v1.0.0/specification/OpenMetrics.md#stateset). This semantic convention will be updated once *StateSet* is specified in OpenTelemetry. This planned change is not expected to have any consequence on the way users query their timeseries backend to retrieve the values of `hw.status` over time. diff --git a/model/hardware/registry.yaml b/model/hardware/registry.yaml index 248484b193..0eb30a5fc3 100644 --- a/model/hardware/registry.yaml +++ b/model/hardware/registry.yaml @@ -1,6 +1,7 @@ groups: - id: registry.hardware type: attribute_group + display_name: Hardware Attributes brief: > Attributes for hardware. attributes: diff --git a/model/linux/registry.yaml b/model/linux/registry.yaml index a3bf3f1554..68f6398acb 100644 --- a/model/linux/registry.yaml +++ b/model/linux/registry.yaml @@ -2,6 +2,7 @@ groups: # linux.memory.* attribute group - id: registry.linux.memory type: attribute_group + display_name: Linux Memory Attributes brief: "Describes Linux Memory attributes" attributes: - id: linux.memory.slab.state diff --git a/model/process/registry.yaml b/model/process/registry.yaml index ebcd9012e8..4e2c32e4f1 100644 --- a/model/process/registry.yaml +++ b/model/process/registry.yaml @@ -254,5 +254,5 @@ groups: manage process resources. This attribute provides the path(s) to the cgroup(s) associated with the process, which should match the contents of the - [/proc//cgroup](https://man7.org/linux/man-pages/man7/cgroups.7.html) + [/proc/\[PID\]/cgroup](https://man7.org/linux/man-pages/man7/cgroups.7.html) file. diff --git a/model/profile/registry.yaml b/model/profile/registry.yaml index 8bbac2ef51..d5d6649d0a 100644 --- a/model/profile/registry.yaml +++ b/model/profile/registry.yaml @@ -2,6 +2,7 @@ groups: - id: registry.profile.frame type: attribute_group + display_name: Profile Frame Attributes brief: > Describes the origin of a single frame in a Profile. attributes: @@ -11,7 +12,6 @@ groups: Describes the interpreter or compiler of a single frame. examples: ['cpython'] type: - allow_custom_values: true members: - id: dotnet brief: > diff --git a/model/test/registry.yaml b/model/test/registry.yaml index abc97af06f..cb7b8d2985 100644 --- a/model/test/registry.yaml +++ b/model/test/registry.yaml @@ -1,6 +1,7 @@ groups: - id: registry.test type: attribute_group + display_name: Test Attributes brief: > This group describes attributes specific to [software tests](https://wikipedia.org/wiki/Software_testing). diff --git a/model/vcs/registry.yaml b/model/vcs/registry.yaml index 8b61583e0b..d9e96deb9e 100644 --- a/model/vcs/registry.yaml +++ b/model/vcs/registry.yaml @@ -1,6 +1,7 @@ groups: - id: registry.vcs.repository type: attribute_group + display_name: VCS Repository Attributes brief: > This group defines the attributes for [Version Control Systems (VCS)](https://wikipedia.org/wiki/Version_control). diff --git a/templates/registry/markdown/body_field_table.j2 b/templates/registry/markdown/body_field_table.j2 index ca97a077f0..b600f6dd7f 100644 --- a/templates/registry/markdown/body_field_table.j2 +++ b/templates/registry/markdown/body_field_table.j2 @@ -6,7 +6,10 @@ {% macro flatten(fields, ns, depth) %}{% if fields %}{% for f in fields | sort(attribute="id") %} {% set ns.flat = [ns.flat, [{'field':f,'depth':depth}]] | flatten %}{% if f.fields %}{% set _= flatten(f.fields, ns, depth + 1) %}{% endif %} {% endfor %}{% endif %}{% endmacro %} -{% macro field_name(field, depth) %}{% set name= " " * 2 * depth ~ '`' ~ field.id ~ '`' %}{% if field.type == "map" %}{{ name ~ ":"}}{% else %}{{ name }}{% endif %}{% endmacro %} +{% macro field_name(field, depth) -%} +{%- set name= " " * 2 * depth ~ '`' ~ field.id ~ '`' -%} +{%- if (field.type == "map") or (field.type == "map[]") %}{{ name ~ ":"}}{% else -%} +{{ name }}{% endif %}{% endmacro %} {#- Macro for creating body table -#} {% macro generate(fields) %}{% if (fields | length > 0) %}{% set ns = namespace(flat=[])%}{% set _ = flatten(fields, ns, 0) %}| Body Field | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | |---|---|---|---|---|---|