Define dynamic request attributes for Google GenAI LLM inference spans

.chloggen/gcp_genai_dynamic_req_attr.yaml

@@ -0,0 +1,5 @@
+change_type: enhancement
+component: [gcp, gen-ai]
+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.

areas.yaml

@@ -1,4 +1,4 @@
-areas:
+areareas:
   - name: "Semantic Conventions: System"
     owner:
       - name: "semconv-system-approvers"
@@ -43,6 +43,7 @@ areas:
       - area:gen-ai
       - area:openai
       - area:mcp
+      - area:gcp
     status:
       - accepting_contributions
       - active

docs/gen-ai/README.md

@@ -39,6 +39,7 @@ Technology specific semantic conventions are defined for the following GenAI sys
 * [Anthropic](./anthropic.md): Semantic Conventions for Anthropic.
 * [Azure AI Inference](./azure-ai-inference.md): Semantic Conventions for Azure AI Inference.
 * [AWS Bedrock](./aws-bedrock.md): Semantic Conventions for AWS Bedrock.
+* [Google Generative AI](./gcp.md): Semantic Conventions for Gemini and Vertex AI.
 * [OpenAI](./openai.md): Semantic Conventions for OpenAI.
 
 See also:

docs/gen-ai/gcp.md

@@ -0,0 +1,142 @@
+<!--- Hugo front matter used to generate the website version of this page:
+linkTitle: Google Generative AI Semantic Conventions
+--->
+
+# 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
+
+<!-- semconv span.gen_ai.gcp.client -->
+<!-- NOTE: THIS TEXT IS AUTOGENERATED. DO NOT EDIT BY HAND. -->
+<!-- see templates/registry/markdown/snippet.md.j2 -->
+<!-- prettier-ignore-start -->
+<!-- markdownlint-capture -->
+<!-- markdownlint-disable -->
+
+**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.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. [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. [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) |
+| [`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.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.
+
+**[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.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.
+
+**[6] `gen_ai.output.type`:** when applicable and if the request includes an output format.
+
+**[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.
+
+**[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.
+
+**[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.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 <https://github.com/googleapis/python-genai> and  `com.google.genai.types.*` in <https://github.com/googleapis/java-genai> 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 <https://protobuf.dev/programming-guides/proto3/#json>; 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 <https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp>. 
+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.
+
+---
+
+`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) |
+| `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) |
+
+---
+
+`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) |
+
+<!-- markdownlint-restore -->
+<!-- prettier-ignore-end -->
+<!-- END AUTOGENERATED TEXT -->
+<!-- endsemconv -->
+
+## 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

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.operation.config
+
+  - 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.

model/gcp/registry.yaml

@@ -341,3 +341,40 @@ groups:
           The region of a **regional** Instance Group Manager (e.g., `us-central1`).
           Set this **only** when the IGM is regional.
         examples: ['us-central1', 'europe-west1']
+
+  - 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.operation.config
+        stability: development
+        type: string
+        brief: Operation-specific request configuration options for Google generative AI operations recorded as a JSON string.
+        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 <https://github.com/googleapis/python-genai> and
+          `com.google.genai.types.*` in <https://github.com/googleapis/java-genai> 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.
+
+          The names SHOULD align with the expectations of proto3 JSON encoding
+          <https://protobuf.dev/programming-guides/proto3/#json>; 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 <https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp>.
+
+          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.

model/gen-ai/spans.yaml

@@ -226,6 +226,22 @@ groups:
         requirement_level:
           conditionally_required: If not default (443).
 
+  - id: span.gen_ai.gcp.client
+    type: span
+    extends: attributes.gen_ai.inference.client
+    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.operation.config
+       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.embeddings.client
     type: span
     span_kind: client