logging

package
v0.83.1 Latest Latest
Warning

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

Go to latest
Published: Apr 22, 2026 License: MIT Imports: 17 Imported by: 0

Documentation

Overview

Package logging provides FlightRecorder integration for Go 1.25+. FlightRecorder enables lightweight, always-on tracing suitable for production.

Index

Constants

View Source
const (
	// ModelIDKey is used to store/retrieve ModelID from context.
	ModelIDKey contextKey = "model_id"

	// TokenInfoKey is used to store/retrieve token usage information.
	TokenInfoKey contextKey = "token_info"
)

Variables

This section is empty.

Functions

func GetModelID

func GetModelID(ctx context.Context) (core.ModelID, bool)

GetModelID retrieves ModelID from context.

func GetTokenInfo

func GetTokenInfo(ctx context.Context) (*core.TokenInfo, bool)

GetTokenInfo retrieves TokenInfo from context.

func InitGlobalFlightRecorder added in v0.69.0

func InitGlobalFlightRecorder(opts ...FlightRecorderOption)

InitGlobalFlightRecorder initializes and starts the global FlightRecorder. Safe to call multiple times; only the first call has effect. If the flight recorder fails to start, it logs the error and continues without recording.

func SetLogger

func SetLogger(l *Logger)

SetLogger allows setting a custom configured logger as the global instance.

func TraceLog added in v0.69.0

func TraceLog(ctx context.Context, category, message string)

TraceLog logs a message to the trace at the current point. Useful for marking significant events in the trace timeline.

func TraceRegion added in v0.69.0

func TraceRegion(ctx context.Context, name string) func()

TraceRegion wraps trace.WithRegion for convenient span creation. Use this to annotate important code sections in traces.

Example:

defer TraceRegion(ctx, "ProcessModule")()

func TraceTask added in v0.69.0

func TraceTask(ctx context.Context, name string) (context.Context, func())

TraceTask creates a trace task for tracking high-level operations. Returns a new context and an end function.

Example:

ctx, endTask := TraceTask(ctx, "Optimization")
defer endTask()

func TracingInterceptor added in v0.75.0

func TracingInterceptor() core.ModuleInterceptor

TracingInterceptor creates a module interceptor that logs LLM calls.

func TracingInterceptorWithRLM added in v0.75.0

func TracingInterceptorWithRLM(rlmSession *RLMTraceSession) core.ModuleInterceptor

TracingInterceptorWithRLM creates an interceptor that logs in RLM-compatible format.

func WithModelID

func WithModelID(ctx context.Context, modelID core.ModelID) context.Context

WithModelID adds a ModelID to the context.

func WithTokenInfo

func WithTokenInfo(ctx context.Context, info *core.TokenInfo) context.Context

WithTokenInfo adds TokenInfo to the context.

func WithTraceSession added in v0.75.0

func WithTraceSession(ctx context.Context, session *TraceSession) context.Context

WithTraceSession adds a TraceSession to the context.

Types

type Config

type Config struct {
	Severity      Severity
	Outputs       []Output
	SampleRate    uint32
	DefaultFields map[string]interface{}
}

Config allows flexible logger configuration.

type ConsoleOutput

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

ConsoleOutput formats logs for human readability.

func NewConsoleOutput

func NewConsoleOutput(useStderr bool, opts ...ConsoleOutputOption) *ConsoleOutput

func (*ConsoleOutput) Close

func (c *ConsoleOutput) Close() error

Close cleans up any resources.

func (*ConsoleOutput) Sync

func (c *ConsoleOutput) Sync() error

func (*ConsoleOutput) Write

func (o *ConsoleOutput) Write(e LogEntry) error

type ConsoleOutputOption

type ConsoleOutputOption func(*ConsoleOutput)

func WithColor

func WithColor(enabled bool) ConsoleOutputOption

type FileOutput added in v0.21.0

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

FileOutput formats logs and writes them to a file.

func NewFileOutput added in v0.21.0

func NewFileOutput(path string, opts ...FileOutputOption) (*FileOutput, error)

NewFileOutput creates a new file-based logger output.

func (*FileOutput) Close added in v0.21.0

func (f *FileOutput) Close() error

Close closes the file.

func (*FileOutput) Sync added in v0.21.0

func (f *FileOutput) Sync() error

Sync flushes any buffered data to the underlying file.

func (*FileOutput) Write added in v0.21.0

func (f *FileOutput) Write(e LogEntry) error

Write implements the Output interface.

type FileOutputOption added in v0.21.0

type FileOutputOption func(*FileOutput)

FileOutputOption is a functional option for configuring FileOutput.

func WithBufferSize added in v0.21.0

func WithBufferSize(size int) FileOutputOption

WithBufferSize sets the internal buffer size for writes.

func WithFormatter added in v0.21.0

func WithFormatter(formatter LogFormatter) FileOutputOption

WithFormatter sets a custom log formatter.

func WithJSONFormat added in v0.21.0

func WithJSONFormat(enabled bool) FileOutputOption

WithJSONFormat configures the output to use JSON formatting.

func WithRotation added in v0.21.0

func WithRotation(maxSizeBytes int64, maxFiles int) FileOutputOption

WithRotation enables log file rotation.

type FlightRecorder added in v0.69.0

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

FlightRecorder wraps Go 1.25's runtime/trace.FlightRecorder for production diagnostics. It maintains a ring buffer of recent trace data that can be dumped on-demand (e.g., when an error occurs or performance degrades).

Usage:

fr := NewFlightRecorder(WithMinAge(10 * time.Second))
fr.Start()
defer fr.Stop()

// When an interesting event occurs:
fr.Snapshot("error_occurred.trace")

func GlobalFlightRecorder added in v0.69.0

func GlobalFlightRecorder() *FlightRecorder

GlobalFlightRecorder returns a shared FlightRecorder instance. Initialize with InitGlobalFlightRecorder before use.

func NewFlightRecorder added in v0.69.0

func NewFlightRecorder(opts ...FlightRecorderOption) *FlightRecorder

NewFlightRecorder creates a new FlightRecorder with the given options. The FlightRecorder uses Go 1.25's runtime/trace.FlightRecorder which maintains a ring buffer of trace data with minimal overhead (~1% CPU).

func (*FlightRecorder) Enabled added in v0.69.0

func (fr *FlightRecorder) Enabled() bool

Enabled returns true if the flight recorder is currently running.

func (*FlightRecorder) Snapshot added in v0.69.0

func (fr *FlightRecorder) Snapshot(filename string) error

Snapshot writes the current trace buffer to a file. Call this when an interesting event occurs (error, slow request, etc.) to capture what happened leading up to that moment.

func (*FlightRecorder) SnapshotOnError added in v0.69.0

func (fr *FlightRecorder) SnapshotOnError(err error, filename string) error

SnapshotOnError is a helper that takes a snapshot when an error occurs. Returns the original error for chaining.

Example:

result, err := module.Process(ctx, inputs)
if err != nil {
    return fr.SnapshotOnError(err, "module_error.trace")
}

func (*FlightRecorder) Start added in v0.69.0

func (fr *FlightRecorder) Start() error

Start begins recording trace data into the ring buffer. This is safe to call in production with minimal overhead.

func (*FlightRecorder) Stop added in v0.69.0

func (fr *FlightRecorder) Stop()

Stop stops recording trace data.

type FlightRecorderOption added in v0.69.0

type FlightRecorderOption func(*FlightRecorder)

FlightRecorderOption configures a FlightRecorder.

func WithMaxBytes added in v0.69.0

func WithMaxBytes(n uint64) FlightRecorderOption

WithMaxBytes sets the maximum size of the trace buffer in bytes. This takes precedence over MinAge. If 0, the maximum is implementation defined.

func WithMinAge added in v0.69.0

func WithMinAge(d time.Duration) FlightRecorderOption

WithMinAge sets the minimum age of events to keep in the trace buffer. Default is 10 seconds. Longer durations capture more history but use more memory.

type JSONFormatter added in v0.21.0

type JSONFormatter struct{}

JSONFormatter implements LogFormatter for JSON output.

func (*JSONFormatter) Format added in v0.21.0

func (f *JSONFormatter) Format(e LogEntry) string

Format formats a LogEntry as JSON.

type LogEntry

type LogEntry struct {
	// Standard fields
	Time     int64
	Severity Severity
	Message  string
	File     string
	Line     int
	Function string
	TraceID  string // Added trace ID field

	// LLM-specific fields
	ModelID   string          // The LLM model being used
	TokenInfo *core.TokenInfo // Token usage information
	Latency   int64           // Operation duration in milliseconds
	Cost      float64         // Operation cost in dollars

	// General structured data
	Fields map[string]interface{}
}

LogEntry represents a structured log record with fields particularly relevant to LLM operations.

type LogFormatter added in v0.21.0

type LogFormatter interface {
	Format(entry LogEntry) string
}

LogFormatter defines an interface for formatting log entries.

type Logger

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

Logger provides the core logging functionality.

func GetLogger

func GetLogger() *Logger

GetLogger returns the global logger instance.

func NewLogger

func NewLogger(cfg Config) *Logger

NewLogger creates a new logger with the given configuration.

func (*Logger) Debug

func (l *Logger) Debug(ctx context.Context, format string, args ...interface{})

Regular severity-based logging methods.

func (*Logger) Error

func (l *Logger) Error(ctx context.Context, format string, args ...interface{})

func (*Logger) Fatal added in v0.19.0

func (l *Logger) Fatal(ctx context.Context, msg string)

func (*Logger) Fatalf added in v0.19.0

func (l *Logger) Fatalf(ctx context.Context, format string, args ...interface{})

func (*Logger) Info

func (l *Logger) Info(ctx context.Context, format string, args ...interface{})

func (*Logger) PromptCompletion

func (l *Logger) PromptCompletion(ctx context.Context, prompt, completion string, tokenInfo *core.TokenInfo)

LLM-specific logging methods.

func (*Logger) Warn

func (l *Logger) Warn(ctx context.Context, format string, args ...interface{})

type Output

type Output interface {
	Write(LogEntry) error
	Sync() error
	Close() error
}

Output interface allows for different logging destinations.

type RLMCallEntry added in v0.75.0

type RLMCallEntry struct {
	Prompt           string  `json:"prompt"`
	Response         string  `json:"response"`
	PromptTokens     int     `json:"prompt_tokens"`
	CompletionTokens int     `json:"completion_tokens"`
	ExecutionTime    float64 `json:"execution_time"`
}

RLMCallEntry represents a sub-LLM call in RLM format.

type RLMCodeBlock added in v0.75.0

type RLMCodeBlock struct {
	Code   string        `json:"code"`
	Result RLMCodeResult `json:"result"`
}

RLMCodeBlock represents an executed code block in RLM format.

type RLMCodeResult added in v0.75.0

type RLMCodeResult struct {
	Stdout        string         `json:"stdout"`
	Stderr        string         `json:"stderr"`
	Locals        map[string]any `json:"locals"`
	ExecutionTime float64        `json:"execution_time"`
	RLMCalls      []RLMCallEntry `json:"rlm_calls"`
}

RLMCodeResult represents code execution results in RLM format.

type RLMIterationEntry added in v0.75.0

type RLMIterationEntry struct {
	Type          string         `json:"type"`
	Iteration     int            `json:"iteration"`
	Timestamp     string         `json:"timestamp"`
	Prompt        []RLMMessage   `json:"prompt"`
	Response      string         `json:"response"`
	CodeBlocks    []RLMCodeBlock `json:"code_blocks"`
	FinalAnswer   any            `json:"final_answer"`
	IterationTime float64        `json:"iteration_time"`
}

RLMIterationEntry is compatible with rlm-go's IterationEntry for viewer support.

type RLMMessage added in v0.75.0

type RLMMessage struct {
	Role    string `json:"role"`
	Content string `json:"content"`
}

RLMMessage represents a chat message in RLM format.

type RLMMetadataEntry added in v0.75.0

type RLMMetadataEntry struct {
	Type              string         `json:"type"`
	Timestamp         string         `json:"timestamp"`
	RootModel         string         `json:"root_model"`
	MaxDepth          int            `json:"max_depth"`
	MaxIterations     int            `json:"max_iterations"`
	Backend           string         `json:"backend"`
	BackendKwargs     map[string]any `json:"backend_kwargs"`
	EnvironmentType   string         `json:"environment_type"`
	EnvironmentKwargs map[string]any `json:"environment_kwargs"`
	OtherBackends     any            `json:"other_backends"`
	Context           string         `json:"context,omitempty"`
	Query             string         `json:"query,omitempty"`
}

RLMMetadataEntry is compatible with rlm-go's MetadataEntry for viewer support.

type RLMSessionConfig added in v0.75.0

type RLMSessionConfig struct {
	RootModel     string
	MaxIterations int
	Backend       string
	BackendKwargs map[string]any
	Context       string
	Query         string
}

RLMSessionConfig holds configuration for an RLM trace session.

type RLMTraceSession added in v0.75.0

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

RLMTraceSession provides rlm-go viewer compatible logging.

func NewRLMTraceSession added in v0.75.0

func NewRLMTraceSession(logDir string, cfg RLMSessionConfig) (*RLMTraceSession, error)

NewRLMTraceSession creates a new RLM-compatible trace session.

func (*RLMTraceSession) Close added in v0.75.0

func (s *RLMTraceSession) Close() error

Close closes the log file.

func (*RLMTraceSession) LogIteration added in v0.75.0

func (s *RLMTraceSession) LogIteration(
	prompt []RLMMessage,
	response string,
	codeBlocks []RLMCodeBlock,
	finalAnswer any,
	iterationTime time.Duration,
) error

LogIteration logs a single iteration in RLM-compatible format.

func (*RLMTraceSession) LogLLMCall added in v0.75.0

func (s *RLMTraceSession) LogLLMCall(
	prompt string,
	response string,
	promptTokens int,
	completionTokens int,
	latency time.Duration,
) error

LogLLMCall logs an LLM call as a simple iteration (for non-RLM modules).

func (*RLMTraceSession) Path added in v0.75.0

func (s *RLMTraceSession) Path() string

Path returns the path to the log file.

type Severity

type Severity int32

Severity represents log levels with clear mapping to different stages of LLM operations.

const (
	DEBUG Severity = iota
	INFO
	WARN
	ERROR
	FATAL
)

func ParseSeverity added in v0.37.0

func ParseSeverity(level string) Severity

ParseSeverity converts a string to a Severity level. Returns INFO level for unknown strings.

func (Severity) String

func (s Severity) String() string

String provides human-readable severity levels.

type TextFormatter added in v0.21.0

type TextFormatter struct {
	// Whether to include timestamps in the output
	IncludeTimestamp bool
	// Whether to include file and line information
	IncludeLocation bool
	// Whether to include stack traces for errors
	IncludeStackTrace bool
}

TextFormatter implements LogFormatter with a simple text format.

func (*TextFormatter) Format added in v0.21.0

func (f *TextFormatter) Format(e LogEntry) string

Format formats a LogEntry as text.

type TraceEvent added in v0.75.0

type TraceEvent struct {
	Type      TraceEventType         `json:"type"`
	Timestamp time.Time              `json:"timestamp"`
	TraceID   string                 `json:"trace_id"`
	SpanID    string                 `json:"span_id,omitempty"`
	ParentID  string                 `json:"parent_id,omitempty"`
	Data      map[string]interface{} `json:"data,omitempty"`
}

type TraceEventType added in v0.75.0

type TraceEventType string
const (
	TraceEventSession  TraceEventType = "session"
	TraceEventSpan     TraceEventType = "span"
	TraceEventLLMCall  TraceEventType = "llm_call"
	TraceEventModule   TraceEventType = "module"
	TraceEventCodeExec TraceEventType = "code_exec"
	TraceEventToolCall TraceEventType = "tool_call"
	TraceEventError    TraceEventType = "error"
)

type TraceFormat added in v0.75.0

type TraceFormat int

TraceFormat specifies the output format for trace files.

const (
	// TraceFormatDSPy is the native dspy-go format with rich span/event data.
	TraceFormatDSPy TraceFormat = iota
	// TraceFormatRLM is compatible with rlm-go's viewer (metadata + iteration entries).
	TraceFormatRLM
)

type TraceOutput added in v0.75.0

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

func NewTraceOutput added in v0.75.0

func NewTraceOutput(path string, opts ...TraceOutputOption) (*TraceOutput, error)

func (*TraceOutput) Close added in v0.75.0

func (t *TraceOutput) Close() error

func (*TraceOutput) Flush added in v0.75.0

func (t *TraceOutput) Flush() error

func (*TraceOutput) Write added in v0.75.0

func (t *TraceOutput) Write(event TraceEvent) error

type TraceOutputOption added in v0.75.0

type TraceOutputOption func(*TraceOutput)

func WithTraceBufferSize added in v0.75.0

func WithTraceBufferSize(size int) TraceOutputOption

func WithTraceRotation added in v0.75.0

func WithTraceRotation(maxSize int64, maxFiles int) TraceOutputOption

type TraceSession added in v0.75.0

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

func GetTraceSession added in v0.75.0

func GetTraceSession(ctx context.Context) *TraceSession

GetTraceSession retrieves the TraceSession from context.

func NewTraceSession added in v0.75.0

func NewTraceSession(path string, opts ...TraceOutputOption) (*TraceSession, error)

func StartTraceSession added in v0.75.0

func StartTraceSession(ctx context.Context, path string, metadata map[string]any) (*TraceSession, error)

func (*TraceSession) Close added in v0.75.0

func (s *TraceSession) Close() error

func (*TraceSession) EmitCodeExec added in v0.75.0

func (s *TraceSession) EmitCodeExec(spanID string, iteration int, code, stdout, stderr string, locals map[string]any, durationMs int64, subLLMCalls []map[string]any) error

func (*TraceSession) EmitError added in v0.75.0

func (s *TraceSession) EmitError(spanID, errorType, message string, recoverable bool) error

func (*TraceSession) EmitLLMCall added in v0.75.0

func (s *TraceSession) EmitLLMCall(spanID, provider, model, prompt, response string, usage *core.TokenUsage, latencyMs int64) error

func (*TraceSession) EmitModule added in v0.75.0

func (s *TraceSession) EmitModule(spanID, moduleType, moduleName, signature string, inputs, outputs map[string]any, durationMs int64, llmCalls int, totalTokens int, success bool) error

func (*TraceSession) EmitSpanEnd added in v0.75.0

func (s *TraceSession) EmitSpanEnd(spanID string, outputs map[string]any, err error, durationMs int64) error

func (*TraceSession) EmitSpanStart added in v0.75.0

func (s *TraceSession) EmitSpanStart(spanID, parentID, operation string, inputs map[string]any) error

func (*TraceSession) EmitToolCall added in v0.75.0

func (s *TraceSession) EmitToolCall(spanID, toolName string, input, output any, durationMs int64, success bool, err error) error

func (*TraceSession) TraceID added in v0.75.0

func (s *TraceSession) TraceID() string

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL