[google-genai/spans] Define gcp.gen_ai.operation.config. attribute

.chloggen/gcp_genai_request_star_attributes.yaml

@@ -0,0 +1,5 @@
+change_type: enhancement
+component: gen-ai
+note: Define attribute for Google generative AI operation request configuration.
+issues: [2053]
+subtext: Defines `gcp.gen_ai.operation.config` as a templated string for recording a subset of operation configuration options.

.chloggen/init-gcp-genai.yaml

@@ -0,0 +1,4 @@
+change_type: enhancement
+component: gen-ai
+note: Define common span attributes for Google generative AI
+issues: [2053]

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 GenAI](./google-genai.md): Semantic Conventions for Gemini and Vertex AI.
 * [OpenAI](./openai.md): Semantic Conventions for OpenAI.
 
 See also:

docs/registry/attributes/gcp.md

@@ -8,6 +8,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
 
@@ -177,3 +178,46 @@ This document defines attributes for Google Compute Engine (GCE).
 | <a id="gcp-gce-instance-group-manager-name" href="#gcp-gce-instance-group-manager-name">`gcp.gce.instance_group_manager.name`</a> | ![Development](https://img.shields.io/badge/-development-blue) | string | The name of the Instance Group Manager (IGM) that manages this VM, if any. | `web-igm`; `my-managed-group` |
 | <a id="gcp-gce-instance-group-manager-region" href="#gcp-gce-instance-group-manager-region">`gcp.gce.instance_group_manager.region`</a> | ![Development](https://img.shields.io/badge/-development-blue) | string | The region of a **regional** Instance Group Manager (e.g., `us-central1`). Set this **only** when the IGM is regional. | `us-central1`; `europe-west1` |
 | <a id="gcp-gce-instance-group-manager-zone" href="#gcp-gce-instance-group-manager-zone">`gcp.gce.instance_group_manager.zone`</a> | ![Development](https://img.shields.io/badge/-development-blue) | string | The zone of a **zonal** Instance Group Manager (e.g., `us-central1-a`). Set this **only** when the IGM is zonal. | `us-central1-a`; `europe-west1-b` |
+
+## Generative AI Attributes
+
+This documents defines attributes for Google generative AI systems.
+
+**Attributes:**
+
+| Key | Stability | Value Type | Description | Example Values |
+| --- | --- | --- | --- | --- |
+| <a id="gcp-gen-ai-operation-config" href="#gcp-gen-ai-operation-config">`gcp.gen_ai.operation.config.<key>`</a> | ![Development](https://img.shields.io/badge/-development-blue) | template[any] | Operation-specific request configuration options for Google generative AI operations, the `<key>` being the configuration name, the value being the corresponding configuration value. [6] | A config `audioTimestamp` with value `true` SHOULD be recorded as the<br>`gcp.gen_ai.operation.config.audioTimestamp` attribute with value `true`.; A config `safetySettings` with value `[{"threshold":"OFF"}]` SHOULD be recorded as the<br>`gcp.gen_ai.operation.config.safetySettings` attribute with value:`[{"threshold":"OFF"}]`; A config `thinkingConfig` with value `{"includeThoughts":true}` SHOULD be recorded as the<br>`gcp.gen_ai.operation.config.thinkingConfig` attribute with value:`{"includeThoughts":"true"}` |
+
+**[6] `gcp.gen_ai.operation.config.<key>`:** The available `<key>` values are dependent on `gen_ai.operation.name` and SHOULD
+correspond to fields on the operation-specific `*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.
+
+Instrumentations SHOULD record only an allowlisted subset of request configuration.
+Each allowlisted field SHOULD be recorded as a separate
+`gcp.gen_ai.operation.config.<key>` attribute where `<key>` is the configuration
+name and the attribute value is the corresponding config value.
+
+Scalar values SHOULD be recorded using the corresponding scalar type.
+Structured values such as objects and arrays SHOULD be recorded in structured
+form when supported. When recorded on spans, structured values MAY be recorded as
+JSON strings if structured format is not supported and SHOULD be recorded in
+structured form otherwise. The recorded fields also SHOULD NOT overlap with
+configuration that has already been captured elsewhere through standard Semantic
+Conventions.
+
+The `<key>` names and any JSON encoding 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 be 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/gcp/registry.yaml

@@ -341,3 +341,58 @@ 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: template[any]
+        brief: Operation-specific request configuration options for Google generative AI operations, the `<key>` being the configuration name, the value being the corresponding configuration value.
+        examples:
+          - |
+            A config `audioTimestamp` with value `true` SHOULD be recorded as the
+            `gcp.gen_ai.operation.config.audioTimestamp` attribute with value `true`.
+          - |
+            A config `safetySettings` with value `[{"threshold":"OFF"}]` SHOULD be recorded as the
+            `gcp.gen_ai.operation.config.safetySettings` attribute with value:`[{"threshold":"OFF"}]`
+          - |
+            A config `thinkingConfig` with value `{"includeThoughts":true}` SHOULD be recorded as the
+            `gcp.gen_ai.operation.config.thinkingConfig` attribute with value:`{"includeThoughts":"true"}`
+        note: |
+          The available `<key>` values are dependent on `gen_ai.operation.name` and SHOULD
+          correspond to fields on the operation-specific `*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.
+
+          Instrumentations SHOULD record only an allowlisted subset of request configuration.
+          Each allowlisted field SHOULD be recorded as a separate
+          `gcp.gen_ai.operation.config.<key>` attribute where `<key>` is the configuration
+          name and the attribute value is the corresponding config value.
+
+          Scalar values SHOULD be recorded using the corresponding scalar type.
+          Structured values such as objects and arrays SHOULD be recorded in structured
+          form when supported. When recorded on spans, structured values MAY be recorded as
+          JSON strings if structured format is not supported and SHOULD be recorded in
+          structured form otherwise. The recorded fields also SHOULD NOT overlap with
+          configuration that has already been captured elsewhere through standard Semantic
+          Conventions.
+
+          The `<key>` names and any JSON encoding 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 be 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,20 @@ 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.provider.name` MUST be set to `"gcp.gen_ai"`, `"gcp.vertex_ai"`, or `"gcp.gemini"` and SHOULD be provided **at span creation time**.
+
+      **Span name** SHOULD be `{gen_ai.operation.name} {gen_ai.request.model}`.
+    attributes:
+      - ref: gcp.gen_ai.operation.config
+        requirement_level: opt_in
+
   - id: span.gen_ai.embeddings.client
     type: span
     span_kind: client