spans.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.cache_read.input_tokens
        requirement_level: recommended
      - ref: gen_ai.usage.cache_creation.input_tokens
        requirement_level: recommended
      - ref: gen_ai.usage.output_tokens
        requirement_level: recommended
      - ref: gen_ai.conversation.id
        requirement_level:
          conditionally_required: when available
        note: |
          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.

      - ref: gen_ai.system_instructions
        requirement_level: opt_in
      - ref: gen_ai.input.messages
        requirement_level: opt_in
      - ref: gen_ai.output.messages
        requirement_level: opt_in
      - ref: gen_ai.tool.definitions
        requirement_level: opt_in

  - 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/blob/v1.55.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.provider.name
        # TODO: Not adding to common attributes because of https://github.com/open-telemetry/weaver/issues/479
        requirement_level: required
        sampling_relevant: true
      - ref: gen_ai.operation.name
        sampling_relevant: true
      - ref: server.address
        sampling_relevant: true
      - ref: server.port
        sampling_relevant: true
      - ref: gen_ai.request.model
        sampling_relevant: true
      - 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.
      - ref: server.address
        sampling_relevant: true
      - ref: server.port
        sampling_relevant: true
      - ref: gen_ai.request.model
        sampling_relevant: true
      - ref: gen_ai.operation.name
        sampling_relevant: true

  - id: span.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.provider.name` 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.usage.input_tokens
        note: >
          The total input token count is returned by `usage.input_tokens` or a similar property in the model response.
      - ref: gen_ai.usage.cache_read.input_tokens
        note: >
          Corresponds to `usage.input_tokens_details.cached_tokens` or a similar property in the model response.
      - ref: openai.request.service_tier
        requirement_level:
          conditionally_required: if the request includes a service_tier and the value is not 'auto'
      - ref: openai.response.service_tier
        requirement_level:
          conditionally_required: if the response was received and includes a service_tier
      - ref: openai.response.system_fingerprint
        requirement_level: recommended
      - ref: openai.api.type
        requirement_level: recommended

  - id: span.azure.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/rest/api/aifoundry/modelinference/)
      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 `"azure.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: azure.resource_provider.namespace
        note: >
          When `azure.resource_provider.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.provider.name
        requirement_level: required
        sampling_relevant: true
      - ref: gen_ai.operation.name
        sampling_relevant: true
      - ref: server.address
        sampling_relevant: true
      - ref: server.port
        sampling_relevant: true
      - ref: gen_ai.request.model
        sampling_relevant: true
      - ref: gen_ai.request.encoding_formats
        requirement_level: recommended
      - ref: gen_ai.usage.input_tokens
        requirement_level: recommended
      - ref: gen_ai.embeddings.dimension.count
        requirement_level: recommended
      - ref: gen_ai.response.model
        requirement_level: recommended

  - id: span.gen_ai.retrieval.client
    type: span
    span_kind: client
    stability: development
    brief: >
      Describes GenAI retrieval span - a request to a Generative AI service or framework
      that retrieves relevant information or context from a vector database or search system.

      The `gen_ai.operation.name` SHOULD be `retrieval`.

      **Span name** SHOULD be `{gen_ai.operation.name} {gen_ai.data_source.id}`. Semantic conventions
      for individual GenAI providers and retrievers MAY specify different span name format.
    extends: attributes.gen_ai.common.client
    attributes:
      - ref: gen_ai.operation.name
        requirement_level: required
      - ref: gen_ai.retrieval.query.text
        requirement_level: opt_in
      - ref: gen_ai.request.top_k
        requirement_level: recommended
      - ref: gen_ai.retrieval.documents
        requirement_level: opt_in
      - ref: gen_ai.provider.name
        requirement_level:
          conditionally_required: when applicable
      - ref: gen_ai.data_source.id
        requirement_level:
          conditionally_required: when applicable
      - ref: error.type
        requirement_level:
          conditionally_required: "if the operation ended in an error"

  - 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.provider.name
        requirement_level: required
        sampling_relevant: true
      - ref: gen_ai.operation.name
        sampling_relevant: true
      - ref: server.address
        sampling_relevant: true
      - ref: server.port
        sampling_relevant: true
      - ref: gen_ai.request.model
        sampling_relevant: true
      - 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.
      - ref: gen_ai.agent.version
        requirement_level:
          conditionally_required: If provided by the application.
      - ref: gen_ai.system_instructions
        requirement_level: opt_in
        note: ""  # note is not needed here


  - id: span.gen_ai.invoke_agent.client
    type: span
    stability: development
    span_kind: client
    brief: >
      Describes GenAI agent invocation.
    note: |
      The `gen_ai.operation.name` SHOULD be `invoke_agent`.

      **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.

      **Span kind** SHOULD be `CLIENT` and MAY be set to `INTERNAL` on spans representing
      invocation of agents running in the same process.
      It's RECOMMENDED to use `CLIENT` kind when the agent being instrumented usually runs
      in a different process than its caller or when the agent invocation happens over
      instrumented protocol such as HTTP.

      Examples of span kinds for different agent scenarios:

      - `CLIENT`: Remote agent services (e.g., OpenAI Assistants API, AWS Bedrock Agents)
      - `INTERNAL`: In-process agents (e.g., LangChain agents, CrewAI agents)
    extends: attributes.gen_ai.inference.client
    attributes:
      - ref: gen_ai.provider.name
        requirement_level: required
        sampling_relevant: true
      - ref: gen_ai.operation.name
        sampling_relevant: true
      - ref: gen_ai.request.model
        sampling_relevant: true
      - 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
      - ref: gen_ai.agent.version
        requirement_level:
          conditionally_required: when available
      - ref: gen_ai.data_source.id
        requirement_level:
          conditionally_required: if applicable.
      - ref: server.address
        requirement_level:
          recommended: when span kind is `CLIENT`.
        sampling_relevant: true
      - ref: server.port
        sampling_relevant: true
      - ref: gen_ai.system_instructions
        requirement_level: opt_in
      - ref: gen_ai.input.messages
        requirement_level: opt_in
      - ref: gen_ai.output.messages
        requirement_level: opt_in


  - 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 can instrument tool execution calls SHOULD do so,
      unless another instrumentation can reliably cover all supported tool types.
      MCP tool executions may also be traced by the
      [corresponding MCP instrumentation](/docs/gen-ai/mcp.md#client).

      Tools are often executed directly by application code. Application developers
      are encouraged to follow this semantic convention for tools invoked by their
      own code and to manually instrument any tool calls that automatic
      instrumentations do not cover.
    attributes:
      - ref: gen_ai.operation.name
        requirement_level: required
        sampling_relevant: true
      - 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: gen_ai.tool.type
        requirement_level:
          recommended: if available
      - ref: gen_ai.tool.call.arguments
        requirement_level: opt_in
      - ref: gen_ai.tool.call.result
        requirement_level: opt_in
      - 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: span.aws.bedrock.client
    extends: span.gen_ai.inference.client
    stability: development
    span_kind: client
    type: span
    brief: >
      Describes an AWS Bedrock operation span.
    attributes:
      - ref: aws.bedrock.guardrail.id
        requirement_level: required
      - ref: aws.bedrock.knowledge_base.id
        requirement_level: recommended

  - id: span.anthropic.inference.client
    extends: attributes.gen_ai.inference.client
    stability: development
    span_kind: client
    type: span
    brief: >
      Semantic Conventions for [Anthropic](https://www.anthropic.com/) 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 `"anthropic"` and SHOULD be provided **at span creation time**.

      **Span name** SHOULD be `{gen_ai.operation.name} {gen_ai.request.model}`.
    attributes:
      - ref: gen_ai.usage.input_tokens
        note: >
          Anthropic `input_tokens` excludes cached tokens. Compute:
          `gen_ai.usage.input_tokens = input_tokens + cache_read_input_tokens + cache_creation_input_tokens`
      - ref: gen_ai.usage.cache_read.input_tokens
        note: >
          Anthropic reports this separately from `input_tokens`.
          This value MUST be added to the Anthropic `input_tokens` to compute `gen_ai.usage.input_tokens`.
      - ref: gen_ai.usage.cache_creation.input_tokens
        note: >
          Anthropic reports this separately from `input_tokens`.
          This value MUST be added to the Anthropic `input_tokens` to compute `gen_ai.usage.input_tokens`.

  - id: span.gen_ai.invoke_workflow.internal
    type: span
    span_kind: internal
    stability: development
    brief: >
      Represents an operation that executes a coordinated process composed of multiple agents
      or other operations involving generative AI.
    note: |
      The `gen_ai.operation.name` SHOULD be `invoke_workflow`.
      **Span name** SHOULD be `invoke_workflow {gen_ai.workflow.name}`.

      This span SHOULD be reported by the instrumentations when they can
      reliably determine that invocation is a workflow (i.e. groups several agent
      invocations) and SHOULD NOT be reported by instrumentations that
      can't distinguish it `invoke_workflow` from `invoke_agent`.
      eg: Some frameworks like ADK have workflow agents that orchestrate other agents
      and report `invoke_agent` spans, so `invoke_workflow` SHOULD NOT be reported by such instrumentations.
      Conversely, frameworks like CrewAI have a distinct concept of crew (similar to workflow)
      that is separate from individual agents, so they SHOULD report `invoke_workflow` spans.
    attributes:
      - ref: gen_ai.operation.name
        requirement_level: required
        sampling_relevant: true
      - 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.
      - ref: gen_ai.workflow.name
        requirement_level:
          conditionally_required: when available
      - ref: gen_ai.input.messages
        requirement_level: opt_in
      - ref: gen_ai.output.messages
        requirement_level: opt_in