278 lines
12 KiB
YAML
278 lines
12 KiB
YAML
groups:
|
|
- id: attributes.gen_ai.common.client
|
|
type: attribute_group
|
|
stability: development
|
|
brief: >
|
|
Common attributes for all GenAI spans.
|
|
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: 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: attributes.gen_ai.inference.client
|
|
type: attribute_group
|
|
stability: development
|
|
brief: >
|
|
Describes GenAI inference attributes.
|
|
extends: attributes.gen_ai.common.client
|
|
attributes:
|
|
- 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.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.inference.client
|
|
type: span
|
|
stability: development
|
|
span_kind: client
|
|
brief: >
|
|
This span represents a client call to Generative AI model or service that generates
|
|
a response or requests a tool call based on the input prompt.
|
|
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: attributes.gen_ai.inference.client
|
|
attributes:
|
|
- ref: gen_ai.system
|
|
# TODO: Not adding to 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
|
|
|
|
- id: attributes.gen_ai.inference.openai_based
|
|
extends: attributes.gen_ai.inference.client
|
|
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.inference.client
|
|
extends: attributes.gen_ai.inference.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.inference.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.embeddings.client
|
|
type: span
|
|
span_kind: client
|
|
stability: development
|
|
brief: >
|
|
Describes GenAI embeddings span - a request to a Generative AI model or service
|
|
that generates an embeddings based on the input.
|
|
|
|
The `gen_ai.operation.name` SHOULD be `embeddings`.
|
|
|
|
**Span name** SHOULD be `{gen_ai.operation.name} {gen_ai.request.model}`.
|
|
extends: attributes.gen_ai.common.client
|
|
attributes:
|
|
- ref: gen_ai.request.encoding_formats
|
|
requirement_level: recommended
|
|
- ref: gen_ai.usage.input_tokens
|
|
requirement_level: recommended
|
|
|
|
- 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: attributes.gen_ai.common.client
|
|
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.invoke_agent.client
|
|
type: span
|
|
stability: development
|
|
span_kind: client
|
|
brief: >
|
|
Describes GenAI agent invocation and is usually applicable when working
|
|
with remote agent services.
|
|
note: |
|
|
The `gen_ai.operation.name` SHOULD be `invoke_agent`.
|
|
The **span name** SHOULD be `invoke_agent {gen_ai.agent.name}` if `gen_ai.agent.name` is readily available.
|
|
When `gen_ai.agent.name` is not available, it SHOULD be `invoke_agent`.
|
|
Semantic conventions for individual GenAI systems and frameworks MAY specify different span name format.
|
|
extends: attributes.gen_ai.inference.client
|
|
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: when available
|
|
- ref: gen_ai.agent.description
|
|
requirement_level:
|
|
conditionally_required: when available
|
|
|
|
- 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.
|