groups: - id: trace.gen_ai.client.common_request_attributes type: attribute_group stability: development brief: > Describes GenAI operation span. attributes: - ref: gen_ai.request.model requirement_level: conditionally_required: If available. note: > 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. - ref: gen_ai.operation.name requirement_level: required - ref: gen_ai.request.max_tokens requirement_level: recommended - ref: gen_ai.request.choice.count requirement_level: conditionally_required: if available, in the request, and !=1 - ref: gen_ai.request.temperature requirement_level: recommended - ref: gen_ai.request.top_p requirement_level: recommended - ref: gen_ai.request.stop_sequences requirement_level: recommended - ref: gen_ai.request.frequency_penalty requirement_level: recommended - ref: gen_ai.request.presence_penalty requirement_level: recommended - ref: gen_ai.request.seed requirement_level: conditionally_required: if applicable and if the request includes a seed - ref: gen_ai.request.encoding_formats requirement_level: recommended - ref: server.address brief: GenAI server address. requirement_level: recommended - ref: server.port brief: GenAI server port. requirement_level: conditionally_required: If `server.address` is set. - ref: error.type requirement_level: conditionally_required: "if the operation ended in an error" note: | 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. - id: trace.gen_ai.client.common_attributes type: attribute_group stability: development brief: > Describes GenAI operation span. extends: trace.gen_ai.client.common_request_attributes attributes: - ref: gen_ai.output.type requirement_level: conditionally_required: when applicable and if the request includes an output format. - ref: gen_ai.response.id requirement_level: recommended - ref: gen_ai.response.model requirement_level: recommended note: > 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. - ref: gen_ai.response.finish_reasons requirement_level: recommended - ref: gen_ai.usage.input_tokens requirement_level: recommended - ref: gen_ai.usage.output_tokens requirement_level: recommended - id: span.gen_ai.client type: span stability: development span_kind: client brief: > This span represents a client call to Generative AI model or service. note: | **Span name** SHOULD be `{gen_ai.operation.name} {gen_ai.request.model}`. Semantic conventions for individual GenAI systems and frameworks MAY specify different span name format and MUST follow the overall [guidelines for span names](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.37.0/specification/trace/api.md#span). **Span kind** SHOULD be `CLIENT`and MAY be set to `INTERNAL` on spans representing call to models running in the same process. It's RECOMMENDED to use `CLIENT` kind when the GenAI system being instrumented usually runs in a different process than its client or when the GenAI call happens over instrumented protocol such as HTTP. extends: trace.gen_ai.client.common_attributes attributes: - ref: gen_ai.system # TODO: Not adding to trace.gen_ai.client.common_attributes because of https://github.com/open-telemetry/build-tools/issues/192 requirement_level: required - ref: gen_ai.request.top_k requirement_level: recommended events: - gen_ai.content.prompt - gen_ai.content.completion - id: attributes.gen_ai.openai_based extends: trace.gen_ai.client.common_attributes type: attribute_group stability: development brief: > Describes attributes that are common to OpenAI-based Generative AI services. attributes: - ref: gen_ai.output.type note: > This attribute SHOULD be set to the output type requested by the client: - `json` for structured outputs with defined or undefined schema - `image` for image output - `speech` for speech output - `text` for plain text output The 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. - id: span.gen_ai.openai.client extends: attributes.gen_ai.openai_based stability: development span_kind: client type: span brief: > Semantic Conventions for [OpenAI](https://openai.com/) client spans extend and override the semantic conventions for [Gen AI Spans](gen-ai-spans.md). note: | `gen_ai.system` MUST be set to `"openai"` 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: gen_ai.openai.request.service_tier requirement_level: conditionally_required: if the request includes a service_tier and the value is not 'auto' - ref: gen_ai.openai.response.service_tier requirement_level: conditionally_required: if the response was received and includes a service_tier - ref: gen_ai.openai.response.system_fingerprint requirement_level: recommended - ref: gen_ai.usage.input_tokens brief: The number of tokens used in the prompt sent to OpenAI. - ref: gen_ai.usage.output_tokens brief: The number of tokens used in the completions from OpenAI. - id: span.gen_ai.az.ai.inference.client extends: attributes.gen_ai.openai_based stability: development type: span span_kind: client brief: > Semantic Conventions for [Azure AI Inference](https://learn.microsoft.com/azure/ai-studio/reference/reference-model-inference-api) client spans extend and override the semantic conventions for [Gen AI Spans](gen-ai-spans.md). note: | `gen_ai.system` MUST be set to `"az.ai.inference"` and SHOULD be provided **at span creation time**. **Span name** SHOULD be `{gen_ai.operation.name} {gen_ai.request.model}` when the model name is available and `{gen_ai.operation.name}` otherwise. attributes: - ref: az.namespace note: > When `az.namespace` attribute is populated, it MUST be set to `Microsoft.CognitiveServices` for all operations performed by Azure AI Inference clients. examples: ["Microsoft.CognitiveServices"] - ref: gen_ai.usage.input_tokens brief: > The number of prompt tokens as reported in the usage prompt_tokens property of the response. - ref: gen_ai.usage.output_tokens brief: > The number of completion tokens as reported in the usage completion_tokens property of the response. - ref: server.port requirement_level: conditionally_required: If not default (443). - id: span.gen_ai.create_agent.client type: span stability: development span_kind: client brief: > Describes GenAI agent creation and is usually applicable when working with remote agent services. note: | The `gen_ai.operation.name` SHOULD be `create_agent`. **Span name** SHOULD be `create_agent {gen_ai.agent.name}`. Semantic conventions for individual GenAI systems and frameworks MAY specify different span name format. extends: trace.gen_ai.client.common_request_attributes attributes: - ref: gen_ai.system requirement_level: required - ref: gen_ai.agent.id requirement_level: conditionally_required: if applicable. - ref: gen_ai.agent.name requirement_level: conditionally_required: If provided by the application. - ref: gen_ai.agent.description requirement_level: conditionally_required: If provided by the application. - id: span.gen_ai.execute_tool.internal type: span stability: development span_kind: internal brief: Describes tool execution span. note: | `gen_ai.operation.name` SHOULD be `execute_tool`. **Span name** SHOULD be `execute_tool {gen_ai.tool.name}`. GenAI instrumentations that are able to instrument tool execution call SHOULD do so. However, it's common for tools to be executed by the application code. It's recommended for the application developers to follow this semantic convention for tools invoked by the application code. attributes: - ref: gen_ai.tool.name requirement_level: recommended - ref: gen_ai.tool.call.id requirement_level: recommended: if available - ref: gen_ai.tool.description requirement_level: recommended: if available - ref: error.type requirement_level: conditionally_required: "if the operation ended in an error" note: | 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.