Documentation
¶
Overview ¶
Package logging provides FlightRecorder integration for Go 1.25+. FlightRecorder enables lightweight, always-on tracing suitable for production.
Index ¶
- Constants
- func GetModelID(ctx context.Context) (core.ModelID, bool)
- func GetTokenInfo(ctx context.Context) (*core.TokenInfo, bool)
- func InitGlobalFlightRecorder(opts ...FlightRecorderOption)
- func SetLogger(l *Logger)
- func TraceLog(ctx context.Context, category, message string)
- func TraceRegion(ctx context.Context, name string) func()
- func TraceTask(ctx context.Context, name string) (context.Context, func())
- func TracingInterceptor() core.ModuleInterceptor
- func TracingInterceptorWithRLM(rlmSession *RLMTraceSession) core.ModuleInterceptor
- func WithModelID(ctx context.Context, modelID core.ModelID) context.Context
- func WithTokenInfo(ctx context.Context, info *core.TokenInfo) context.Context
- func WithTraceSession(ctx context.Context, session *TraceSession) context.Context
- type Config
- type ConsoleOutput
- type ConsoleOutputOption
- type FileOutput
- type FileOutputOption
- type FlightRecorder
- type FlightRecorderOption
- type JSONFormatter
- type LogEntry
- type LogFormatter
- type Logger
- func (l *Logger) Debug(ctx context.Context, format string, args ...interface{})
- func (l *Logger) Error(ctx context.Context, format string, args ...interface{})
- func (l *Logger) Fatal(ctx context.Context, msg string)
- func (l *Logger) Fatalf(ctx context.Context, format string, args ...interface{})
- func (l *Logger) Info(ctx context.Context, format string, args ...interface{})
- func (l *Logger) PromptCompletion(ctx context.Context, prompt, completion string, tokenInfo *core.TokenInfo)
- func (l *Logger) Warn(ctx context.Context, format string, args ...interface{})
- type Output
- type RLMCallEntry
- type RLMCodeBlock
- type RLMCodeResult
- type RLMIterationEntry
- type RLMMessage
- type RLMMetadataEntry
- type RLMSessionConfig
- type RLMTraceSession
- func (s *RLMTraceSession) Close() error
- func (s *RLMTraceSession) LogIteration(prompt []RLMMessage, response string, codeBlocks []RLMCodeBlock, ...) error
- func (s *RLMTraceSession) LogLLMCall(prompt string, response string, promptTokens int, completionTokens int, ...) error
- func (s *RLMTraceSession) Path() string
- type Severity
- type TextFormatter
- type TraceEvent
- type TraceEventType
- type TraceFormat
- type TraceOutput
- type TraceOutputOption
- type TraceSession
- func (s *TraceSession) Close() error
- func (s *TraceSession) EmitCodeExec(spanID string, iteration int, code, stdout, stderr string, ...) error
- func (s *TraceSession) EmitError(spanID, errorType, message string, recoverable bool) error
- func (s *TraceSession) EmitLLMCall(spanID, provider, model, prompt, response string, usage *core.TokenUsage, ...) error
- func (s *TraceSession) EmitModule(spanID, moduleType, moduleName, signature string, ...) error
- func (s *TraceSession) EmitSpanEnd(spanID string, outputs map[string]any, err error, durationMs int64) error
- func (s *TraceSession) EmitSpanStart(spanID, parentID, operation string, inputs map[string]any) error
- func (s *TraceSession) EmitToolCall(spanID, toolName string, input, output any, durationMs int64, success bool, ...) error
- func (s *TraceSession) TraceID() string
Constants ¶
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 ¶
GetModelID retrieves ModelID from context.
func GetTokenInfo ¶
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
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
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
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 ¶
WithModelID adds a ModelID to the context.
func WithTokenInfo ¶
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) 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
LogFormatter defines an interface for formatting log entries.
type Logger ¶
type Logger struct {
// contains filtered or unexported fields
}
Logger provides the core logging functionality.
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
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.
func ParseSeverity ¶ added in v0.37.0
ParseSeverity converts a string to a Severity level. Returns INFO level for unknown strings.
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 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 (*TraceSession) Close ¶ added in v0.75.0
func (s *TraceSession) Close() error
func (*TraceSession) EmitCodeExec ¶ added in v0.75.0
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 (*TraceSession) EmitSpanEnd ¶ added in v0.75.0
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 (*TraceSession) TraceID ¶ added in v0.75.0
func (s *TraceSession) TraceID() string