llmobs

package
v2.6.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Feb 9, 2026 License: Apache-2.0, BSD-3-Clause, Apache-2.0 Imports: 6 Imported by: 2

Documentation

Overview

Package llmobs contains the Go SDK to use DataDog's LLM Observability product. You can read more at https://docs.datadoghq.com/llm_observability

EXPERIMENTAL: This package is experimental and may change or be removed at any time without notice. It is not subject to the Go module's compatibility promise.

Index

Examples

Constants

View Source 
const (
	// MetricKeyInputTokens is the standard key for input token count metrics.
	MetricKeyInputTokens = "input_tokens"

	// MetricKeyOutputTokens is the standard key for output token count metrics.
	MetricKeyOutputTokens = "output_tokens"

	// MetricKeyTotalTokens is the standard key for total token count metrics.
	MetricKeyTotalTokens = "total_tokens"
)

Variables

This section is empty.

Functions

func SubmitEvaluationFromSpan 

func SubmitEvaluationFromSpan[T EvaluationValue](label string, value T, span EvaluatedSpan, opts ...EvaluationOption)

SubmitEvaluationFromSpan submits an evaluation metric for the given span. The metric will be associated with the span using its span ID and trace ID.

func SubmitEvaluationFromTag 

func SubmitEvaluationFromTag[T EvaluationValue](label string, value T, tag JoinTag, opts ...EvaluationOption)

SubmitEvaluationFromTag submits an evaluation metric for spans identified by a tag key-value pair.

Types

type AgentSpan 

type AgentSpan struct {
	// contains filtered or unexported fields
}

AgentSpan represents a span for AI agent operations. Use AnnotateTextIO to annotate with text input/output.

func StartAgentSpan 

func StartAgentSpan(ctx context.Context, name string, opts ...StartSpanOption) (*AgentSpan, context.Context)

StartAgentSpan starts an LLMObs span of kind Agent. Pass the returned context to subsequent start span calls to create child spans of this one.

func (*AgentSpan) AnnotateTextIO 

func (s *AgentSpan) AnnotateTextIO(input, output string, opts ...AnnotateOption)

type AnnotateOption 

type AnnotateOption func(a *illmobs.SpanAnnotations)

AnnotateOption configures span annotations. Use with span annotation methods.

func WithAnnotatedMetadata 

func WithAnnotatedMetadata(meta map[string]any) AnnotateOption

WithAnnotatedMetadata adds metadata to the span annotation. Metadata can contain arbitrary structured data related to the operation.

func WithAnnotatedMetrics 

func WithAnnotatedMetrics(metrics map[string]float64) AnnotateOption

WithAnnotatedMetrics adds metrics to the span annotation. Metrics are numeric values that can be aggregated and analyzed. Common metrics include token counts, latency, costs, etc. Multiple calls to this function will merge the metrics.

func WithAnnotatedSessionID 

func WithAnnotatedSessionID(sessionID string) AnnotateOption

WithAnnotatedSessionID sets the session ID tag for the span annotation. This is a convenience function for setting the session ID tag specifically.

func WithAnnotatedTags 

func WithAnnotatedTags(tags map[string]string) AnnotateOption

WithAnnotatedTags adds tags to the span annotation.

func WithIntent added in v2.5.0 

func WithIntent(intent string) AnnotateOption

WithIntent sets the intent for the span. Intent is a description of a reason for calling an MCP tool.

type AnySpan 

type AnySpan struct {
	// contains filtered or unexported fields
}

AnySpan represents a generic LLMObs span retrieved from context. It can represent any span kind (LLM, Workflow, Agent, Tool, Task, Embedding, or Retrieval). Use the As* methods to convert it to a specific span type for type-specific operations.

func SpanFromContext 

func SpanFromContext(ctx context.Context) (*AnySpan, bool)

SpanFromContext retrieves the active LLMObs span from the given context. Returns an AnySpan and true if found, nil and false otherwise. The returned AnySpan can be converted to specific span types using the As* methods (AsLLM, AsWorkflow, AsAgent, AsTool, AsTask, AsEmbedding, AsRetrieval).

Example 
package main

import (
	"context"
	"log"

	"github.com/DataDog/dd-trace-go/v2/llmobs"
)

func main() {
	ctx := context.Background()
	_, ctx = llmobs.StartLLMSpan(ctx, "llm-span", llmobs.WithMLApp("ml-app"), llmobs.WithModelName("model_name"), llmobs.WithModelProvider("model_provider"))

	span, ok := llmobs.SpanFromContext(ctx)
	if !ok {
		log.Fatal("span not found in context")
	}
	llm, ok := span.AsLLM()
	if !ok {
		log.Fatal("span was not llm")
	}
	llm.Finish()
}

func (AnySpan) APMTraceID 

func (s AnySpan) APMTraceID() string
func (s AnySpan) AddLink(link SpanLink)

func (AnySpan) Annotate 

func (s AnySpan) Annotate(opts ...AnnotateOption)

func (*AnySpan) AsAgent 

func (s *AnySpan) AsAgent() (*AgentSpan, bool)

AsAgent attempts to convert the span to an AgentSpan. Returns the AgentSpan and true if the span is of kind Agent, otherwise returns nil and false.

func (*AnySpan) AsEmbedding 

func (s *AnySpan) AsEmbedding() (*EmbeddingSpan, bool)

AsEmbedding attempts to convert the span to an EmbeddingSpan. Returns the EmbeddingSpan and true if the span is of kind Embedding, otherwise returns nil and false.

func (*AnySpan) AsLLM 

func (s *AnySpan) AsLLM() (*LLMSpan, bool)

AsLLM attempts to convert the span to an LLMSpan. Returns the LLMSpan and true if the span is of kind LLM, otherwise returns nil and false.

func (*AnySpan) AsRetrieval 

func (s *AnySpan) AsRetrieval() (*RetrievalSpan, bool)

AsRetrieval attempts to convert the span to a RetrievalSpan. Returns the RetrievalSpan and true if the span is of kind Retrieval, otherwise returns nil and false.

func (*AnySpan) AsTask 

func (s *AnySpan) AsTask() (*TaskSpan, bool)

AsTask attempts to convert the span to a TaskSpan. Returns the TaskSpan and true if the span is of kind Task, otherwise returns nil and false.

func (*AnySpan) AsTool 

func (s *AnySpan) AsTool() (*ToolSpan, bool)

AsTool attempts to convert the span to a ToolSpan. Returns the ToolSpan and true if the span is of kind Tool, otherwise returns nil and false.

func (*AnySpan) AsWorkflow 

func (s *AnySpan) AsWorkflow() (*WorkflowSpan, bool)

AsWorkflow attempts to convert the span to a WorkflowSpan. Returns the WorkflowSpan and true if the span is of kind Workflow, otherwise returns nil and false.

func (AnySpan) Finish 

func (s AnySpan) Finish(opts ...FinishSpanOption)

func (AnySpan) Kind 

func (s AnySpan) Kind() string

func (AnySpan) Name 

func (s AnySpan) Name() string

func (AnySpan) SpanID 

func (s AnySpan) SpanID() string

func (AnySpan) TraceID 

func (s AnySpan) TraceID() string

type EmbeddedDocument 

type EmbeddedDocument = illmobs.EmbeddedDocument

EmbeddedDocument represents a document for embedding operations. Contains the document content and metadata. It is used to annotate input of embedding spans.

type EmbeddingSpan 

type EmbeddingSpan struct {
	// contains filtered or unexported fields
}

EmbeddingSpan represents a span for text embedding operations. Use AnnotateEmbeddingIO to annotate with input documents and output embeddings.

func StartEmbeddingSpan 

func StartEmbeddingSpan(ctx context.Context, name string, opts ...StartSpanOption) (*EmbeddingSpan, context.Context)

StartEmbeddingSpan starts an LLMObs span of kind Embedding. Pass the returned context to subsequent start span calls to create child spans of this one.

Note: embedding spans are annotated with input EmbeddedDocument and output text.

func (EmbeddingSpan) APMTraceID 

func (s EmbeddingSpan) APMTraceID() string
func (s EmbeddingSpan) AddLink(link SpanLink)

func (EmbeddingSpan) Annotate 

func (s EmbeddingSpan) Annotate(opts ...AnnotateOption)

func (*EmbeddingSpan) AnnotateEmbeddingIO 

func (s *EmbeddingSpan) AnnotateEmbeddingIO(input []EmbeddedDocument, output string, opts ...AnnotateOption)

AnnotateEmbeddingIO annotates the embedding span with input documents and output embeddings text.

func (EmbeddingSpan) Finish 

func (s EmbeddingSpan) Finish(opts ...FinishSpanOption)

func (EmbeddingSpan) Kind 

func (s EmbeddingSpan) Kind() string

func (EmbeddingSpan) Name 

func (s EmbeddingSpan) Name() string

func (EmbeddingSpan) SpanID 

func (s EmbeddingSpan) SpanID() string

func (EmbeddingSpan) TraceID 

func (s EmbeddingSpan) TraceID() string

type EvaluatedSpan added in v2.3.1 

type EvaluatedSpan interface {
	SpanID() string
	TraceID() string
}

EvaluatedSpan is the interface used in SubmitEvaluationFromSpan to identify the span to evaluate.

type EvaluationOption 

type EvaluationOption func(cfg *illmobs.EvaluationConfig)

EvaluationOption configures evaluation metric submission.

func WithEvaluationMLApp 

func WithEvaluationMLApp(mlApp string) EvaluationOption

WithEvaluationMLApp sets the ML application name for the evaluation metric. If not set, uses the global ML app configuration.

func WithEvaluationTags 

func WithEvaluationTags(tags []string) EvaluationOption

WithEvaluationTags sets tags for the evaluation metric.

func WithEvaluationTimestamp 

func WithEvaluationTimestamp(t time.Time) EvaluationOption

WithEvaluationTimestamp sets a custom timestamp for the evaluation metric. If not set, uses the current time.

type EvaluationValue 

type EvaluationValue interface {
	~bool | ~string | ~int | ~int8 | ~int16 | ~int32 | ~int64 | ~uint | ~uint8 | ~uint16 | ~uint32 | ~uint64 | ~float32 | ~float64
}

EvaluationValue represents the allowed types for evaluation metric values. Supports boolean values (true/false), string values (categorical), and numeric values (scores).

type FinishSpanOption 

type FinishSpanOption func(cfg *illmobs.FinishSpanConfig)

FinishSpanOption configures span finishing. Use with span.Finish().

func WithError 

func WithError(err error) FinishSpanOption

WithError marks the finished span with the given error. The error will be captured with stack trace information and marked as a span error.

func WithFinishTime 

func WithFinishTime(t time.Time) FinishSpanOption

WithFinishTime sets a custom finish time for the span. If not provided, the current time is used when Finish() is called.

type JoinTag 

type JoinTag struct {
	// Key is the tag key to match against.
	Key string

	// Value is the tag value to match against.
	Value string
}

JoinTag represents a tag key-value pair used to identify spans for evaluation metrics. When using SubmitEvaluationFromTag, the metric will be associated with all spans that have a tag matching this key-value pair.

type LLMMessage 

type LLMMessage = illmobs.LLMMessage

LLMMessage represents a message in a conversation with a Large Language Model. It is used to annotate IO of LLM spans. Contains role (user, assistant, system) and content.

type LLMSpan 

type LLMSpan struct {
	// contains filtered or unexported fields
}

LLMSpan represents a span for Large Language Model operations. Use AnnotateLLMIO to annotate with LLM-specific input/output messages.

func StartLLMSpan 

func StartLLMSpan(ctx context.Context, name string, opts ...StartSpanOption) (*LLMSpan, context.Context)

StartLLMSpan starts an LLMObs span of kind LLM. Pass the returned context to subsequent start span calls to create child spans of this one.

Note: LLM spans are annotated with input/output as LLMMessage.

Example 
package main

import (
	"context"

	"github.com/DataDog/dd-trace-go/v2/llmobs"
)

func main() {
	ctx := context.Background()
	span, ctx := llmobs.StartLLMSpan(ctx, "llm-span", llmobs.WithMLApp("ml-app"), llmobs.WithModelName("model_name"), llmobs.WithModelProvider("model_provider"))
	defer span.Finish()

	input := []llmobs.LLMMessage{
		{
			Role:    "user",
			Content: "Hello world!",
		},
	}
	output := []llmobs.LLMMessage{
		{
			Role:    "assistant",
			Content: "How can I help?",
		},
	}
	span.AnnotateLLMIO(
		input,
		output,
		llmobs.WithAnnotatedMetadata(map[string]any{"temperature": 0, "max_tokens": 200}),
		llmobs.WithAnnotatedTags(map[string]string{"host": "host_name"}),
		llmobs.WithAnnotatedMetrics(map[string]float64{llmobs.MetricKeyInputTokens: 4, llmobs.MetricKeyOutputTokens: 6, llmobs.MetricKeyTotalTokens: 10}),
	)
}

func (LLMSpan) APMTraceID 

func (s LLMSpan) APMTraceID() string
func (s LLMSpan) AddLink(link SpanLink)

func (LLMSpan) Annotate 

func (s LLMSpan) Annotate(opts ...AnnotateOption)

func (*LLMSpan) AnnotateLLMIO 

func (s *LLMSpan) AnnotateLLMIO(input, output []LLMMessage, opts ...AnnotateOption)

AnnotateLLMIO annotates the LLM span with input and output messages. Messages should use the LLMMessage type with role and content.

func (LLMSpan) Finish 

func (s LLMSpan) Finish(opts ...FinishSpanOption)

func (LLMSpan) Kind 

func (s LLMSpan) Kind() string

func (LLMSpan) Name 

func (s LLMSpan) Name() string

func (LLMSpan) SpanID 

func (s LLMSpan) SpanID() string

func (LLMSpan) TraceID 

func (s LLMSpan) TraceID() string

type Prompt 

type Prompt = illmobs.Prompt

Prompt represents a structured prompt template used with LLMs.

type RetrievalSpan 

type RetrievalSpan struct {
	// contains filtered or unexported fields
}

RetrievalSpan represents a span for information retrieval operations. Use AnnotateRetrievalIO to annotate with input query and output retrieved documents.

func StartRetrievalSpan 

func StartRetrievalSpan(ctx context.Context, name string, opts ...StartSpanOption) (*RetrievalSpan, context.Context)

StartRetrievalSpan starts an LLMObs span of kind Retrieval. Pass the returned context to subsequent start span calls to create child spans of this one.

Note: retrieval spans are annotated with input text and output RetrievedDocument.

func (RetrievalSpan) APMTraceID 

func (s RetrievalSpan) APMTraceID() string
func (s RetrievalSpan) AddLink(link SpanLink)

func (RetrievalSpan) Annotate 

func (s RetrievalSpan) Annotate(opts ...AnnotateOption)

func (*RetrievalSpan) AnnotateRetrievalIO 

func (s *RetrievalSpan) AnnotateRetrievalIO(input string, output []RetrievedDocument, opts ...AnnotateOption)

AnnotateRetrievalIO annotates the retrieval span with input query text and output retrieved documents.

func (RetrievalSpan) Finish 

func (s RetrievalSpan) Finish(opts ...FinishSpanOption)

func (RetrievalSpan) Kind 

func (s RetrievalSpan) Kind() string

func (RetrievalSpan) Name 

func (s RetrievalSpan) Name() string

func (RetrievalSpan) SpanID 

func (s RetrievalSpan) SpanID() string

func (RetrievalSpan) TraceID 

func (s RetrievalSpan) TraceID() string

type RetrievedDocument 

type RetrievedDocument = illmobs.RetrievedDocument

RetrievedDocument represents a document for retrieval operations. Contains the document content, metadata, and relevance score. It is used to annotate output of retrieval spans.

type Span 

type Span interface {

	// Name returns the span name.
	Name() string

	// SpanID returns the unique identifier for this span.
	SpanID() string

	// Kind returns the span kind (llm, workflow, agent, tool, task, embedding, retrieval).
	Kind() string

	// TraceID returns the LLMObs trace identifier.
	TraceID() string

	// APMTraceID returns the underlying APM trace identifier.
	APMTraceID() string

	// AddLink adds a link to another span, useful for connecting related operations.
	AddLink(link SpanLink)

	// Finish completes the span and sends it for processing.
	Finish(opts ...FinishSpanOption)

	// Annotate allows to make generic span annotations. If you want to annotate Input/Output, you can use the specific
	// functions from each span kind.
	Annotate(opts ...AnnotateOption)
	// contains filtered or unexported methods
}

Span represents a generic LLMObs span that can be converted to specific span types. 

type SpanLink = illmobs.SpanLink

SpanLink represents a link between spans, typically used for connecting related operations across different traces or services.

type StartSpanOption 

type StartSpanOption func(cfg *illmobs.StartSpanConfig)

StartSpanOption configures span creation. Use with Start*Span functions.

func WithIntegration added in v2.5.0 

func WithIntegration(integration string) StartSpanOption

func WithMLApp 

func WithMLApp(mlApp string) StartSpanOption

WithMLApp sets the ML application name for the span. This overrides the global ML app configuration for this specific span.

func WithModelName 

func WithModelName(modelName string) StartSpanOption

WithModelName sets the specific model name for the span (e.g., "gpt-4", "claude-3"). Used primarily with LLM spans to track which model is being used.

func WithModelProvider 

func WithModelProvider(modelProvider string) StartSpanOption

WithModelProvider sets the model provider for the span (e.g., "openai", "anthropic"). Used primarily with LLM spans to track which provider is being used.

func WithSessionID 

func WithSessionID(sessionID string) StartSpanOption

WithSessionID sets the session identifier for the span.

func WithStartTime 

func WithStartTime(t time.Time) StartSpanOption

WithStartTime sets a custom start time for the span. If not provided, the current time is used.

type TaskSpan 

type TaskSpan struct {
	// contains filtered or unexported fields
}

TaskSpan represents a span for discrete task operations. Use AnnotateTextIO to annotate with text input/output.

func StartTaskSpan 

func StartTaskSpan(ctx context.Context, name string, opts ...StartSpanOption) (*TaskSpan, context.Context)

StartTaskSpan starts an LLMObs span of kind Task. Pass the returned context to subsequent start span calls to create child spans of this one.

func (*TaskSpan) AnnotateTextIO 

func (s *TaskSpan) AnnotateTextIO(input, output string, opts ...AnnotateOption)

type ToolCall added in v2.4.1 

type ToolCall = illmobs.ToolCall

ToolCall represents a call to a tool within an LLM message.

type ToolDefinition 

type ToolDefinition = illmobs.ToolDefinition

ToolDefinition represents the definition of a tool/function that an LLM can call.

type ToolResult added in v2.4.1 

type ToolResult = illmobs.ToolResult

ToolResult represents the result of a tool call within an LLM message.

type ToolSpan 

type ToolSpan struct {
	// contains filtered or unexported fields
}

ToolSpan represents a span for tool/function call operations. Use AnnotateTextIO to annotate with text input/output.

func StartToolSpan 

func StartToolSpan(ctx context.Context, name string, opts ...StartSpanOption) (*ToolSpan, context.Context)

StartToolSpan starts an LLMObs span of kind Tool. Pass the returned context to subsequent start span calls to create child spans of this one.

func (*ToolSpan) AnnotateTextIO 

func (s *ToolSpan) AnnotateTextIO(input, output string, opts ...AnnotateOption)

type WorkflowSpan 

type WorkflowSpan struct {
	// contains filtered or unexported fields
}

WorkflowSpan represents a span for high-level workflow operations. Use AnnotateTextIO to annotate with text input/output.

func StartWorkflowSpan 

func StartWorkflowSpan(ctx context.Context, name string, opts ...StartSpanOption) (*WorkflowSpan, context.Context)

StartWorkflowSpan starts an LLMObs span of kind Workflow. Pass the returned context to subsequent start span calls to create child spans of this one.

func (*WorkflowSpan) AnnotateTextIO 

func (s *WorkflowSpan) AnnotateTextIO(input, output string, opts ...AnnotateOption)

Source Files

View all Source files

Directories

Path Synopsis

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.