Ballerina library

ai.observe

Modules

ai

ai.observe

Module ai.observe

API

createChatSpan
createCreateAgentSpan
createCreateKnowledgeBaseSpan
createEmbeddingSpan
createExecuteToolSpan
createGenerateContentSpan
createInvokeAgentSpan
createKnowledgeBaseIngestSpan
createKnowledgeBaseRetrieveSpan
getCurrentAiSpan

ChatSpanCreateAgentSpanCreateKnowledgeBaseSpanEmbeddingSpanExecuteToolSpanGenerateContentSpanInvokeAgentSpanKnowledgeBaseIngestSpanKnowledgeBaseRetrieveSpan

Declarations

OutputType
ToolType

Definitions

AiSpanLlmSpan

ballerina/ai.observe Ballerina library

1.10.0

Functions

createChatSpan

Isolated Function
function createChatSpan(string llmModel) returns ChatSpan

Creates a span representing a chat model interaction.

Parameters
  • llmModel string - The name of the LLM or chat model used
Return Type
  • ChatSpan - A ChatSpan instance representing the span

createCreateAgentSpan

Isolated Function
function createCreateAgentSpan(string agentName) returns CreateAgentSpan

Creates a span representing the creation of an AI agent.

Parameters
  • agentName string - The name of the agent being created
Return Type

createCreateKnowledgeBaseSpan

Isolated Function
function createCreateKnowledgeBaseSpan(string kbName) returns CreateKnowledgeBaseSpan

Creates a span representing the creation of a knowledge base.

Parameters
  • kbName string - The name of the knowledge base being created
Return Type

createEmbeddingSpan

Isolated Function
function createEmbeddingSpan(string embeddingModel) returns EmbeddingSpan

Creates a span representing an embedding generation operation.

Parameters
  • embeddingModel string - The embedding model name or identifier
Return Type

createExecuteToolSpan

Isolated Function
function createExecuteToolSpan(string toolName) returns ExecuteToolSpan

Creates a span representing the execution of an AI tool.

Parameters
  • toolName string - The name of the tool being executed
Return Type

createGenerateContentSpan

Isolated Function
function createGenerateContentSpan(string llmModel) returns GenerateContentSpan

Creates a span representing a generate content LLM interaction.

Parameters
  • llmModel string - The name of the LLM or chat model used
Return Type

createInvokeAgentSpan

Isolated Function
function createInvokeAgentSpan(string agentName) returns InvokeAgentSpan

Creates a span representing the invocation of an AI agent.

Parameters
  • agentName string - The name of the agent being invoked
Return Type

createKnowledgeBaseIngestSpan

Isolated Function
function createKnowledgeBaseIngestSpan(string kbName) returns KnowledgeBaseIngestSpan

Creates a span representing ingestion into a knowledge base.

Parameters
  • kbName string - The name of the knowledge base being ingested into
Return Type

createKnowledgeBaseRetrieveSpan

Isolated Function
function createKnowledgeBaseRetrieveSpan(string kbName) returns KnowledgeBaseRetrieveSpan

Creates a span representing a retrieval operation from a knowledge base.

Parameters
  • kbName string - The name of the knowledge base being queried
Return Type

getCurrentAiSpan

Isolated Function
function getCurrentAiSpan() returns AiSpan?

Retrieves the current active AI span, if any.

Returns the AiSpan associated with the current execution context. If tracing is not enabled or no span exists for the current context, returns ().

Return Type
  • AiSpan? - 
    • The current active AI span, or () if none is active

Classes

ai.observe: ChatSpan

Isolated

Chat-specific LLM span implementation for chat operations.

addTag

Isolated Function
function addTag("gen_ai.knowledge_base.retrieve.input.filter"|"gen_ai.knowledge_base.retrieve.input.limit"|"gen_ai.knowledge_base.retrieve.input.query"|"gen_ai.knowledge_base.ingest.input.chunks"|"gen_ai.knowledge_base.id"|"gen_ai.knowledge_base.name"|"gen_ai.input.tools"|"gen_ai.input.content"|"gen_ai.tool.output"|"gen_ai.tool.arguments"|"gen_ai.tool.type"|"gen_ai.tool.description"|"gen_ai.tool.name"|"gen_ai.tool.call.id"|"gen_ai.agent.tools"|"gen_ai.agent.name"|"gen_ai.agent.id"|"gen_ai.system_instructions"|"gen_ai.output.messages"|"gen_ai.input.messages"|"gen_ai.usage.output_tokens"|"gen_ai.usage.input_tokens"|"gen_ai.response.id"|"gen_ai.response.finish_reasons"|"gen_ai.request.temperature"|"gen_ai.request.stop_sequences"|"gen_ai.response.model"|"gen_ai.request.model"|"gen_ai.output.type"|"gen_ai.conversation.id"|"gen_ai.provider.name"|"gen_ai.operation.name" key, anydata value) returns ()

Adds a tag to the span.

Method included from *LlmSpan

addProvider

Isolated Function
function addProvider(string providerName)

Records the provider name used for the request.

Parameters
  • providerName string - The name of the AI provider/service (for example: openai)

addTemperature

Isolated Function
function addTemperature(float|decimal temperature)

Records the temperature setting used for the request.

Parameters
  • temperature float|decimal - The temperature value controlling randomness

addInputMessages

Isolated Function
function addInputMessages(json messages)

Records the input messages payload for the request.

Parameters
  • messages json - The input messages sent to the model

addOutputMessages

Isolated Function
function addOutputMessages(json messages)

Records the output messages payload produced by the model.

Parameters
  • messages json - The output messages returned by the model

addResponseModel

Isolated Function
function addResponseModel(string modelName)

Records the model name used for the response.

Parameters
  • modelName string - The model identifier/name used to generate the response (for example: gpt-40-2024)

addTools

Isolated Function
function addTools(json[] tools)

Records the tools schema send to the model.

Parameters
  • tools json[] - An array of tool schemas sent the the model

addResponseId

Isolated Function
function addResponseId(string|int id)

Records the response identifier assigned by the provider.

Parameters
  • id string|int - The provider-assigned response identifier

addInputTokenCount

Isolated Function
function addInputTokenCount(int count)

Records the count of input tokens consumed by the request.

Parameters
  • count int - Number of input tokens consumed

addOutputTokenCount

Isolated Function
function addOutputTokenCount(int count)

Records the count of output tokens produced by the response.

Parameters
  • count int - Number of output tokens produced

addFinishReason

Isolated Function
function addFinishReason(string|string[] reason)

Records the finish reason(s) returned by the model.

Parameters
  • reason string|string[] - A finish reason string or an array of reasons returned by the model

addOutputType

Isolated Function
function addOutputType(OutputType outputType)

Sets the response output type (e.g., text or json).

Parameters
  • outputType OutputType - The output type describing the response format

addStopSequence

Isolated Function
function addStopSequence(string|string[] stopSequence)

Records one or more stop sequences supplied to the model.

Parameters
  • stopSequence string|string[] - A single stop sequence or an array of stop sequences

close

Isolated Function
function close(error? err)

Closes the span and records its final status.

Parameters
  • err error? (default ()) - Optional error that indicates if the operation failed

ai.observe: CreateAgentSpan

Isolated

Represents a tracing span for creating an agent.

addTag

Isolated Function
function addTag("gen_ai.knowledge_base.retrieve.input.filter"|"gen_ai.knowledge_base.retrieve.input.limit"|"gen_ai.knowledge_base.retrieve.input.query"|"gen_ai.knowledge_base.ingest.input.chunks"|"gen_ai.knowledge_base.id"|"gen_ai.knowledge_base.name"|"gen_ai.input.tools"|"gen_ai.input.content"|"gen_ai.tool.output"|"gen_ai.tool.arguments"|"gen_ai.tool.type"|"gen_ai.tool.description"|"gen_ai.tool.name"|"gen_ai.tool.call.id"|"gen_ai.agent.tools"|"gen_ai.agent.name"|"gen_ai.agent.id"|"gen_ai.system_instructions"|"gen_ai.output.messages"|"gen_ai.input.messages"|"gen_ai.usage.output_tokens"|"gen_ai.usage.input_tokens"|"gen_ai.response.id"|"gen_ai.response.finish_reasons"|"gen_ai.request.temperature"|"gen_ai.request.stop_sequences"|"gen_ai.response.model"|"gen_ai.request.model"|"gen_ai.output.type"|"gen_ai.conversation.id"|"gen_ai.provider.name"|"gen_ai.operation.name" key, anydata value) returns ()

Adds a tag to the span.

Method included from *AiSpan

addId

Isolated Function
function addId(string agentId)

Records the agent ID assigned after creation.

Parameters
  • agentId string - The agent identifier

addSystemInstructions

Isolated Function
function addSystemInstructions(string instructions)

Records system instruction of the agent.

Parameters
  • instructions string - The system instructions string

addTools

Isolated Function
function addTools(json tools)

Records the tools used by the agent.

Parameters
  • tools json - Tools used by the agent

close

Isolated Function
function close(error? err)

Closes the agent creation span and records its final status.

Parameters
  • err error? (default ()) - Optional error that indicates if the operation failed

ai.observe: CreateKnowledgeBaseSpan

Isolated

Represents a tracing span for creating a knowledge base.

addTag

Isolated Function
function addTag("gen_ai.knowledge_base.retrieve.input.filter"|"gen_ai.knowledge_base.retrieve.input.limit"|"gen_ai.knowledge_base.retrieve.input.query"|"gen_ai.knowledge_base.ingest.input.chunks"|"gen_ai.knowledge_base.id"|"gen_ai.knowledge_base.name"|"gen_ai.input.tools"|"gen_ai.input.content"|"gen_ai.tool.output"|"gen_ai.tool.arguments"|"gen_ai.tool.type"|"gen_ai.tool.description"|"gen_ai.tool.name"|"gen_ai.tool.call.id"|"gen_ai.agent.tools"|"gen_ai.agent.name"|"gen_ai.agent.id"|"gen_ai.system_instructions"|"gen_ai.output.messages"|"gen_ai.input.messages"|"gen_ai.usage.output_tokens"|"gen_ai.usage.input_tokens"|"gen_ai.response.id"|"gen_ai.response.finish_reasons"|"gen_ai.request.temperature"|"gen_ai.request.stop_sequences"|"gen_ai.response.model"|"gen_ai.request.model"|"gen_ai.output.type"|"gen_ai.conversation.id"|"gen_ai.provider.name"|"gen_ai.operation.name" key, anydata value) returns ()

Adds a tag to the span.

Method included from *AiSpan

addId

Isolated Function
function addId(string|int id)

Records the knowledge base ID assigned after creation

Parameters
  • id string|int - The knowledge base identifier

close

Isolated Function
function close(error? err)

Closes the knowledge base creation span and records its final status.

Parameters
  • err error? (default ()) - Optional error that indicates if the operation failed

ai.observe: EmbeddingSpan

Isolated

Represents a tracing span for embedding model operations.

addTag

Isolated Function
function addTag("gen_ai.knowledge_base.retrieve.input.filter"|"gen_ai.knowledge_base.retrieve.input.limit"|"gen_ai.knowledge_base.retrieve.input.query"|"gen_ai.knowledge_base.ingest.input.chunks"|"gen_ai.knowledge_base.id"|"gen_ai.knowledge_base.name"|"gen_ai.input.tools"|"gen_ai.input.content"|"gen_ai.tool.output"|"gen_ai.tool.arguments"|"gen_ai.tool.type"|"gen_ai.tool.description"|"gen_ai.tool.name"|"gen_ai.tool.call.id"|"gen_ai.agent.tools"|"gen_ai.agent.name"|"gen_ai.agent.id"|"gen_ai.system_instructions"|"gen_ai.output.messages"|"gen_ai.input.messages"|"gen_ai.usage.output_tokens"|"gen_ai.usage.input_tokens"|"gen_ai.response.id"|"gen_ai.response.finish_reasons"|"gen_ai.request.temperature"|"gen_ai.request.stop_sequences"|"gen_ai.response.model"|"gen_ai.request.model"|"gen_ai.output.type"|"gen_ai.conversation.id"|"gen_ai.provider.name"|"gen_ai.operation.name" key, anydata value) returns ()

Adds a tag to the span.

Method included from *AiSpan

addResponseModel

Isolated Function
function addResponseModel(string model)

Records the response model name used for the embedding.

Parameters
  • model string - The model identifier/name used to generate the embedding

addProvider

Isolated Function
function addProvider(string providerName)

Records the provider name used for the embedding request.

Parameters
  • providerName string - The name of the AI provider/service (for example: openai)

addInputContent

Isolated Function
function addInputContent(anydata content)

Records the input content for the embedding request.

Parameters
  • content anydata - The input content to be embedded

addInputTokenCount

Isolated Function
function addInputTokenCount(int count)

Records the input token count for the embedding request.

Parameters
  • count int - Number of input tokens consumed

close

Isolated Function
function close(error? err)

Closes the embedding span and records its final status.

Parameters
  • err error? (default ()) - Optional error that indicates if the operation failed

ai.observe: ExecuteToolSpan

Isolated

Represents a tracing span for executing a tool.

addTag

Isolated Function
function addTag("gen_ai.knowledge_base.retrieve.input.filter"|"gen_ai.knowledge_base.retrieve.input.limit"|"gen_ai.knowledge_base.retrieve.input.query"|"gen_ai.knowledge_base.ingest.input.chunks"|"gen_ai.knowledge_base.id"|"gen_ai.knowledge_base.name"|"gen_ai.input.tools"|"gen_ai.input.content"|"gen_ai.tool.output"|"gen_ai.tool.arguments"|"gen_ai.tool.type"|"gen_ai.tool.description"|"gen_ai.tool.name"|"gen_ai.tool.call.id"|"gen_ai.agent.tools"|"gen_ai.agent.name"|"gen_ai.agent.id"|"gen_ai.system_instructions"|"gen_ai.output.messages"|"gen_ai.input.messages"|"gen_ai.usage.output_tokens"|"gen_ai.usage.input_tokens"|"gen_ai.response.id"|"gen_ai.response.finish_reasons"|"gen_ai.request.temperature"|"gen_ai.request.stop_sequences"|"gen_ai.response.model"|"gen_ai.request.model"|"gen_ai.output.type"|"gen_ai.conversation.id"|"gen_ai.provider.name"|"gen_ai.operation.name" key, anydata value) returns ()

Adds a tag to the span.

Method included from *AiSpan

addId

Isolated Function
function addId(string|int toolCallId)

Records the tool call ID of the execution.

Parameters
  • toolCallId string|int - The tool call identifier

addDescription

Isolated Function
function addDescription(string description)

Records the tool description of the execution.

Parameters
  • description string - The tool description string

addType

Isolated Function
function addType(ToolType toolType)

Records the tool type of the execution.

Parameters

addArguments

Isolated Function
function addArguments(json arguments)

Records arguments of the tool execution.

Parameters
  • arguments json - The tool arguments

addOutput

Isolated Function
function addOutput(anydata output)

Records output of the tool execution.

Parameters
  • output anydata - The output produced by the tool

close

Isolated Function
function close(error? err)

Closes the tool execution span and records its final status.

Parameters
  • err error? (default ()) - Optional error that indicates if the operation failed

ai.observe: GenerateContentSpan

Isolated

Generate-content specific LLM span implementation.

addTag

Isolated Function
function addTag("gen_ai.knowledge_base.retrieve.input.filter"|"gen_ai.knowledge_base.retrieve.input.limit"|"gen_ai.knowledge_base.retrieve.input.query"|"gen_ai.knowledge_base.ingest.input.chunks"|"gen_ai.knowledge_base.id"|"gen_ai.knowledge_base.name"|"gen_ai.input.tools"|"gen_ai.input.content"|"gen_ai.tool.output"|"gen_ai.tool.arguments"|"gen_ai.tool.type"|"gen_ai.tool.description"|"gen_ai.tool.name"|"gen_ai.tool.call.id"|"gen_ai.agent.tools"|"gen_ai.agent.name"|"gen_ai.agent.id"|"gen_ai.system_instructions"|"gen_ai.output.messages"|"gen_ai.input.messages"|"gen_ai.usage.output_tokens"|"gen_ai.usage.input_tokens"|"gen_ai.response.id"|"gen_ai.response.finish_reasons"|"gen_ai.request.temperature"|"gen_ai.request.stop_sequences"|"gen_ai.response.model"|"gen_ai.request.model"|"gen_ai.output.type"|"gen_ai.conversation.id"|"gen_ai.provider.name"|"gen_ai.operation.name" key, anydata value) returns ()

Adds a tag to the span.

Method included from *LlmSpan

addProvider

Isolated Function
function addProvider(string providerName)

Records the provider name used for the request.

Parameters
  • providerName string - The name of the AI provider/service (for example: openai)

addTemperature

Isolated Function
function addTemperature(float|decimal temperature)

Records the temperature setting used for the request.

Parameters
  • temperature float|decimal - The temperature value controlling randomness

addInputMessages

Isolated Function
function addInputMessages(json messages)

Records the input messages payload for the request.

Parameters
  • messages json - The input messages sent to the model

addOutputMessages

Isolated Function
function addOutputMessages(json messages)

Records the output messages payload produced by the model.

Parameters
  • messages json - The output messages returned by the model

addResponseModel

Isolated Function
function addResponseModel(string modelName)

Records the model name used for the response.

Parameters
  • modelName string - The model identifier/name used to generate the response (for example: gpt-40-2024)

addTools

Isolated Function
function addTools(json[] tools)

Records the tools schema send to the model.

Parameters
  • tools json[] - An array of tool schemas sent the the model

addResponseId

Isolated Function
function addResponseId(string|int id)

Records the response identifier assigned by the provider.

Parameters
  • id string|int - The provider-assigned response identifier

addInputTokenCount

Isolated Function
function addInputTokenCount(int count)

Records the count of input tokens consumed by the request.

Parameters
  • count int - Number of input tokens consumed

addOutputTokenCount

Isolated Function
function addOutputTokenCount(int count)

Records the count of output tokens produced by the response.

Parameters
  • count int - Number of output tokens produced

addFinishReason

Isolated Function
function addFinishReason(string|string[] reason)

Records the finish reason(s) returned by the model.

Parameters
  • reason string|string[] - A finish reason string or an array of reasons returned by the model

addOutputType

Isolated Function
function addOutputType(OutputType outputType)

Sets the response output type (e.g., text or json).

Parameters
  • outputType OutputType - The output type describing the response format

addStopSequence

Isolated Function
function addStopSequence(string|string[] stopSequence)

Records one or more stop sequences supplied to the model.

Parameters
  • stopSequence string|string[] - A single stop sequence or an array of stop sequences

close

Isolated Function
function close(error? err)

Closes the span and records its final status.

Parameters
  • err error? (default ()) - Optional error that indicates if the operation failed

ai.observe: InvokeAgentSpan

Isolated

Represents a tracing span for invoking an agent.

addTag

Isolated Function
function addTag("gen_ai.knowledge_base.retrieve.input.filter"|"gen_ai.knowledge_base.retrieve.input.limit"|"gen_ai.knowledge_base.retrieve.input.query"|"gen_ai.knowledge_base.ingest.input.chunks"|"gen_ai.knowledge_base.id"|"gen_ai.knowledge_base.name"|"gen_ai.input.tools"|"gen_ai.input.content"|"gen_ai.tool.output"|"gen_ai.tool.arguments"|"gen_ai.tool.type"|"gen_ai.tool.description"|"gen_ai.tool.name"|"gen_ai.tool.call.id"|"gen_ai.agent.tools"|"gen_ai.agent.name"|"gen_ai.agent.id"|"gen_ai.system_instructions"|"gen_ai.output.messages"|"gen_ai.input.messages"|"gen_ai.usage.output_tokens"|"gen_ai.usage.input_tokens"|"gen_ai.response.id"|"gen_ai.response.finish_reasons"|"gen_ai.request.temperature"|"gen_ai.request.stop_sequences"|"gen_ai.response.model"|"gen_ai.request.model"|"gen_ai.output.type"|"gen_ai.conversation.id"|"gen_ai.provider.name"|"gen_ai.operation.name" key, anydata value) returns ()

Adds a tag to the span.

Method included from *AiSpan

addId

Isolated Function
function addId(string agentId)

Records the agent ID of the invocation.

Parameters
  • agentId string - The agent identifier

addSystemInstruction

Isolated Function
function addSystemInstruction(string instruction)

Records system instruction of the agent.

Parameters
  • instruction string - The system instruction

addSessionId

Isolated Function
function addSessionId(string sessionId)

Records the session ID of the invocation.

Parameters
  • sessionId string - The session/conversation identifier

addInput

Isolated Function
function addInput(string query)

Records the input query of the agent invocation.

Parameters
  • query string - The input query string

addOutput

Isolated Function
function addOutput(OutputType outputType, json output)

Records the output of the agent invocation.

Parameters
  • output json - The output messages

close

Isolated Function
function close(error? err)

Closes the agent invocation span and records its final status.

Parameters
  • err error? (default ()) - Optional error that indicates if the operation failed

ai.observe: KnowledgeBaseIngestSpan

Isolated

Represents a tracing span for ingesting data into a knowledge base.

addTag

Isolated Function
function addTag("gen_ai.knowledge_base.retrieve.input.filter"|"gen_ai.knowledge_base.retrieve.input.limit"|"gen_ai.knowledge_base.retrieve.input.query"|"gen_ai.knowledge_base.ingest.input.chunks"|"gen_ai.knowledge_base.id"|"gen_ai.knowledge_base.name"|"gen_ai.input.tools"|"gen_ai.input.content"|"gen_ai.tool.output"|"gen_ai.tool.arguments"|"gen_ai.tool.type"|"gen_ai.tool.description"|"gen_ai.tool.name"|"gen_ai.tool.call.id"|"gen_ai.agent.tools"|"gen_ai.agent.name"|"gen_ai.agent.id"|"gen_ai.system_instructions"|"gen_ai.output.messages"|"gen_ai.input.messages"|"gen_ai.usage.output_tokens"|"gen_ai.usage.input_tokens"|"gen_ai.response.id"|"gen_ai.response.finish_reasons"|"gen_ai.request.temperature"|"gen_ai.request.stop_sequences"|"gen_ai.response.model"|"gen_ai.request.model"|"gen_ai.output.type"|"gen_ai.conversation.id"|"gen_ai.provider.name"|"gen_ai.operation.name" key, anydata value) returns ()

Adds a tag to the span.

Method included from *AiSpan

addId

Isolated Function
function addId(string|int id)

Records the knowledge base ID for the ingest operation.

Parameters
  • id string|int - The knowledge base identifier

addInputChunks

Isolated Function
function addInputChunks(json chunks)

Records the input chunks provied/generated for the ingest operation

Parameters
  • chunks json - The input chunks to be ingested

close

Isolated Function
function close(error? err)

Closes the ingest span and records its final status

Parameters
  • err error? (default ()) - Optional error that indicates if the operation failed

ai.observe: KnowledgeBaseRetrieveSpan

Isolated

Represents a tracing span for retrieving data from a knowledge base.

addTag

Isolated Function
function addTag("gen_ai.knowledge_base.retrieve.input.filter"|"gen_ai.knowledge_base.retrieve.input.limit"|"gen_ai.knowledge_base.retrieve.input.query"|"gen_ai.knowledge_base.ingest.input.chunks"|"gen_ai.knowledge_base.id"|"gen_ai.knowledge_base.name"|"gen_ai.input.tools"|"gen_ai.input.content"|"gen_ai.tool.output"|"gen_ai.tool.arguments"|"gen_ai.tool.type"|"gen_ai.tool.description"|"gen_ai.tool.name"|"gen_ai.tool.call.id"|"gen_ai.agent.tools"|"gen_ai.agent.name"|"gen_ai.agent.id"|"gen_ai.system_instructions"|"gen_ai.output.messages"|"gen_ai.input.messages"|"gen_ai.usage.output_tokens"|"gen_ai.usage.input_tokens"|"gen_ai.response.id"|"gen_ai.response.finish_reasons"|"gen_ai.request.temperature"|"gen_ai.request.stop_sequences"|"gen_ai.response.model"|"gen_ai.request.model"|"gen_ai.output.type"|"gen_ai.conversation.id"|"gen_ai.provider.name"|"gen_ai.operation.name" key, anydata value) returns ()

Adds a tag to the span.

Method included from *AiSpan

addId

Isolated Function
function addId(string|int id)

Records the knowledge base ID for the retrieve operation.

Parameters
  • id string|int - The knowledge base identifier

addInputQuery

Isolated Function
function addInputQuery(json query)

Records the input query for the retrieve operation.

Parameters
  • query json - The input query to retrieve data

addLimit

Isolated Function
function addLimit(int maxLimit)

Records the maximum limit for the retrieve operation.

Parameters
  • maxLimit int - The maximum number of results to retrieve

addFilter

Isolated Function
function addFilter(json filter)

Records the filter for the retrieve operation.

Parameters
  • filter json - The filter criteria for retrieval

close

Isolated Function
function close(error? err)

Closes the retrieve span and records its final status.

Parameters
  • err error? (default ()) - Optional error that indicates if the operation failed

Enums

ai.observe: OutputType

Represents the type of output produced by an LLM.

Members

TEXT - Represents a plain text output
JSON - Represents a structured JSON output

ai.observe: ToolType

Identifies the type of tool used by an agent.

Members

FUNCTION - Represents a function tool
EXTENTION - Represents a tool that directly invokes external APIs, such as an MCP server.

Object types

ai.observe: AiSpan

Distinct

Represents an AI tracing span that allows adding tags and closing the span.

close

Isolated Function
function close(error? err)

Closes the span and records its final status.

Parameters
  • err error? (default ()) - 

ai.observe: LlmSpan

Distinct

Represents an LLM-specific tracing span for LLM calls.

addTag

Isolated Function
function addTag("gen_ai.knowledge_base.retrieve.input.filter"|"gen_ai.knowledge_base.retrieve.input.limit"|"gen_ai.knowledge_base.retrieve.input.query"|"gen_ai.knowledge_base.ingest.input.chunks"|"gen_ai.knowledge_base.id"|"gen_ai.knowledge_base.name"|"gen_ai.input.tools"|"gen_ai.input.content"|"gen_ai.tool.output"|"gen_ai.tool.arguments"|"gen_ai.tool.type"|"gen_ai.tool.description"|"gen_ai.tool.name"|"gen_ai.tool.call.id"|"gen_ai.agent.tools"|"gen_ai.agent.name"|"gen_ai.agent.id"|"gen_ai.system_instructions"|"gen_ai.output.messages"|"gen_ai.input.messages"|"gen_ai.usage.output_tokens"|"gen_ai.usage.input_tokens"|"gen_ai.response.id"|"gen_ai.response.finish_reasons"|"gen_ai.request.temperature"|"gen_ai.request.stop_sequences"|"gen_ai.response.model"|"gen_ai.request.model"|"gen_ai.output.type"|"gen_ai.conversation.id"|"gen_ai.provider.name"|"gen_ai.operation.name" key, anydata value) returns ()

Adds a tag to the span.

Method included from *AiSpan

close

Isolated Function
function close(error|() err) returns ()

Closes the span and records its final status.

Method included from *AiSpan

addProvider

Isolated Function
function addProvider(string providerName)

Records the provider name used for the request.

Parameters
  • providerName string - The name of the AI provider/service (for example: openai)

addTemperature

Isolated Function
function addTemperature(float|decimal temperature)

Records the temperature setting used for the request.

Parameters
  • temperature float|decimal - The temperature value controlling randomness

addInputMessages

Isolated Function
function addInputMessages(json messages)

Records the input messages payload for the request.

Parameters
  • messages json - The input messages sent to the model

addOutputMessages

Isolated Function
function addOutputMessages(json messages)

Records the output messages payload produced by the model.

Parameters
  • messages json - The output messages returned by the model

addResponseModel

Isolated Function
function addResponseModel(string modelName)

Records the model name used for the response.

Parameters
  • modelName string - The model identifier/name used to generate the response (for example: gpt-40-2024)

addResponseId

Isolated Function
function addResponseId(string|int id)

Records the response identifier assigned by the provider.

Parameters
  • id string|int - The provider-assigned response identifier

addInputTokenCount

Isolated Function
function addInputTokenCount(int count)

Records the count of input tokens consumed by the request.

Parameters
  • count int - Number of input tokens consumed

addOutputTokenCount

Isolated Function
function addOutputTokenCount(int count)

Records the count of output tokens produced by the model.

Parameters
  • count int - Number of output tokens produced

addFinishReason

Isolated Function
function addFinishReason(string|string[] reason)

Records the finish reason(s) returned by the model.

Parameters
  • reason string|string[] - A finish reason string or an array of reasons returned by the model

addOutputType

Isolated Function
function addOutputType(OutputType outputType)

Records the response output type

Parameters
  • outputType OutputType - The output type describing the response format

addStopSequence

Isolated Function
function addStopSequence(string|string[] stopSequence)

Records one or more stop sequences supplied to the model

Parameters
  • stopSequence string|string[] - A single stop sequence or an array of stop sequences

addTools

Isolated Function
function addTools(json[] tools)

Records the tools schema send to the model

Parameters
  • tools json[] - An array of tool schemas sent the the model

Import

import ballerina/ai.observe;Copy

Other versions

1.11.0

1.10.0

1.9.01.8.01.7.0
See more...

Metadata

Released date: 14 days ago

Version: 1.10.0

License: Apache-2.0

Compatibility

Platform: java21

Ballerina version: 2201.12.0

GraalVM compatible: Yes

Pull count

Total: 24351

Current verison: 443

Weekly downloads

Source repository

Keywords

AI/Agent

Cost/Freemium

Agent

Vendor/N/A

Area/AI

Type/Connector

Contributors

Dependencies

ballerina/math.vector/1.2.0ballerina/url/2.6.0ballerina/time/2.7.0
See more...

Dependents

sumudunissanka/ai.googleapis.vertex/1.0.0sumudunissanka/ai.googleapis.vertex/1.0.1sumudunissanka/ai.googleapis.vertex/1.0.2
See more...

Terms of service

Privacy policy

Cookie policy

Delete policy

© 2026 WSO2 LLC