From 005a551d0847a324e5d3eaa0f42dd0f2150049b9 Mon Sep 17 00:00:00 2001 From: Michael Aaron Safyan Date: Wed, 16 Apr 2025 12:25:24 -0400 Subject: [PATCH 1/8] Define dynamic request attribute for Google generative AI systems and create a GCP-specific variants of the Gen AI documentation in support of this. --- docs/attributes-registry/gcp.md | 13 ++++ docs/gen-ai/README.md | 1 + docs/gen-ai/gcp.md | 128 ++++++++++++++++++++++++++++++++ model/gcp/gen-ai.yaml | 33 ++++++++ model/gcp/registry.yaml | 25 +++++++ model/gen-ai/spans.yaml | 16 ++++ 6 files changed, 216 insertions(+) create mode 100644 docs/gen-ai/gcp.md create mode 100644 model/gcp/gen-ai.yaml diff --git a/docs/attributes-registry/gcp.md b/docs/attributes-registry/gcp.md index 04365844ab..6155cd7eda 100644 --- a/docs/attributes-registry/gcp.md +++ b/docs/attributes-registry/gcp.md @@ -7,6 +7,7 @@ - [GCP Client Attributes](#gcp-client-attributes) - [GCP - Google Cloud Run Attributes](#gcp---google-cloud-run-attributes) - [GCP - Google Compute Engine (GCE) Attributes](#gcp---google-compute-engine-gce-attributes) +- [Generative AI Attributes](#generative-ai-attributes) ## GCP - AppHub Attributes @@ -103,3 +104,15 @@ This document defines attributes for Google Compute Engine (GCE). |---|---|---|---|---| | `gcp.gce.instance.hostname` | string | The hostname of a GCE instance. This is the full value of the default or [custom hostname](https://cloud.google.com/compute/docs/instances/custom-hostname-vm). | `my-host1234.example.com`; `sample-vm.us-west1-b.c.my-project.internal` | ![Development](https://img.shields.io/badge/-development-blue) | | `gcp.gce.instance.name` | string | The instance name of a GCE instance. This is the value provided by `host.name`, the visible name of the instance in the Cloud Console UI, and the prefix for the default hostname of the instance as defined by the [default internal DNS name](https://cloud.google.com/compute/docs/internal-dns#instance-fully-qualified-domain-names). | `instance-1`; `my-vm-name` | ![Development](https://img.shields.io/badge/-development-blue) | + +## Generative AI Attributes + +This documents defines attributes for Google generative AI systems. + +| Attribute | Type | Description | Examples | Stability | +|---|---|---|---|---| +| `gcp.gen_ai.request.` | string[] | Request configuration options named in a Google-specific manner. [6] | | ![Development](https://img.shields.io/badge/-development-blue) | + +**[6] `gcp.gen_ai.request`:** Key names are derived from the data structures in the Google Gen AI SDK ("google.genai.types.*" in https://github.com/googleapis/python-genai). +Key names are dependent on the particular operation in question. Each operation has its corresponding "*Config" data structure; for example, the "generate_content" operation has "GenerateContentConfig", while "generate_images" has a corresponding "GenerateImagesConfig". +Key names correspond to a flattened version of the config data structure. For example {"foo": {"bar": {"baz": 5}}} results in a key called "gcp.gen_ai.request.foo.bar.baz" with value 5. diff --git a/docs/gen-ai/README.md b/docs/gen-ai/README.md index eb3c63cbef..7fd2337fea 100644 --- a/docs/gen-ai/README.md +++ b/docs/gen-ai/README.md @@ -21,5 +21,6 @@ Technology specific semantic conventions are defined for the following GenAI sys * [Azure AI Inference](./azure-ai-inference.md): Semantic Conventions for Azure AI Inference. * [OpenAI](./openai.md): Semantic Conventions for OpenAI. +* [Google Generative AI](./gcp.md): Semantic Conventions for Gemini and Vertex AI. [DocumentStatus]: https://opentelemetry.io/docs/specs/otel/document-status diff --git a/docs/gen-ai/gcp.md b/docs/gen-ai/gcp.md new file mode 100644 index 0000000000..fb882345c7 --- /dev/null +++ b/docs/gen-ai/gcp.md @@ -0,0 +1,128 @@ + + +# Semantic conventions for Google Generative AI operations + +**Status**: [Development][DocumentStatus] + +The Semantic Conventions for [Gemini](https://ai.google.dev/gemini-api/docs) and [Vertex AI](https://cloud.google.com/vertex-ai) extend and override the [GenAI Semantic Conventions](README.md). + +## Spans + + + + + + + + +**Status:** ![Development](https://img.shields.io/badge/-development-blue) + +Semantic Conventions for model inference spans when calling Google systems. + +`gen_ai.system` MUST be set to `"gcp.gen_ai"`, `"gcp.vertex_ai"`, or `"gcp.gemini"`. + +**Span kind** SHOULD be `CLIENT`. + +**Span status** SHOULD follow the [Recording Errors](/docs/general/recording-errors.md) document. + +| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | +|---|---|---|---|---|---| +| [`gen_ai.operation.name`](/docs/attributes-registry/gen-ai.md) | string | The name of the operation being performed. [1] | `chat`; `generate_content`; `text_completion` | `Required` | ![Development](https://img.shields.io/badge/-development-blue) | +| [`error.type`](/docs/attributes-registry/error.md) | string | Describes a class of error the operation ended with. [2] | `timeout`; `java.net.UnknownHostException`; `server_certificate_invalid`; `500` | `Conditionally Required` if the operation ended in an error | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| [`gcp.client.service`](/docs/attributes-registry/gcp.md) | string | Identifies the Google Cloud service for which the official client library is intended. [3] | `appengine`; `run`; `firestore`; `alloydb`; `spanner` | `Conditionally Required` If available | ![Development](https://img.shields.io/badge/-development-blue) | +| [`gen_ai.output.type`](/docs/attributes-registry/gen-ai.md) | string | Represents the content type requested by the client. [4] | `text`; `json`; `image` | `Conditionally Required` [5] | ![Development](https://img.shields.io/badge/-development-blue) | +| [`gen_ai.request.choice.count`](/docs/attributes-registry/gen-ai.md) | int | The target number of candidate completions to return. | `3` | `Conditionally Required` if available, in the request, and !=1 | ![Development](https://img.shields.io/badge/-development-blue) | +| [`gen_ai.request.model`](/docs/attributes-registry/gen-ai.md) | string | The name of the GenAI model a request is being made to. [6] | `gpt-4` | `Conditionally Required` If available. | ![Development](https://img.shields.io/badge/-development-blue) | +| [`gen_ai.request.seed`](/docs/attributes-registry/gen-ai.md) | int | Requests with same seed value more likely to return same result. | `100` | `Conditionally Required` if applicable and if the request includes a seed | ![Development](https://img.shields.io/badge/-development-blue) | +| [`server.port`](/docs/attributes-registry/server.md) | int | GenAI server port. [7] | `80`; `8080`; `443` | `Conditionally Required` If `server.address` is set. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| [`gen_ai.request.encoding_formats`](/docs/attributes-registry/gen-ai.md) | string[] | The encoding formats requested in an embeddings operation, if specified. [8] | `["base64"]`; `["float", "binary"]` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | +| [`gen_ai.request.frequency_penalty`](/docs/attributes-registry/gen-ai.md) | double | The frequency penalty setting for the GenAI request. | `0.1` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | +| [`gen_ai.request.max_tokens`](/docs/attributes-registry/gen-ai.md) | int | The maximum number of tokens the model generates for a request. | `100` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | +| [`gen_ai.request.presence_penalty`](/docs/attributes-registry/gen-ai.md) | double | The presence penalty setting for the GenAI request. | `0.1` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | +| [`gen_ai.request.stop_sequences`](/docs/attributes-registry/gen-ai.md) | string[] | List of sequences that the model will use to stop generating further tokens. | `["forest", "lived"]` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | +| [`gen_ai.request.temperature`](/docs/attributes-registry/gen-ai.md) | double | The temperature setting for the GenAI request. | `0.0` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | +| [`gen_ai.request.top_p`](/docs/attributes-registry/gen-ai.md) | double | The top_p sampling setting for the GenAI request. | `1.0` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | +| [`gen_ai.response.finish_reasons`](/docs/attributes-registry/gen-ai.md) | string[] | Array of reasons the model stopped generating tokens, corresponding to each generation received. | `["stop"]`; `["stop", "length"]` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | +| [`gen_ai.response.id`](/docs/attributes-registry/gen-ai.md) | string | The unique identifier for the completion. | `chatcmpl-123` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | +| [`gen_ai.response.model`](/docs/attributes-registry/gen-ai.md) | string | The name of the model that generated the response. [9] | `gpt-4-0613` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | +| [`gen_ai.usage.input_tokens`](/docs/attributes-registry/gen-ai.md) | int | The number of tokens used in the GenAI input (prompt). | `100` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | +| [`gen_ai.usage.output_tokens`](/docs/attributes-registry/gen-ai.md) | int | The number of tokens used in the GenAI response (completion). | `180` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | +| [`server.address`](/docs/attributes-registry/server.md) | string | GenAI server address. [10] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | `Recommended` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| [`gcp.gen_ai.request.`](/docs/attributes-registry/gcp.md) | string[] | Request configuration options named in a Google-specific manner. [11] | | `Opt-In` | ![Development](https://img.shields.io/badge/-development-blue) | + +**[1] `gen_ai.operation.name`:** If one of the predefined values applies, but specific system uses a different name it's RECOMMENDED to document it in the semantic conventions for specific GenAI system and use system-specific name in the instrumentation. If a different name is not documented, instrumentation libraries SHOULD use applicable predefined value. + +**[2] `error.type`:** The `error.type` SHOULD match the error code returned by the Generative AI provider or the client library, +the canonical name of exception that occurred, or another low-cardinality error identifier. +Instrumentations SHOULD document the list of errors they report. + +**[3] `gcp.client.service`:** Intended to be a stable identifier for Google Cloud client libraries that is uniform across implementation languages. The value should be derived from the canonical service domain for the service; for example, 'foo.googleapis.com' should result in a value of 'foo'. + +**[4] `gen_ai.output.type`:** This attribute SHOULD be used when the client requests output of a specific type. The model may return zero or more outputs of this type. +This attribute specifies the output modality and not the actual output format. For example, if an image is requested, the actual output could be a URL pointing to an image file. +Additional output format details may be recorded in the future in the `gen_ai.output.{type}.*` attributes. + +**[5] `gen_ai.output.type`:** when applicable and if the request includes an output format. + +**[6] `gen_ai.request.model`:** The name of the GenAI model a request is being made to. If the model is supplied by a vendor, then the value must be the exact name of the model requested. If the model is a fine-tuned custom model, the value should have a more specific name than the base model that's been fine-tuned. + +**[7] `server.port`:** When observed from the client side, and when communicating through an intermediary, `server.port` SHOULD represent the server port behind any intermediaries, for example proxies, if it's available. + +**[8] `gen_ai.request.encoding_formats`:** In some GenAI systems the encoding formats are called embedding types. Also, some GenAI systems only accept a single format per request. + +**[9] `gen_ai.response.model`:** If available. The name of the GenAI model that provided the response. If the model is supplied by a vendor, then the value must be the exact name of the model actually used. If the model is a fine-tuned custom model, the value should have a more specific name than the base model that's been fine-tuned. + +**[10] `server.address`:** When observed from the client side, and when communicating through an intermediary, `server.address` SHOULD represent the server address behind any intermediaries, for example proxies, if it's available. + +**[11] `gcp.gen_ai.request`:** Key names are derived from the data structures in the Google Gen AI SDK ("google.genai.types.*" in https://github.com/googleapis/python-genai). +Key names are dependent on the particular operation in question. Each operation has its corresponding "*Config" data structure; for example, the "generate_content" operation has "GenerateContentConfig", while "generate_images" has a corresponding "GenerateImagesConfig". +Key names correspond to a flattened version of the config data structure. For example {"foo": {"bar": {"baz": 5}}} results in a key called "gcp.gen_ai.request.foo.bar.baz" with value 5. + +--- + +`error.type` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. + +| Value | Description | Stability | +|---|---|---| +| `_OTHER` | A fallback error value to be used when the instrumentation doesn't define a custom value. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | + +--- + +`gen_ai.operation.name` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. + +| Value | Description | Stability | +|---|---|---| +| `chat` | Chat completion operation such as [OpenAI Chat API](https://platform.openai.com/docs/api-reference/chat) | ![Development](https://img.shields.io/badge/-development-blue) | +| `create_agent` | Create GenAI agent | ![Development](https://img.shields.io/badge/-development-blue) | +| `embeddings` | Embeddings operation such as [OpenAI Create embeddings API](https://platform.openai.com/docs/api-reference/embeddings/create) | ![Development](https://img.shields.io/badge/-development-blue) | +| `execute_tool` | Execute a tool | ![Development](https://img.shields.io/badge/-development-blue) | +| `generate_content` | Multimodal content generation operation such as [Gemini Generate Content](https://ai.google.dev/api/generate-content) | ![Development](https://img.shields.io/badge/-development-blue) | +| `text_completion` | Text completions operation such as [OpenAI Completions API (Legacy)](https://platform.openai.com/docs/api-reference/completions) | ![Development](https://img.shields.io/badge/-development-blue) | + +--- + +`gen_ai.output.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 | +|---|---|---| +| `image` | Image | ![Development](https://img.shields.io/badge/-development-blue) | +| `json` | JSON object with known or unknown schema | ![Development](https://img.shields.io/badge/-development-blue) | +| `speech` | Speech | ![Development](https://img.shields.io/badge/-development-blue) | +| `text` | Plain text | ![Development](https://img.shields.io/badge/-development-blue) | + + + + + + +## Events + +Google generative AI events follow generic [Generative AI events](gen-ai-events.md). + +## Metrics + +Google generative AI metrics follow generic [Generative AI metrics](gen-ai-metrics.md). + +[DocumentStatus]: https://opentelemetry.io/docs/specs/otel/document-status diff --git a/model/gcp/gen-ai.yaml b/model/gcp/gen-ai.yaml new file mode 100644 index 0000000000..dba009b77a --- /dev/null +++ b/model/gcp/gen-ai.yaml @@ -0,0 +1,33 @@ +groups: + - id: attributes.gcp.gen_ai + type: attribute_group + name: gcp.gen_ai + stability: development + brief: > + Attributes that are used for Google generative AI systems + and that are common to multiple Google endpoints (i.e. common + to both the Vertex AI and to the Gemini API endpoints). + attributes: + - ref: gcp.gen_ai.request + + - id: attributes.gcp.vertex_ai + type: attribute_group + extends: attributes.gcp.gen_ai + name: gcp.vertex_ai + stability: development + brief: > + Attributes that are used for Vertex AI. + attributes: + - ref: gcp.client.service + note: Should be "aiplatform" for the Vertex AI endpoint. + + - id: attributes.gcp.gemini + type: attribute_group + extends: attributes.gcp.gen_ai + name: gcp.gemini + stability: development + brief: > + Attributes that are used for Gemini. + attributes: + - ref: gcp.client.service + note: Should be "generativelanguage" for the Gemini endpoint. diff --git a/model/gcp/registry.yaml b/model/gcp/registry.yaml index 0ce4b48a71..c83521944d 100644 --- a/model/gcp/registry.yaml +++ b/model/gcp/registry.yaml @@ -195,3 +195,28 @@ groups: brief: > The hostname of a GCE instance. This is the full value of the default or [custom hostname](https://cloud.google.com/compute/docs/instances/custom-hostname-vm). examples: ['my-host1234.example.com', 'sample-vm.us-west1-b.c.my-project.internal'] + + - id: registry.gcp.gen_ai + type: attribute_group + display_name: Generative AI Attributes + brief: > + This documents defines attributes for Google generative AI systems. + stability: development + attributes: + - id: gcp.gen_ai.request + stability: development + type: template[string[]] + brief: > + Request configuration options named in a Google-specific manner. + note: > + Key names are derived from the data structures in the Google + Gen AI SDK ("google.genai.types.*" in https://github.com/googleapis/python-genai). + + Key names are dependent on the particular operation in question. + Each operation has its corresponding "*Config" data structure; for + example, the "generate_content" operation has "GenerateContentConfig", + while "generate_images" has a corresponding "GenerateImagesConfig". + + Key names correspond to a flattened version of the config data + structure. For example {"foo": {"bar": {"baz": 5}}} results in + a key called "gcp.gen_ai.request.foo.bar.baz" with value 5. diff --git a/model/gen-ai/spans.yaml b/model/gen-ai/spans.yaml index 4632692b3d..3f159c4187 100644 --- a/model/gen-ai/spans.yaml +++ b/model/gen-ai/spans.yaml @@ -177,6 +177,22 @@ groups: requirement_level: conditionally_required: If not default (443). + - id: span.gen_ai.gcp.client + type: span + extends: trace.gen_ai.client.common_attributes + stability: development + brief: Semantic Conventions for model inference spans when calling Google systems. + span_kind: client + note: | + `gen_ai.system` MUST be set to `"gcp.gen_ai"`, `"gcp.vertex_ai"`, or `"gcp.gemini"`. + attributes: + - ref: gcp.gen_ai.request + requirement_level: opt_in + - ref: gcp.client.service + requirement_level: + note: Expected to be "aiplatform" (Vertex AI) or "generativelanguage" (Gemini). + conditionally_required: If available + - id: span.gen_ai.create_agent.client type: span stability: development From 0e1f9fcd61079c2eb10f4f46aca0f36836ccb7ac Mon Sep 17 00:00:00 2001 From: Michael Aaron Safyan Date: Wed, 16 Apr 2025 12:27:52 -0400 Subject: [PATCH 2/8] Add a changelog entry. --- .chloggen/gcp_genai_dynamic_req_attr.yaml | 4 ++++ 1 file changed, 4 insertions(+) create mode 100644 .chloggen/gcp_genai_dynamic_req_attr.yaml diff --git a/.chloggen/gcp_genai_dynamic_req_attr.yaml b/.chloggen/gcp_genai_dynamic_req_attr.yaml new file mode 100644 index 0000000000..368d207cff --- /dev/null +++ b/.chloggen/gcp_genai_dynamic_req_attr.yaml @@ -0,0 +1,4 @@ +change_type: enhancement +component: [gcp, gen-ai] +note: Define dynamic request attributes for Google generative AI systems. +issues: [2053] From 8833c976e2d2944e82a97b95b825d6b1e9003ac3 Mon Sep 17 00:00:00 2001 From: Michael Aaron Safyan Date: Wed, 16 Apr 2025 14:39:46 -0400 Subject: [PATCH 3/8] Fix lint issue. --- docs/attributes-registry/gcp.md | 2 +- docs/gen-ai/gcp.md | 2 +- model/gcp/registry.yaml | 2 +- 3 files changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/attributes-registry/gcp.md b/docs/attributes-registry/gcp.md index 6155cd7eda..b9de50cab4 100644 --- a/docs/attributes-registry/gcp.md +++ b/docs/attributes-registry/gcp.md @@ -113,6 +113,6 @@ This documents defines attributes for Google generative AI systems. |---|---|---|---|---| | `gcp.gen_ai.request.` | string[] | Request configuration options named in a Google-specific manner. [6] | | ![Development](https://img.shields.io/badge/-development-blue) | -**[6] `gcp.gen_ai.request`:** Key names are derived from the data structures in the Google Gen AI SDK ("google.genai.types.*" in https://github.com/googleapis/python-genai). +**[6] `gcp.gen_ai.request`:** Key names are derived from the data structures in the Google Gen AI SDK ("google.genai.types.*" in ). Key names are dependent on the particular operation in question. Each operation has its corresponding "*Config" data structure; for example, the "generate_content" operation has "GenerateContentConfig", while "generate_images" has a corresponding "GenerateImagesConfig". Key names correspond to a flattened version of the config data structure. For example {"foo": {"bar": {"baz": 5}}} results in a key called "gcp.gen_ai.request.foo.bar.baz" with value 5. diff --git a/docs/gen-ai/gcp.md b/docs/gen-ai/gcp.md index fb882345c7..716c6caf64 100644 --- a/docs/gen-ai/gcp.md +++ b/docs/gen-ai/gcp.md @@ -76,7 +76,7 @@ Additional output format details may be recorded in the future in the `gen_ai.ou **[10] `server.address`:** When observed from the client side, and when communicating through an intermediary, `server.address` SHOULD represent the server address behind any intermediaries, for example proxies, if it's available. -**[11] `gcp.gen_ai.request`:** Key names are derived from the data structures in the Google Gen AI SDK ("google.genai.types.*" in https://github.com/googleapis/python-genai). +**[11] `gcp.gen_ai.request`:** Key names are derived from the data structures in the Google Gen AI SDK ("google.genai.types.*" in ). Key names are dependent on the particular operation in question. Each operation has its corresponding "*Config" data structure; for example, the "generate_content" operation has "GenerateContentConfig", while "generate_images" has a corresponding "GenerateImagesConfig". Key names correspond to a flattened version of the config data structure. For example {"foo": {"bar": {"baz": 5}}} results in a key called "gcp.gen_ai.request.foo.bar.baz" with value 5. diff --git a/model/gcp/registry.yaml b/model/gcp/registry.yaml index c83521944d..4e26c174c5 100644 --- a/model/gcp/registry.yaml +++ b/model/gcp/registry.yaml @@ -210,7 +210,7 @@ groups: Request configuration options named in a Google-specific manner. note: > Key names are derived from the data structures in the Google - Gen AI SDK ("google.genai.types.*" in https://github.com/googleapis/python-genai). + Gen AI SDK ("google.genai.types.*" in ). Key names are dependent on the particular operation in question. Each operation has its corresponding "*Config" data structure; for From 194362bba8920738a8907220bdac62608d75f8d2 Mon Sep 17 00:00:00 2001 From: Michael Aaron Safyan Date: Thu, 17 Apr 2025 12:07:31 -0400 Subject: [PATCH 4/8] Update name, type, and add comments in response to PR feedback. --- docs/attributes-registry/gcp.md | 8 +++++--- docs/gen-ai/gcp.md | 8 +++++--- model/gcp/gen-ai.yaml | 2 +- model/gcp/registry.yaml | 25 ++++++++++++++++++++++--- model/gen-ai/spans.yaml | 2 +- 5 files changed, 34 insertions(+), 11 deletions(-) diff --git a/docs/attributes-registry/gcp.md b/docs/attributes-registry/gcp.md index b9de50cab4..ac409e712a 100644 --- a/docs/attributes-registry/gcp.md +++ b/docs/attributes-registry/gcp.md @@ -111,8 +111,10 @@ This documents defines attributes for Google generative AI systems. | Attribute | Type | Description | Examples | Stability | |---|---|---|---|---| -| `gcp.gen_ai.request.` | string[] | Request configuration options named in a Google-specific manner. [6] | | ![Development](https://img.shields.io/badge/-development-blue) | +| `gcp.gen_ai.operation.config.` | string | Request configuration options named in a Google-specific manner. [6] | | ![Development](https://img.shields.io/badge/-development-blue) | -**[6] `gcp.gen_ai.request`:** Key names are derived from the data structures in the Google Gen AI SDK ("google.genai.types.*" in ). +**[6] `gcp.gen_ai.operation.config`:** Values are actually of ANY valid attribute type -- primitives or lists of primitives (string, bool, int, double, list[string], list[bool], list[int], list[double]). The value type is presently documented as string due to to limitations in tooling; see . +Key names are derived from the data structures in the Google Gen AI SDK ("google.genai.types.*" in ). Note that similar types are present in other languages, using similar code generation; see, for example `com.google.genai.types.*` in . However, the naming in Python is canonical (e.g. key names use `lower_with_underscore` rather than `camelCase`) and should be used for formal reference. Key names are dependent on the particular operation in question. Each operation has its corresponding "*Config" data structure; for example, the "generate_content" operation has "GenerateContentConfig", while "generate_images" has a corresponding "GenerateImagesConfig". -Key names correspond to a flattened version of the config data structure. For example {"foo": {"bar": {"baz": 5}}} results in a key called "gcp.gen_ai.request.foo.bar.baz" with value 5. +Key names correspond to a flattened version of the config data structure. For example {"foo": {"bar": {"baz": 5}}} results in a key called "gcp.gen_ai.operation.config.foo.bar.baz" with value 5. +Lists containing heterogenous types or containing non-primitive types are expressed using multiple keys: a `.length` key indicating the total number of elements in the list and a `[index]` key for Each index. For example, {"foo": ["abc", 123]} results in the keys `gcp.gen_ai.operation.config.foo.length`, `gcp.gen_ai.operation.config.foo[0]`, and `gcp.gen_ai.operation.config.foo[1]`. Lists of homogenous primitive type (e.g. list[string], list[bool], list[int], list[double]) are stored in a single key; for example, {"foo": [123, 456]} results in a single key `gcp.gen_ai.operation.config.foo` whose value is `[123, 456]`. diff --git a/docs/gen-ai/gcp.md b/docs/gen-ai/gcp.md index 716c6caf64..a2f7c1f7c2 100644 --- a/docs/gen-ai/gcp.md +++ b/docs/gen-ai/gcp.md @@ -50,7 +50,7 @@ Semantic Conventions for model inference spans when calling Google systems. | [`gen_ai.usage.input_tokens`](/docs/attributes-registry/gen-ai.md) | int | The number of tokens used in the GenAI input (prompt). | `100` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | | [`gen_ai.usage.output_tokens`](/docs/attributes-registry/gen-ai.md) | int | The number of tokens used in the GenAI response (completion). | `180` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | | [`server.address`](/docs/attributes-registry/server.md) | string | GenAI server address. [10] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | `Recommended` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | -| [`gcp.gen_ai.request.`](/docs/attributes-registry/gcp.md) | string[] | Request configuration options named in a Google-specific manner. [11] | | `Opt-In` | ![Development](https://img.shields.io/badge/-development-blue) | +| [`gcp.gen_ai.operation.config.`](/docs/attributes-registry/gcp.md) | string | Request configuration options named in a Google-specific manner. [11] | | `Opt-In` | ![Development](https://img.shields.io/badge/-development-blue) | **[1] `gen_ai.operation.name`:** If one of the predefined values applies, but specific system uses a different name it's RECOMMENDED to document it in the semantic conventions for specific GenAI system and use system-specific name in the instrumentation. If a different name is not documented, instrumentation libraries SHOULD use applicable predefined value. @@ -76,9 +76,11 @@ Additional output format details may be recorded in the future in the `gen_ai.ou **[10] `server.address`:** When observed from the client side, and when communicating through an intermediary, `server.address` SHOULD represent the server address behind any intermediaries, for example proxies, if it's available. -**[11] `gcp.gen_ai.request`:** Key names are derived from the data structures in the Google Gen AI SDK ("google.genai.types.*" in ). +**[11] `gcp.gen_ai.operation.config`:** Values are actually of ANY valid attribute type -- primitives or lists of primitives (string, bool, int, double, list[string], list[bool], list[int], list[double]). The value type is presently documented as string due to to limitations in tooling; see . +Key names are derived from the data structures in the Google Gen AI SDK ("google.genai.types.*" in ). Note that similar types are present in other languages, using similar code generation; see, for example `com.google.genai.types.*` in . However, the naming in Python is canonical (e.g. key names use `lower_with_underscore` rather than `camelCase`) and should be used for formal reference. Key names are dependent on the particular operation in question. Each operation has its corresponding "*Config" data structure; for example, the "generate_content" operation has "GenerateContentConfig", while "generate_images" has a corresponding "GenerateImagesConfig". -Key names correspond to a flattened version of the config data structure. For example {"foo": {"bar": {"baz": 5}}} results in a key called "gcp.gen_ai.request.foo.bar.baz" with value 5. +Key names correspond to a flattened version of the config data structure. For example {"foo": {"bar": {"baz": 5}}} results in a key called "gcp.gen_ai.operation.config.foo.bar.baz" with value 5. +Lists containing heterogenous types or containing non-primitive types are expressed using multiple keys: a `.length` key indicating the total number of elements in the list and a `[index]` key for Each index. For example, {"foo": ["abc", 123]} results in the keys `gcp.gen_ai.operation.config.foo.length`, `gcp.gen_ai.operation.config.foo[0]`, and `gcp.gen_ai.operation.config.foo[1]`. Lists of homogenous primitive type (e.g. list[string], list[bool], list[int], list[double]) are stored in a single key; for example, {"foo": [123, 456]} results in a single key `gcp.gen_ai.operation.config.foo` whose value is `[123, 456]`. --- diff --git a/model/gcp/gen-ai.yaml b/model/gcp/gen-ai.yaml index dba009b77a..e84af123ad 100644 --- a/model/gcp/gen-ai.yaml +++ b/model/gcp/gen-ai.yaml @@ -8,7 +8,7 @@ groups: and that are common to multiple Google endpoints (i.e. common to both the Vertex AI and to the Gemini API endpoints). attributes: - - ref: gcp.gen_ai.request + - ref: gcp.gen_ai.operation.config - id: attributes.gcp.vertex_ai type: attribute_group diff --git a/model/gcp/registry.yaml b/model/gcp/registry.yaml index 4e26c174c5..4d2193a11c 100644 --- a/model/gcp/registry.yaml +++ b/model/gcp/registry.yaml @@ -203,14 +203,23 @@ groups: This documents defines attributes for Google generative AI systems. stability: development attributes: - - id: gcp.gen_ai.request + - id: gcp.gen_ai.operation.config stability: development - type: template[string[]] + type: template[string] brief: > Request configuration options named in a Google-specific manner. note: > + Values are actually of ANY valid attribute type -- primitives or + lists of primitives (string, bool, int, double, list[string], list[bool], + list[int], list[double]). The value type is presently documented as + string due to to limitations in tooling; see . + Key names are derived from the data structures in the Google Gen AI SDK ("google.genai.types.*" in ). + Note that similar types are present in other languages, using similar code generation; + see, for example `com.google.genai.types.*` in . + However, the naming in Python is canonical (e.g. key names use `lower_with_underscore` + rather than `camelCase`) and should be used for formal reference. Key names are dependent on the particular operation in question. Each operation has its corresponding "*Config" data structure; for @@ -219,4 +228,14 @@ groups: Key names correspond to a flattened version of the config data structure. For example {"foo": {"bar": {"baz": 5}}} results in - a key called "gcp.gen_ai.request.foo.bar.baz" with value 5. + a key called "gcp.gen_ai.operation.config.foo.bar.baz" with value 5. + + Lists containing heterogenous types or containing non-primitive types + are expressed using multiple keys: a `.length` key indicating the + total number of elements in the list and a `[index]` key for Each + index. For example, {"foo": ["abc", 123]} results in the keys + `gcp.gen_ai.operation.config.foo.length`, `gcp.gen_ai.operation.config.foo[0]`, + and `gcp.gen_ai.operation.config.foo[1]`. Lists of homogenous primitive type + (e.g. list[string], list[bool], list[int], list[double]) are stored in a + single key; for example, {"foo": [123, 456]} results in a single key + `gcp.gen_ai.operation.config.foo` whose value is `[123, 456]`. diff --git a/model/gen-ai/spans.yaml b/model/gen-ai/spans.yaml index 3f159c4187..0358aa8d81 100644 --- a/model/gen-ai/spans.yaml +++ b/model/gen-ai/spans.yaml @@ -186,7 +186,7 @@ groups: note: | `gen_ai.system` MUST be set to `"gcp.gen_ai"`, `"gcp.vertex_ai"`, or `"gcp.gemini"`. attributes: - - ref: gcp.gen_ai.request + - ref: gcp.gen_ai.operation.config requirement_level: opt_in - ref: gcp.client.service requirement_level: From 1119ed376b8bc611e40e1a8c8c8215de93dd990b Mon Sep 17 00:00:00 2001 From: Michael Aaron Safyan Date: Thu, 17 Apr 2025 12:08:11 -0400 Subject: [PATCH 5/8] Fix typo 'to to'. --- docs/attributes-registry/gcp.md | 2 +- docs/gen-ai/gcp.md | 2 +- model/gcp/registry.yaml | 2 +- 3 files changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/attributes-registry/gcp.md b/docs/attributes-registry/gcp.md index ac409e712a..f1ee265795 100644 --- a/docs/attributes-registry/gcp.md +++ b/docs/attributes-registry/gcp.md @@ -113,7 +113,7 @@ This documents defines attributes for Google generative AI systems. |---|---|---|---|---| | `gcp.gen_ai.operation.config.` | string | Request configuration options named in a Google-specific manner. [6] | | ![Development](https://img.shields.io/badge/-development-blue) | -**[6] `gcp.gen_ai.operation.config`:** Values are actually of ANY valid attribute type -- primitives or lists of primitives (string, bool, int, double, list[string], list[bool], list[int], list[double]). The value type is presently documented as string due to to limitations in tooling; see . +**[6] `gcp.gen_ai.operation.config`:** Values are actually of ANY valid attribute type -- primitives or lists of primitives (string, bool, int, double, list[string], list[bool], list[int], list[double]). The value type is presently documented as string due to limitations in tooling; see . Key names are derived from the data structures in the Google Gen AI SDK ("google.genai.types.*" in ). Note that similar types are present in other languages, using similar code generation; see, for example `com.google.genai.types.*` in . However, the naming in Python is canonical (e.g. key names use `lower_with_underscore` rather than `camelCase`) and should be used for formal reference. Key names are dependent on the particular operation in question. Each operation has its corresponding "*Config" data structure; for example, the "generate_content" operation has "GenerateContentConfig", while "generate_images" has a corresponding "GenerateImagesConfig". Key names correspond to a flattened version of the config data structure. For example {"foo": {"bar": {"baz": 5}}} results in a key called "gcp.gen_ai.operation.config.foo.bar.baz" with value 5. diff --git a/docs/gen-ai/gcp.md b/docs/gen-ai/gcp.md index a2f7c1f7c2..ba6884a2de 100644 --- a/docs/gen-ai/gcp.md +++ b/docs/gen-ai/gcp.md @@ -76,7 +76,7 @@ Additional output format details may be recorded in the future in the `gen_ai.ou **[10] `server.address`:** When observed from the client side, and when communicating through an intermediary, `server.address` SHOULD represent the server address behind any intermediaries, for example proxies, if it's available. -**[11] `gcp.gen_ai.operation.config`:** Values are actually of ANY valid attribute type -- primitives or lists of primitives (string, bool, int, double, list[string], list[bool], list[int], list[double]). The value type is presently documented as string due to to limitations in tooling; see . +**[11] `gcp.gen_ai.operation.config`:** Values are actually of ANY valid attribute type -- primitives or lists of primitives (string, bool, int, double, list[string], list[bool], list[int], list[double]). The value type is presently documented as string due to limitations in tooling; see . Key names are derived from the data structures in the Google Gen AI SDK ("google.genai.types.*" in ). Note that similar types are present in other languages, using similar code generation; see, for example `com.google.genai.types.*` in . However, the naming in Python is canonical (e.g. key names use `lower_with_underscore` rather than `camelCase`) and should be used for formal reference. Key names are dependent on the particular operation in question. Each operation has its corresponding "*Config" data structure; for example, the "generate_content" operation has "GenerateContentConfig", while "generate_images" has a corresponding "GenerateImagesConfig". Key names correspond to a flattened version of the config data structure. For example {"foo": {"bar": {"baz": 5}}} results in a key called "gcp.gen_ai.operation.config.foo.bar.baz" with value 5. diff --git a/model/gcp/registry.yaml b/model/gcp/registry.yaml index 4d2193a11c..7f718a94bf 100644 --- a/model/gcp/registry.yaml +++ b/model/gcp/registry.yaml @@ -212,7 +212,7 @@ groups: Values are actually of ANY valid attribute type -- primitives or lists of primitives (string, bool, int, double, list[string], list[bool], list[int], list[double]). The value type is presently documented as - string due to to limitations in tooling; see . + string due to limitations in tooling; see . Key names are derived from the data structures in the Google Gen AI SDK ("google.genai.types.*" in ). From c9ba89bdabc54653b09aff60c708a23cadfff9f6 Mon Sep 17 00:00:00 2001 From: Michael Aaron Safyan Date: Thu, 17 Apr 2025 12:12:07 -0400 Subject: [PATCH 6/8] Update attribute 'brief' description per PR feedback. --- docs/attributes-registry/gcp.md | 2 +- docs/gen-ai/gcp.md | 2 +- model/gcp/registry.yaml | 2 +- 3 files changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/attributes-registry/gcp.md b/docs/attributes-registry/gcp.md index f1ee265795..1ee178b7c1 100644 --- a/docs/attributes-registry/gcp.md +++ b/docs/attributes-registry/gcp.md @@ -111,7 +111,7 @@ This documents defines attributes for Google generative AI systems. | Attribute | Type | Description | Examples | Stability | |---|---|---|---|---| -| `gcp.gen_ai.operation.config.` | string | Request configuration options named in a Google-specific manner. [6] | | ![Development](https://img.shields.io/badge/-development-blue) | +| `gcp.gen_ai.operation.config.` | string | Gen AI operation options, `` being the flattened name of the configuration option passed to the client library. [6] | | ![Development](https://img.shields.io/badge/-development-blue) | **[6] `gcp.gen_ai.operation.config`:** Values are actually of ANY valid attribute type -- primitives or lists of primitives (string, bool, int, double, list[string], list[bool], list[int], list[double]). The value type is presently documented as string due to limitations in tooling; see . Key names are derived from the data structures in the Google Gen AI SDK ("google.genai.types.*" in ). Note that similar types are present in other languages, using similar code generation; see, for example `com.google.genai.types.*` in . However, the naming in Python is canonical (e.g. key names use `lower_with_underscore` rather than `camelCase`) and should be used for formal reference. diff --git a/docs/gen-ai/gcp.md b/docs/gen-ai/gcp.md index ba6884a2de..17a34f9e01 100644 --- a/docs/gen-ai/gcp.md +++ b/docs/gen-ai/gcp.md @@ -50,7 +50,7 @@ Semantic Conventions for model inference spans when calling Google systems. | [`gen_ai.usage.input_tokens`](/docs/attributes-registry/gen-ai.md) | int | The number of tokens used in the GenAI input (prompt). | `100` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | | [`gen_ai.usage.output_tokens`](/docs/attributes-registry/gen-ai.md) | int | The number of tokens used in the GenAI response (completion). | `180` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | | [`server.address`](/docs/attributes-registry/server.md) | string | GenAI server address. [10] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | `Recommended` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | -| [`gcp.gen_ai.operation.config.`](/docs/attributes-registry/gcp.md) | string | Request configuration options named in a Google-specific manner. [11] | | `Opt-In` | ![Development](https://img.shields.io/badge/-development-blue) | +| [`gcp.gen_ai.operation.config.`](/docs/attributes-registry/gcp.md) | string | Gen AI operation options, `` being the flattened name of the configuration option passed to the client library. [11] | | `Opt-In` | ![Development](https://img.shields.io/badge/-development-blue) | **[1] `gen_ai.operation.name`:** If one of the predefined values applies, but specific system uses a different name it's RECOMMENDED to document it in the semantic conventions for specific GenAI system and use system-specific name in the instrumentation. If a different name is not documented, instrumentation libraries SHOULD use applicable predefined value. diff --git a/model/gcp/registry.yaml b/model/gcp/registry.yaml index 7f718a94bf..68f335aaac 100644 --- a/model/gcp/registry.yaml +++ b/model/gcp/registry.yaml @@ -207,7 +207,7 @@ groups: stability: development type: template[string] brief: > - Request configuration options named in a Google-specific manner. + Gen AI operation options, `` being the flattened name of the configuration option passed to the client library. note: > Values are actually of ANY valid attribute type -- primitives or lists of primitives (string, bool, int, double, list[string], list[bool], From a750ee0f0fc9d3134db91ebbbd2916a5a6592161 Mon Sep 17 00:00:00 2001 From: Michael Aaron Safyan Date: Fri, 25 Apr 2025 18:50:22 -0400 Subject: [PATCH 7/8] Update definition per feedback in LLM SIG. --- .chloggen/gcp_genai_dynamic_req_attr.yaml | 3 +- docs/attributes-registry/gcp.md | 11 +++-- docs/gen-ai/gcp.md | 22 ++++----- model/gcp/registry.yaml | 55 +++++++++++------------ model/gen-ai/spans.yaml | 2 +- 5 files changed, 42 insertions(+), 51 deletions(-) diff --git a/.chloggen/gcp_genai_dynamic_req_attr.yaml b/.chloggen/gcp_genai_dynamic_req_attr.yaml index 368d207cff..24755a3a31 100644 --- a/.chloggen/gcp_genai_dynamic_req_attr.yaml +++ b/.chloggen/gcp_genai_dynamic_req_attr.yaml @@ -1,4 +1,5 @@ change_type: enhancement component: [gcp, gen-ai] -note: Define dynamic request attributes for Google generative AI systems. +note: Define attribute for Google generative AI operation request configuration. issues: [2053] +subtext: Defines `gcp.gen_ai.operation.config` as a JSON-valued string for recording a subset of operation configuration options. diff --git a/docs/attributes-registry/gcp.md b/docs/attributes-registry/gcp.md index 1ee178b7c1..665d6a4a84 100644 --- a/docs/attributes-registry/gcp.md +++ b/docs/attributes-registry/gcp.md @@ -111,10 +111,9 @@ This documents defines attributes for Google generative AI systems. | Attribute | Type | Description | Examples | Stability | |---|---|---|---|---| -| `gcp.gen_ai.operation.config.` | string | Gen AI operation options, `` being the flattened name of the configuration option passed to the client library. [6] | | ![Development](https://img.shields.io/badge/-development-blue) | +| `gcp.gen_ai.operation.config` | string | Operation-specific request configuration options for Google generative AI operations. +The string value should be a valid JSON dictionary. The JSON dictionary should include only an allowlisted subset of the request configuration that does not overlap with configuration that has already been captured elsewhere through standard Semantic Conventions. [6] | `{"audioTimestamp":true}`; `{"safetySettings":[{"threshold":"OFF"}]}`; `{"thinkingConfig":{"includeThoughts":true},"routingConfig":{"autoMode":{"modelRoutingPreference":"BALANCED"}}}` | ![Development](https://img.shields.io/badge/-development-blue) | -**[6] `gcp.gen_ai.operation.config`:** Values are actually of ANY valid attribute type -- primitives or lists of primitives (string, bool, int, double, list[string], list[bool], list[int], list[double]). The value type is presently documented as string due to limitations in tooling; see . -Key names are derived from the data structures in the Google Gen AI SDK ("google.genai.types.*" in ). Note that similar types are present in other languages, using similar code generation; see, for example `com.google.genai.types.*` in . However, the naming in Python is canonical (e.g. key names use `lower_with_underscore` rather than `camelCase`) and should be used for formal reference. -Key names are dependent on the particular operation in question. Each operation has its corresponding "*Config" data structure; for example, the "generate_content" operation has "GenerateContentConfig", while "generate_images" has a corresponding "GenerateImagesConfig". -Key names correspond to a flattened version of the config data structure. For example {"foo": {"bar": {"baz": 5}}} results in a key called "gcp.gen_ai.operation.config.foo.bar.baz" with value 5. -Lists containing heterogenous types or containing non-primitive types are expressed using multiple keys: a `.length` key indicating the total number of elements in the list and a `[index]` key for Each index. For example, {"foo": ["abc", 123]} results in the keys `gcp.gen_ai.operation.config.foo.length`, `gcp.gen_ai.operation.config.foo[0]`, and `gcp.gen_ai.operation.config.foo[1]`. Lists of homogenous primitive type (e.g. list[string], list[bool], list[int], list[double]) are stored in a single key; for example, {"foo": [123, 456]} results in a single key `gcp.gen_ai.operation.config.foo` whose value is `[123, 456]`. +**[6] `gcp.gen_ai.operation.config`:** The data structure is dependent on the value of "gen_ai.operation.name" and should correspond with the "*Config" data structure in the Google Gen AI SDK. The Google Gen AI SDK provides these "*Config" data structures in multiple languages, generated from a common source of truth. See "google.genai.types.*" in and `com.google.genai.types.*` in for examples. +Because the data structure is encoded in JSON format, the key names should be specified using "camelCase". More generally, the names should align with the expectations of proto3 JSON encoding ; for example, fields that represent a timestamp in the local language should get mapped to the proto3 JSON encoding of "google.protobuf.Timestamp" (i.e. RFC 3339 date format) per the specification given in . +Instrumentations should not populate this attribute by default. Rather, instrumentations should provide an opt-in mechanism through which the config information can be dumped into this field as a tool for debugging and as an escape hatch for the subset of configuration that is not yet representable using standardized conventions. diff --git a/docs/gen-ai/gcp.md b/docs/gen-ai/gcp.md index 17a34f9e01..6d0e4f74f2 100644 --- a/docs/gen-ai/gcp.md +++ b/docs/gen-ai/gcp.md @@ -37,7 +37,6 @@ Semantic Conventions for model inference spans when calling Google systems. | [`gen_ai.request.model`](/docs/attributes-registry/gen-ai.md) | string | The name of the GenAI model a request is being made to. [6] | `gpt-4` | `Conditionally Required` If available. | ![Development](https://img.shields.io/badge/-development-blue) | | [`gen_ai.request.seed`](/docs/attributes-registry/gen-ai.md) | int | Requests with same seed value more likely to return same result. | `100` | `Conditionally Required` if applicable and if the request includes a seed | ![Development](https://img.shields.io/badge/-development-blue) | | [`server.port`](/docs/attributes-registry/server.md) | int | GenAI server port. [7] | `80`; `8080`; `443` | `Conditionally Required` If `server.address` is set. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | -| [`gen_ai.request.encoding_formats`](/docs/attributes-registry/gen-ai.md) | string[] | The encoding formats requested in an embeddings operation, if specified. [8] | `["base64"]`; `["float", "binary"]` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | | [`gen_ai.request.frequency_penalty`](/docs/attributes-registry/gen-ai.md) | double | The frequency penalty setting for the GenAI request. | `0.1` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | | [`gen_ai.request.max_tokens`](/docs/attributes-registry/gen-ai.md) | int | The maximum number of tokens the model generates for a request. | `100` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | | [`gen_ai.request.presence_penalty`](/docs/attributes-registry/gen-ai.md) | double | The presence penalty setting for the GenAI request. | `0.1` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | @@ -46,11 +45,12 @@ Semantic Conventions for model inference spans when calling Google systems. | [`gen_ai.request.top_p`](/docs/attributes-registry/gen-ai.md) | double | The top_p sampling setting for the GenAI request. | `1.0` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | | [`gen_ai.response.finish_reasons`](/docs/attributes-registry/gen-ai.md) | string[] | Array of reasons the model stopped generating tokens, corresponding to each generation received. | `["stop"]`; `["stop", "length"]` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | | [`gen_ai.response.id`](/docs/attributes-registry/gen-ai.md) | string | The unique identifier for the completion. | `chatcmpl-123` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | -| [`gen_ai.response.model`](/docs/attributes-registry/gen-ai.md) | string | The name of the model that generated the response. [9] | `gpt-4-0613` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | +| [`gen_ai.response.model`](/docs/attributes-registry/gen-ai.md) | string | The name of the model that generated the response. [8] | `gpt-4-0613` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | | [`gen_ai.usage.input_tokens`](/docs/attributes-registry/gen-ai.md) | int | The number of tokens used in the GenAI input (prompt). | `100` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | | [`gen_ai.usage.output_tokens`](/docs/attributes-registry/gen-ai.md) | int | The number of tokens used in the GenAI response (completion). | `180` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | -| [`server.address`](/docs/attributes-registry/server.md) | string | GenAI server address. [10] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | `Recommended` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | -| [`gcp.gen_ai.operation.config.`](/docs/attributes-registry/gcp.md) | string | Gen AI operation options, `` being the flattened name of the configuration option passed to the client library. [11] | | `Opt-In` | ![Development](https://img.shields.io/badge/-development-blue) | +| [`server.address`](/docs/attributes-registry/server.md) | string | GenAI server address. [9] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | `Recommended` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| [`gcp.gen_ai.operation.config`](/docs/attributes-registry/gcp.md) | string | Operation-specific request configuration options for Google generative AI operations. +The string value should be a valid JSON dictionary. The JSON dictionary should include only an allowlisted subset of the request configuration that does not overlap with configuration that has already been captured elsewhere through standard Semantic Conventions. [10] | `{"audioTimestamp":true}`; `{"safetySettings":[{"threshold":"OFF"}]}`; `{"thinkingConfig":{"includeThoughts":true},"routingConfig":{"autoMode":{"modelRoutingPreference":"BALANCED"}}}` | `Opt-In` | ![Development](https://img.shields.io/badge/-development-blue) | **[1] `gen_ai.operation.name`:** If one of the predefined values applies, but specific system uses a different name it's RECOMMENDED to document it in the semantic conventions for specific GenAI system and use system-specific name in the instrumentation. If a different name is not documented, instrumentation libraries SHOULD use applicable predefined value. @@ -70,17 +70,13 @@ Additional output format details may be recorded in the future in the `gen_ai.ou **[7] `server.port`:** When observed from the client side, and when communicating through an intermediary, `server.port` SHOULD represent the server port behind any intermediaries, for example proxies, if it's available. -**[8] `gen_ai.request.encoding_formats`:** In some GenAI systems the encoding formats are called embedding types. Also, some GenAI systems only accept a single format per request. +**[8] `gen_ai.response.model`:** If available. The name of the GenAI model that provided the response. If the model is supplied by a vendor, then the value must be the exact name of the model actually used. If the model is a fine-tuned custom model, the value should have a more specific name than the base model that's been fine-tuned. -**[9] `gen_ai.response.model`:** If available. The name of the GenAI model that provided the response. If the model is supplied by a vendor, then the value must be the exact name of the model actually used. If the model is a fine-tuned custom model, the value should have a more specific name than the base model that's been fine-tuned. +**[9] `server.address`:** When observed from the client side, and when communicating through an intermediary, `server.address` SHOULD represent the server address behind any intermediaries, for example proxies, if it's available. -**[10] `server.address`:** When observed from the client side, and when communicating through an intermediary, `server.address` SHOULD represent the server address behind any intermediaries, for example proxies, if it's available. - -**[11] `gcp.gen_ai.operation.config`:** Values are actually of ANY valid attribute type -- primitives or lists of primitives (string, bool, int, double, list[string], list[bool], list[int], list[double]). The value type is presently documented as string due to limitations in tooling; see . -Key names are derived from the data structures in the Google Gen AI SDK ("google.genai.types.*" in ). Note that similar types are present in other languages, using similar code generation; see, for example `com.google.genai.types.*` in . However, the naming in Python is canonical (e.g. key names use `lower_with_underscore` rather than `camelCase`) and should be used for formal reference. -Key names are dependent on the particular operation in question. Each operation has its corresponding "*Config" data structure; for example, the "generate_content" operation has "GenerateContentConfig", while "generate_images" has a corresponding "GenerateImagesConfig". -Key names correspond to a flattened version of the config data structure. For example {"foo": {"bar": {"baz": 5}}} results in a key called "gcp.gen_ai.operation.config.foo.bar.baz" with value 5. -Lists containing heterogenous types or containing non-primitive types are expressed using multiple keys: a `.length` key indicating the total number of elements in the list and a `[index]` key for Each index. For example, {"foo": ["abc", 123]} results in the keys `gcp.gen_ai.operation.config.foo.length`, `gcp.gen_ai.operation.config.foo[0]`, and `gcp.gen_ai.operation.config.foo[1]`. Lists of homogenous primitive type (e.g. list[string], list[bool], list[int], list[double]) are stored in a single key; for example, {"foo": [123, 456]} results in a single key `gcp.gen_ai.operation.config.foo` whose value is `[123, 456]`. +**[10] `gcp.gen_ai.operation.config`:** The data structure is dependent on the value of "gen_ai.operation.name" and should correspond with the "*Config" data structure in the Google Gen AI SDK. The Google Gen AI SDK provides these "*Config" data structures in multiple languages, generated from a common source of truth. See "google.genai.types.*" in and `com.google.genai.types.*` in for examples. +Because the data structure is encoded in JSON format, the key names should be specified using "camelCase". More generally, the names should align with the expectations of proto3 JSON encoding ; for example, fields that represent a timestamp in the local language should get mapped to the proto3 JSON encoding of "google.protobuf.Timestamp" (i.e. RFC 3339 date format) per the specification given in . +Instrumentations should not populate this attribute by default. Rather, instrumentations should provide an opt-in mechanism through which the config information can be dumped into this field as a tool for debugging and as an escape hatch for the subset of configuration that is not yet representable using standardized conventions. --- diff --git a/model/gcp/registry.yaml b/model/gcp/registry.yaml index 68f335aaac..767c206503 100644 --- a/model/gcp/registry.yaml +++ b/model/gcp/registry.yaml @@ -205,37 +205,32 @@ groups: attributes: - id: gcp.gen_ai.operation.config stability: development - type: template[string] + type: string brief: > - Gen AI operation options, `` being the flattened name of the configuration option passed to the client library. - note: > - Values are actually of ANY valid attribute type -- primitives or - lists of primitives (string, bool, int, double, list[string], list[bool], - list[int], list[double]). The value type is presently documented as - string due to limitations in tooling; see . + Operation-specific request configuration options for Google generative AI operations. - Key names are derived from the data structures in the Google - Gen AI SDK ("google.genai.types.*" in ). - Note that similar types are present in other languages, using similar code generation; - see, for example `com.google.genai.types.*` in . - However, the naming in Python is canonical (e.g. key names use `lower_with_underscore` - rather than `camelCase`) and should be used for formal reference. - - Key names are dependent on the particular operation in question. - Each operation has its corresponding "*Config" data structure; for - example, the "generate_content" operation has "GenerateContentConfig", - while "generate_images" has a corresponding "GenerateImagesConfig". + The string value should be a valid JSON dictionary. The JSON dictionary should include + only an allowlisted subset of the request configuration that does not overlap with + configuration that has already been captured elsewhere through standard Semantic Conventions. + examples: + - '{"audioTimestamp":true}' + - '{"safetySettings":[{"threshold":"OFF"}]}' + - '{"thinkingConfig":{"includeThoughts":true},"routingConfig":{"autoMode":{"modelRoutingPreference":"BALANCED"}}}' + note: > + The data structure is dependent on the value of "gen_ai.operation.name" and should correspond + with the "*Config" data structure in the Google Gen AI SDK. The Google Gen AI SDK provides + these "*Config" data structures in multiple languages, generated from a common source of truth. + See "google.genai.types.*" in and + `com.google.genai.types.*` in for examples. - Key names correspond to a flattened version of the config data - structure. For example {"foo": {"bar": {"baz": 5}}} results in - a key called "gcp.gen_ai.operation.config.foo.bar.baz" with value 5. + Because the data structure is encoded in JSON format, the key names should be specified + using "camelCase". More generally, the names should align with the expectations of proto3 + JSON encoding ; for example, fields + that represent a timestamp in the local language should get mapped to the proto3 JSON + encoding of "google.protobuf.Timestamp" (i.e. RFC 3339 date format) per the specification + given in . - Lists containing heterogenous types or containing non-primitive types - are expressed using multiple keys: a `.length` key indicating the - total number of elements in the list and a `[index]` key for Each - index. For example, {"foo": ["abc", 123]} results in the keys - `gcp.gen_ai.operation.config.foo.length`, `gcp.gen_ai.operation.config.foo[0]`, - and `gcp.gen_ai.operation.config.foo[1]`. Lists of homogenous primitive type - (e.g. list[string], list[bool], list[int], list[double]) are stored in a - single key; for example, {"foo": [123, 456]} results in a single key - `gcp.gen_ai.operation.config.foo` whose value is `[123, 456]`. + Instrumentations should not populate this attribute by default. Rather, instrumentations + should provide an opt-in mechanism through which the config information can be dumped + into this field as a tool for debugging and as an escape hatch for the subset of + configuration that is not yet representable using standardized conventions. diff --git a/model/gen-ai/spans.yaml b/model/gen-ai/spans.yaml index b5f5bf529c..93d2e398e0 100644 --- a/model/gen-ai/spans.yaml +++ b/model/gen-ai/spans.yaml @@ -177,7 +177,7 @@ groups: - id: span.gen_ai.gcp.client type: span - extends: trace.gen_ai.client.common_attributes + extends: attributes.gen_ai.inference.client stability: development brief: Semantic Conventions for model inference spans when calling Google systems. span_kind: client From dd4a6f3106c0d88342b6fe642a1d4811961a89c6 Mon Sep 17 00:00:00 2001 From: Michael Aaron Safyan Date: Tue, 13 May 2025 15:34:22 -0400 Subject: [PATCH 8/8] Updated per PR feedback. --- docs/attributes-registry/gcp.md | 6 ++--- docs/gen-ai/gcp.md | 46 ++++++++++++++++++++++----------- model/gcp/registry.yaml | 15 +++++------ 3 files changed, 41 insertions(+), 26 deletions(-) diff --git a/docs/attributes-registry/gcp.md b/docs/attributes-registry/gcp.md index 665d6a4a84..3789e5f5fd 100644 --- a/docs/attributes-registry/gcp.md +++ b/docs/attributes-registry/gcp.md @@ -111,9 +111,9 @@ This documents defines attributes for Google generative AI systems. | Attribute | Type | Description | Examples | Stability | |---|---|---|---|---| -| `gcp.gen_ai.operation.config` | string | Operation-specific request configuration options for Google generative AI operations. -The string value should be a valid JSON dictionary. The JSON dictionary should include only an allowlisted subset of the request configuration that does not overlap with configuration that has already been captured elsewhere through standard Semantic Conventions. [6] | `{"audioTimestamp":true}`; `{"safetySettings":[{"threshold":"OFF"}]}`; `{"thinkingConfig":{"includeThoughts":true},"routingConfig":{"autoMode":{"modelRoutingPreference":"BALANCED"}}}` | ![Development](https://img.shields.io/badge/-development-blue) | +| `gcp.gen_ai.operation.config` | string | Operation-specific request configuration options for Google generative AI operations recorded as a JSON string. [6] | `{"audioTimestamp":true}`; `{"safetySettings":[{"threshold":"OFF"}]}`; `{"thinkingConfig":{"includeThoughts":true},"routingConfig":{"autoMode":{"modelRoutingPreference":"BALANCED"}}}` | ![Development](https://img.shields.io/badge/-development-blue) | **[6] `gcp.gen_ai.operation.config`:** The data structure is dependent on the value of "gen_ai.operation.name" and should correspond with the "*Config" data structure in the Google Gen AI SDK. The Google Gen AI SDK provides these "*Config" data structures in multiple languages, generated from a common source of truth. See "google.genai.types.*" in and `com.google.genai.types.*` in for examples. +The JSON dictionary SHOULD include only an allowlisted subset of the request configuration. The contents also SHOULD NOT overlap with configuration that has already been captured elsewhere through standard Semantic Conventions. Because the data structure is encoded in JSON format, the key names should be specified using "camelCase". More generally, the names should align with the expectations of proto3 JSON encoding ; for example, fields that represent a timestamp in the local language should get mapped to the proto3 JSON encoding of "google.protobuf.Timestamp" (i.e. RFC 3339 date format) per the specification given in . -Instrumentations should not populate this attribute by default. Rather, instrumentations should provide an opt-in mechanism through which the config information can be dumped into this field as a tool for debugging and as an escape hatch for the subset of configuration that is not yet representable using standardized conventions. +Instrumentations SHOULD NOT populate this attribute by default. Rather, instrumentations SHOULD provide an opt-in mechanism through which the config information can be dumped into this field as a tool for debugging and as an escape hatch for the subset of configuration that is not yet representable using standardized conventions. diff --git a/docs/gen-ai/gcp.md b/docs/gen-ai/gcp.md index 6d0e4f74f2..8a363f204f 100644 --- a/docs/gen-ai/gcp.md +++ b/docs/gen-ai/gcp.md @@ -32,11 +32,12 @@ Semantic Conventions for model inference spans when calling Google systems. | [`gen_ai.operation.name`](/docs/attributes-registry/gen-ai.md) | string | The name of the operation being performed. [1] | `chat`; `generate_content`; `text_completion` | `Required` | ![Development](https://img.shields.io/badge/-development-blue) | | [`error.type`](/docs/attributes-registry/error.md) | string | Describes a class of error the operation ended with. [2] | `timeout`; `java.net.UnknownHostException`; `server_certificate_invalid`; `500` | `Conditionally Required` if the operation ended in an error | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | | [`gcp.client.service`](/docs/attributes-registry/gcp.md) | string | Identifies the Google Cloud service for which the official client library is intended. [3] | `appengine`; `run`; `firestore`; `alloydb`; `spanner` | `Conditionally Required` If available | ![Development](https://img.shields.io/badge/-development-blue) | -| [`gen_ai.output.type`](/docs/attributes-registry/gen-ai.md) | string | Represents the content type requested by the client. [4] | `text`; `json`; `image` | `Conditionally Required` [5] | ![Development](https://img.shields.io/badge/-development-blue) | +| [`gen_ai.conversation.id`](/docs/attributes-registry/gen-ai.md) | string | The unique identifier for a conversation (session, thread), used to store and correlate messages within this conversation. [4] | `conv_5j66UpCpwteGg4YSxUnt7lPY` | `Conditionally Required` when available | ![Development](https://img.shields.io/badge/-development-blue) | +| [`gen_ai.output.type`](/docs/attributes-registry/gen-ai.md) | string | Represents the content type requested by the client. [5] | `text`; `json`; `image` | `Conditionally Required` [6] | ![Development](https://img.shields.io/badge/-development-blue) | | [`gen_ai.request.choice.count`](/docs/attributes-registry/gen-ai.md) | int | The target number of candidate completions to return. | `3` | `Conditionally Required` if available, in the request, and !=1 | ![Development](https://img.shields.io/badge/-development-blue) | -| [`gen_ai.request.model`](/docs/attributes-registry/gen-ai.md) | string | The name of the GenAI model a request is being made to. [6] | `gpt-4` | `Conditionally Required` If available. | ![Development](https://img.shields.io/badge/-development-blue) | +| [`gen_ai.request.model`](/docs/attributes-registry/gen-ai.md) | string | The name of the GenAI model a request is being made to. [7] | `gpt-4` | `Conditionally Required` If available. | ![Development](https://img.shields.io/badge/-development-blue) | | [`gen_ai.request.seed`](/docs/attributes-registry/gen-ai.md) | int | Requests with same seed value more likely to return same result. | `100` | `Conditionally Required` if applicable and if the request includes a seed | ![Development](https://img.shields.io/badge/-development-blue) | -| [`server.port`](/docs/attributes-registry/server.md) | int | GenAI server port. [7] | `80`; `8080`; `443` | `Conditionally Required` If `server.address` is set. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| [`server.port`](/docs/attributes-registry/server.md) | int | GenAI server port. [8] | `80`; `8080`; `443` | `Conditionally Required` If `server.address` is set. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | | [`gen_ai.request.frequency_penalty`](/docs/attributes-registry/gen-ai.md) | double | The frequency penalty setting for the GenAI request. | `0.1` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | | [`gen_ai.request.max_tokens`](/docs/attributes-registry/gen-ai.md) | int | The maximum number of tokens the model generates for a request. | `100` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | | [`gen_ai.request.presence_penalty`](/docs/attributes-registry/gen-ai.md) | double | The presence penalty setting for the GenAI request. | `0.1` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | @@ -45,12 +46,11 @@ Semantic Conventions for model inference spans when calling Google systems. | [`gen_ai.request.top_p`](/docs/attributes-registry/gen-ai.md) | double | The top_p sampling setting for the GenAI request. | `1.0` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | | [`gen_ai.response.finish_reasons`](/docs/attributes-registry/gen-ai.md) | string[] | Array of reasons the model stopped generating tokens, corresponding to each generation received. | `["stop"]`; `["stop", "length"]` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | | [`gen_ai.response.id`](/docs/attributes-registry/gen-ai.md) | string | The unique identifier for the completion. | `chatcmpl-123` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | -| [`gen_ai.response.model`](/docs/attributes-registry/gen-ai.md) | string | The name of the model that generated the response. [8] | `gpt-4-0613` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | +| [`gen_ai.response.model`](/docs/attributes-registry/gen-ai.md) | string | The name of the model that generated the response. [9] | `gpt-4-0613` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | | [`gen_ai.usage.input_tokens`](/docs/attributes-registry/gen-ai.md) | int | The number of tokens used in the GenAI input (prompt). | `100` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | | [`gen_ai.usage.output_tokens`](/docs/attributes-registry/gen-ai.md) | int | The number of tokens used in the GenAI response (completion). | `180` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | -| [`server.address`](/docs/attributes-registry/server.md) | string | GenAI server address. [9] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | `Recommended` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | -| [`gcp.gen_ai.operation.config`](/docs/attributes-registry/gcp.md) | string | Operation-specific request configuration options for Google generative AI operations. -The string value should be a valid JSON dictionary. The JSON dictionary should include only an allowlisted subset of the request configuration that does not overlap with configuration that has already been captured elsewhere through standard Semantic Conventions. [10] | `{"audioTimestamp":true}`; `{"safetySettings":[{"threshold":"OFF"}]}`; `{"thinkingConfig":{"includeThoughts":true},"routingConfig":{"autoMode":{"modelRoutingPreference":"BALANCED"}}}` | `Opt-In` | ![Development](https://img.shields.io/badge/-development-blue) | +| [`server.address`](/docs/attributes-registry/server.md) | string | GenAI server address. [10] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | `Recommended` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| [`gcp.gen_ai.operation.config`](/docs/attributes-registry/gcp.md) | string | Operation-specific request configuration options for Google generative AI operations recorded as a JSON string. [11] | `{"audioTimestamp":true}`; `{"safetySettings":[{"threshold":"OFF"}]}`; `{"thinkingConfig":{"includeThoughts":true},"routingConfig":{"autoMode":{"modelRoutingPreference":"BALANCED"}}}` | `Opt-In` | ![Development](https://img.shields.io/badge/-development-blue) | **[1] `gen_ai.operation.name`:** If one of the predefined values applies, but specific system uses a different name it's RECOMMENDED to document it in the semantic conventions for specific GenAI system and use system-specific name in the instrumentation. If a different name is not documented, instrumentation libraries SHOULD use applicable predefined value. @@ -60,23 +60,38 @@ Instrumentations SHOULD document the list of errors they report. **[3] `gcp.client.service`:** Intended to be a stable identifier for Google Cloud client libraries that is uniform across implementation languages. The value should be derived from the canonical service domain for the service; for example, 'foo.googleapis.com' should result in a value of 'foo'. -**[4] `gen_ai.output.type`:** This attribute SHOULD be used when the client requests output of a specific type. The model may return zero or more outputs of this type. +**[4] `gen_ai.conversation.id`:** Instrumentations SHOULD populate conversation id when they have it readily available +for a given operation, for example: + +- when client framework being instrumented manages conversation history +(see [LlamaIndex chat store](https://docs.llamaindex.ai/en/stable/module_guides/storing/chat_stores/)) + +- when instrumenting GenAI client libraries that maintain conversation on the backend side +(see [AWS Bedrock agent sessions](https://docs.aws.amazon.com/bedrock/latest/userguide/agents-session-state.html), +[OpenAI Assistant threads](https://platform.openai.com/docs/api-reference/threads)) + +Application developers that manage conversation history MAY add conversation id to GenAI and other +spans or logs using custom span or log record processors or hooks provided by instrumentation +libraries. + +**[5] `gen_ai.output.type`:** This attribute SHOULD be used when the client requests output of a specific type. The model may return zero or more outputs of this type. This attribute specifies the output modality and not the actual output format. For example, if an image is requested, the actual output could be a URL pointing to an image file. Additional output format details may be recorded in the future in the `gen_ai.output.{type}.*` attributes. -**[5] `gen_ai.output.type`:** when applicable and if the request includes an output format. +**[6] `gen_ai.output.type`:** when applicable and if the request includes an output format. -**[6] `gen_ai.request.model`:** The name of the GenAI model a request is being made to. If the model is supplied by a vendor, then the value must be the exact name of the model requested. If the model is a fine-tuned custom model, the value should have a more specific name than the base model that's been fine-tuned. +**[7] `gen_ai.request.model`:** The name of the GenAI model a request is being made to. If the model is supplied by a vendor, then the value must be the exact name of the model requested. If the model is a fine-tuned custom model, the value should have a more specific name than the base model that's been fine-tuned. -**[7] `server.port`:** When observed from the client side, and when communicating through an intermediary, `server.port` SHOULD represent the server port behind any intermediaries, for example proxies, if it's available. +**[8] `server.port`:** When observed from the client side, and when communicating through an intermediary, `server.port` SHOULD represent the server port behind any intermediaries, for example proxies, if it's available. -**[8] `gen_ai.response.model`:** If available. The name of the GenAI model that provided the response. If the model is supplied by a vendor, then the value must be the exact name of the model actually used. If the model is a fine-tuned custom model, the value should have a more specific name than the base model that's been fine-tuned. +**[9] `gen_ai.response.model`:** If available. The name of the GenAI model that provided the response. If the model is supplied by a vendor, then the value must be the exact name of the model actually used. If the model is a fine-tuned custom model, the value should have a more specific name than the base model that's been fine-tuned. -**[9] `server.address`:** When observed from the client side, and when communicating through an intermediary, `server.address` SHOULD represent the server address behind any intermediaries, for example proxies, if it's available. +**[10] `server.address`:** When observed from the client side, and when communicating through an intermediary, `server.address` SHOULD represent the server address behind any intermediaries, for example proxies, if it's available. -**[10] `gcp.gen_ai.operation.config`:** The data structure is dependent on the value of "gen_ai.operation.name" and should correspond with the "*Config" data structure in the Google Gen AI SDK. The Google Gen AI SDK provides these "*Config" data structures in multiple languages, generated from a common source of truth. See "google.genai.types.*" in and `com.google.genai.types.*` in for examples. +**[11] `gcp.gen_ai.operation.config`:** The data structure is dependent on the value of "gen_ai.operation.name" and should correspond with the "*Config" data structure in the Google Gen AI SDK. The Google Gen AI SDK provides these "*Config" data structures in multiple languages, generated from a common source of truth. See "google.genai.types.*" in and `com.google.genai.types.*` in for examples. +The JSON dictionary SHOULD include only an allowlisted subset of the request configuration. The contents also SHOULD NOT overlap with configuration that has already been captured elsewhere through standard Semantic Conventions. Because the data structure is encoded in JSON format, the key names should be specified using "camelCase". More generally, the names should align with the expectations of proto3 JSON encoding ; for example, fields that represent a timestamp in the local language should get mapped to the proto3 JSON encoding of "google.protobuf.Timestamp" (i.e. RFC 3339 date format) per the specification given in . -Instrumentations should not populate this attribute by default. Rather, instrumentations should provide an opt-in mechanism through which the config information can be dumped into this field as a tool for debugging and as an escape hatch for the subset of configuration that is not yet representable using standardized conventions. +Instrumentations SHOULD NOT populate this attribute by default. Rather, instrumentations SHOULD provide an opt-in mechanism through which the config information can be dumped into this field as a tool for debugging and as an escape hatch for the subset of configuration that is not yet representable using standardized conventions. --- @@ -97,6 +112,7 @@ Instrumentations should not populate this attribute by default. Rather, instrume | `embeddings` | Embeddings operation such as [OpenAI Create embeddings API](https://platform.openai.com/docs/api-reference/embeddings/create) | ![Development](https://img.shields.io/badge/-development-blue) | | `execute_tool` | Execute a tool | ![Development](https://img.shields.io/badge/-development-blue) | | `generate_content` | Multimodal content generation operation such as [Gemini Generate Content](https://ai.google.dev/api/generate-content) | ![Development](https://img.shields.io/badge/-development-blue) | +| `invoke_agent` | Invoke GenAI agent | ![Development](https://img.shields.io/badge/-development-blue) | | `text_completion` | Text completions operation such as [OpenAI Completions API (Legacy)](https://platform.openai.com/docs/api-reference/completions) | ![Development](https://img.shields.io/badge/-development-blue) | --- diff --git a/model/gcp/registry.yaml b/model/gcp/registry.yaml index 767c206503..608c4dfac6 100644 --- a/model/gcp/registry.yaml +++ b/model/gcp/registry.yaml @@ -206,12 +206,7 @@ groups: - id: gcp.gen_ai.operation.config stability: development type: string - brief: > - Operation-specific request configuration options for Google generative AI operations. - - The string value should be a valid JSON dictionary. The JSON dictionary should include - only an allowlisted subset of the request configuration that does not overlap with - configuration that has already been captured elsewhere through standard Semantic Conventions. + brief: Operation-specific request configuration options for Google generative AI operations recorded as a JSON string. examples: - '{"audioTimestamp":true}' - '{"safetySettings":[{"threshold":"OFF"}]}' @@ -223,6 +218,10 @@ groups: See "google.genai.types.*" in and `com.google.genai.types.*` in for examples. + The JSON dictionary SHOULD include only an allowlisted subset of the request configuration. The + contents also SHOULD NOT overlap with configuration that has already been captured elsewhere through + standard Semantic Conventions. + Because the data structure is encoded in JSON format, the key names should be specified using "camelCase". More generally, the names should align with the expectations of proto3 JSON encoding ; for example, fields @@ -230,7 +229,7 @@ groups: encoding of "google.protobuf.Timestamp" (i.e. RFC 3339 date format) per the specification given in . - Instrumentations should not populate this attribute by default. Rather, instrumentations - should provide an opt-in mechanism through which the config information can be dumped + Instrumentations SHOULD NOT populate this attribute by default. Rather, instrumentations + SHOULD provide an opt-in mechanism through which the config information can be dumped into this field as a tool for debugging and as an escape hatch for the subset of configuration that is not yet representable using standardized conventions.