Watsonx Semantic Conventions [INSTA-21674]

.chloggen/watsonx-sem-convention.yaml

@@ -0,0 +1,22 @@
+# Use this changelog template to create an entry for release notes.
+#
+# If your change doesn't affect end users you should instead start
+# your pull request title with [chore] or use the "Skip Changelog" label.
+
+# One of 'breaking', 'deprecation', 'new_component', 'enhancement', 'bug_fix'
+change_type: enhancement
+
+# The name of the area of concern in the attributes-registry, (e.g. http, cloud, db)
+component: gen-ai
+
+# A brief description of the change. Surround your text with quotes ("") if it needs to start with a backtick (`).
+note: "Add IBM WatsonX AI semantic conventions"
+
+# Mandatory: One or more tracking issues related to the change. You can use the PR number here if no issue exists.
+# The values here must be integers.
+issues: [1650]
+
+# (Optional) One or more lines of additional information to render under the primary note.
+# These lines will be padded with 2 spaces and then inserted directly into the document.
+# Use pipe (|) for multiline entries.
+subtext:

docs/gen-ai/README.md

@@ -39,5 +39,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.
 * [AWS Bedrock](./aws-bedrock.md): Semantic Conventions for AWS Bedrock.
+* [IBM WatsonX AI](./ibm-watsonx-ai.md): Semantic Conventions for IBM WatsonX AI.
 
 [DocumentStatus]: https://opentelemetry.io/docs/specs/otel/document-status

docs/registry/attributes/README.md

@@ -72,6 +72,7 @@ Currently, the following namespaces exist:
 - [Heroku](heroku.md)
 - [Host](host.md)
 - [HTTP](http.md)
+- [Ibm](ibm.md)
 - [iOS](ios.md)
 - [JVM](jvm.md)
 - [K8s](k8s.md)

docs/registry/attributes/ibm.md

@@ -0,0 +1,20 @@
+<!-- NOTE: THIS FILE IS AUTOGENERATED. DO NOT EDIT BY HAND. -->
+<!-- see templates/registry/markdown/attribute_namespace.md.j2 -->
+
+# Ibm
+
+## WatsonX AI Attributes
+
+This group defines attributes for IBM WatsonX AI.
+
+| Attribute | Type | Description | Examples | Stability |
+|---|---|---|---|---|
+| <a id="ibm-watsonx-ai-decoding-method" href="#ibm-watsonx-ai-decoding-method">`ibm.watsonx.ai.decoding_method`</a> | string | The decoding method used by WatsonX for generating responses. | `greedy`; `sample` | ![Development](https://img.shields.io/badge/-development-blue) |
+| <a id="ibm-watsonx-ai-max-new-tokens" href="#ibm-watsonx-ai-max-new-tokens">`ibm.watsonx.ai.max_new_tokens`</a> | int | The maximum number of new tokens to generate in the response. | `100` | ![Development](https://img.shields.io/badge/-development-blue) |
+| <a id="ibm-watsonx-ai-min-new-tokens" href="#ibm-watsonx-ai-min-new-tokens">`ibm.watsonx.ai.min_new_tokens`</a> | int | The minimum number of new tokens to generate in the response. | `10` | ![Development](https://img.shields.io/badge/-development-blue) |
+| <a id="ibm-watsonx-ai-random-seed" href="#ibm-watsonx-ai-random-seed">`ibm.watsonx.ai.random_seed`</a> | int | The random seed used by WatsonX for deterministic generation. | `42` | ![Development](https://img.shields.io/badge/-development-blue) |
+| <a id="ibm-watsonx-ai-repetition-penalty" href="#ibm-watsonx-ai-repetition-penalty">`ibm.watsonx.ai.repetition_penalty`</a> | double | The penalty applied to repeated tokens in the generated response. | `1.2` | ![Development](https://img.shields.io/badge/-development-blue) |
+| <a id="ibm-watsonx-ai-request-project-id" href="#ibm-watsonx-ai-request-project-id">`ibm.watsonx.ai.request.project_id`</a> | string | The project ID in IBM WatsonX AI. | `12345678-abcd-1234-efgh-1234567890ab` | ![Development](https://img.shields.io/badge/-development-blue) |
+| <a id="ibm-watsonx-ai-request-space-id" href="#ibm-watsonx-ai-request-space-id">`ibm.watsonx.ai.request.space_id`</a> | string | The space ID in IBM WatsonX AI. | `abcdef12-3456-7890-abcd-ef1234567890` | ![Development](https://img.shields.io/badge/-development-blue) |
+| <a id="ibm-watsonx-ai-request-version" href="#ibm-watsonx-ai-request-version">`ibm.watsonx.ai.request.version`</a> | string | The version of the model being used. | `1.0`; `2.3.1` | ![Development](https://img.shields.io/badge/-development-blue) |
+| <a id="ibm-watsonx-ai-response-trace-id" href="#ibm-watsonx-ai-response-trace-id">`ibm.watsonx.ai.response.trace_id`</a> | string | The trace ID returned by IBM WatsonX AI. | `wxt-12345678-abcd-1234-efgh-1234567890ab` | ![Development](https://img.shields.io/badge/-development-blue) |

model/gen-ai/metrics.yaml

@@ -94,6 +94,69 @@ groups:
     unit: "s"
     stability: development
     extends: metric_attributes.gen_ai
+  - id: metric_attributes.ibm.watsonx.ai
+    type: attribute_group
+    brief: 'This group describes IBM WatsonX.AI metrics attributes'
+    attributes:
+      - ref: gen_ai.operation.name
+        requirement_level: required
+      - ref: gen_ai.request.model
+        requirement_level: recommended
+      - ref: gen_ai.token.type
+        requirement_level: required
+      - ref: error.type
+        requirement_level: required
+  - id: metric.ibm.watsonx.ai.completions.tokens
+    type: metric
+    metric_name: ibm.watsonx.ai.completions.tokens
+    annotations:
+      code_generation:
+        metric_value_type: int
+    brief: 'Number of tokens processed by IBM WatsonX.AI completions.'
+    instrument: counter
+    unit: "{token}"
+    stability: development
+    attributes:
+      - ref: gen_ai.operation.name
+        requirement_level: required
+      - ref: gen_ai.token.type
+        requirement_level: required
+      - ref: gen_ai.request.model
+        requirement_level: recommended
+  - id: metric.ibm.watsonx.ai.completions.responses
+    type: metric
+    metric_name: ibm.watsonx.ai.completions.responses
+    annotations:
+      code_generation:
+        metric_value_type: int
+    brief: 'Number of responses generated by IBM WatsonX.AI completions.'
+    instrument: counter
+    unit: "{response}"
+    stability: development
+    attributes:
+      - ref: gen_ai.operation.name
+        requirement_level: required
+      - ref: gen_ai.request.model
+        requirement_level: recommended
+      - ref: gen_ai.response.finish_reasons
+        requirement_level: recommended
+  - id: metric.ibm.watsonx.ai.completions.exceptions
+    type: metric
+    metric_name: ibm.watsonx.ai.completions.exceptions
+    annotations:
+      code_generation:
+        metric_value_type: int
+    brief: 'Number of exceptions encountered during IBM WatsonX.AI completions.'
+    instrument: counter
+    unit: "{exception}"
+    stability: development
+    attributes:
+      - ref: gen_ai.operation.name
+        requirement_level: required
+      - ref: gen_ai.request.model
+        requirement_level: recommended
+      - ref: error.type
+        requirement_level: required
   - id: metric.gen_ai.server.time_to_first_token
     type: metric
     metric_name: gen_ai.server.time_to_first_token

model/gen-ai/spans.yaml

@@ -335,3 +335,40 @@ groups:
         requirement_level: required
       - ref: aws.bedrock.knowledge_base.id
         requirement_level: recommended
+
+  - id: span.ibm.watsonx.ai.inference.client
+    extends: attributes.gen_ai.inference.client
+    stability: development
+    span_kind: client
+    type: span
+    brief: >
+      Semantic Conventions for [IBM WatsonX.AI](https://www.ibm.com/products/watsonx-ai) client spans extend
+      and override the semantic conventions for [Gen AI Spans](gen-ai-spans.md).
+    note: |
+      `gen_ai.provider.name` MUST be set to `"ibm.watsonx.ai"` and SHOULD be provided **at span creation time**.
+
+      **Span name** SHOULD be `{gen_ai.operation.name} {gen_ai.request.model}`.
+    attributes:
+      - ref: gen_ai.request.model
+        requirement_level: required
+      - ref: ibm.watsonx.ai.request.project_id
+        requirement_level:
+          conditionally_required: if the request includes a project_id
+      - ref: ibm.watsonx.ai.request.space_id
+        requirement_level:
+          conditionally_required: if the request includes a space_id
+      - ref: ibm.watsonx.ai.response.trace_id
+        requirement_level:
+          conditionally_required: if the response was received and includes a trace_id
+      - ref: ibm.watsonx.ai.request.version
+        requirement_level: recommended
+      - ref: ibm.watsonx.ai.decoding_method
+        requirement_level: recommended
+      - ref: ibm.watsonx.ai.random_seed
+        requirement_level: recommended
+      - ref: ibm.watsonx.ai.max_new_tokens
+        requirement_level: recommended
+      - ref: ibm.watsonx.ai.min_new_tokens
+        requirement_level: recommended
+      - ref: ibm.watsonx.ai.repetition_penalty
+        requirement_level: recommended

model/ibm-watsonx-ai/registry.yaml

@@ -0,0 +1,53 @@
+groups:
+  - id: registry.ibm.watsonx.ai
+    type: attribute_group
+    display_name: WatsonX AI Attributes
+    brief: >
+      This group defines attributes for IBM WatsonX AI.
+    attributes:
+      - id: ibm.watsonx.ai.request.project_id
+        stability: development
+        type: string
+        brief: The project ID in IBM WatsonX AI.
+        examples: ['12345678-abcd-1234-efgh-1234567890ab']
+      - id: ibm.watsonx.ai.request.space_id
+        stability: development
+        type: string
+        brief: The space ID in IBM WatsonX AI.
+        examples: ['abcdef12-3456-7890-abcd-ef1234567890']
+      - id: ibm.watsonx.ai.request.version
+        stability: development
+        type: string
+        brief: The version of the model being used.
+        examples: ['1.0', '2.3.1']
+      - id: ibm.watsonx.ai.response.trace_id
+        stability: development
+        type: string
+        brief: The trace ID returned by IBM WatsonX AI.
+        examples: ['wxt-12345678-abcd-1234-efgh-1234567890ab']
+      - id: ibm.watsonx.ai.decoding_method
+        stability: development
+        type: string
+        brief: The decoding method used by WatsonX for generating responses.
+        examples: ['greedy', 'sample']
+      - id: ibm.watsonx.ai.random_seed
+        stability: development
+        type: int
+        brief: The random seed used by WatsonX for deterministic generation.
+        examples: [42]
+      - id: ibm.watsonx.ai.max_new_tokens
+        stability: development
+        type: int
+        brief: The maximum number of new tokens to generate in the response.
+        examples: [100]
+      - id: ibm.watsonx.ai.min_new_tokens
+        stability: development
+        type: int
+        brief: The minimum number of new tokens to generate in the response.
+        examples: [10]
+      - id: ibm.watsonx.ai.repetition_penalty
+        stability: development
+        type: double
+        brief: The penalty applied to repeated tokens in the generated response.
+        examples: [1.2]
+