observability

package
v0.6.16 Latest Latest
Warning

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

 Go to latest Published: Aug 24, 2026 License: MIT Imports: 17 Imported by: 0

Documentation

Overview

Package observability records privacy-safe product lifecycle events.

Index

Constants

View Source 
const (
	DefaultDiagnosticRunLimit   = 50
	DefaultDiagnosticEventLimit = 500
	MaximumDiagnosticRunLimit   = 100
	MaximumDiagnosticEventLimit = 1000
)
View Source 
const (
	DefaultMaxBytes int64 = 10 << 20
	DefaultMaxFiles       = 5
)
View Source 
const (
	ApplicationStarted  = "application.started"
	ApplicationStopped  = "application.stopped"
	RunStarted          = "run.started"
	RunCompleted        = "run.completed"
	RunFailed           = "run.failed"
	TurnStarted         = "turn.started"
	TurnCompleted       = "turn.completed"
	TurnDiscarded       = "turn.discarded"
	StepStarted         = "step.started"
	StepCompleted       = "step.completed"
	StepDiscarded       = "step.discarded"
	ProviderStarted     = "provider.request.started"
	ProviderCompleted   = "provider.request.completed"
	ProviderFailed      = "provider.request.failed"
	HTTPAttemptStarted  = "provider.http_attempt.started"
	HTTPAttemptResponse = "provider.http_attempt.response"
	CheckpointCompleted = "checkpoint.completed"
	CheckpointFailed    = "checkpoint.failed"
	ToolStarted         = "tool.call.started"
	ToolCompleted       = "tool.call.completed"
	ToolFailed          = "tool.call.failed"
	ApprovalStarted     = "tool.approval.started"
	ApprovalCompleted   = "tool.approval.completed"
	ApprovalFailed      = "tool.approval.failed"
)

Variables

This section is empty.

Functions

func NewID 

func NewID(prefix string) string

NewID returns a process-local diagnostic ID with 128 bits of randomness. The fallback remains unique within the process if the system random source is unavailable; observability must not block a run because ID generation did.

Types

type DiagnosticEvent 

type DiagnosticEvent struct {
	Name                string    `json:"name"`
	Timestamp           time.Time `json:"timestamp"`
	TurnID              string    `json:"turnId,omitempty"`
	StepID              string    `json:"stepId,omitempty"`
	ProviderRequestID   string    `json:"providerRequestId,omitempty"`
	AttemptID           string    `json:"attemptId,omitempty"`
	ToolCallID          string    `json:"toolCallId,omitempty"`
	ToolName            string    `json:"toolName,omitempty"`
	Status              string    `json:"status,omitempty"`
	ErrorCode           string    `json:"errorCode,omitempty"`
	Reason              string    `json:"reason,omitempty"`
	DurationMS          int64     `json:"durationMs,omitempty"`
	TimeToFirstOutputMS int64     `json:"timeToFirstOutputMs,omitempty"`
	Provider            string    `json:"provider,omitempty"`
	Model               string    `json:"model,omitempty"`
	Attempt             int       `json:"attempt,omitempty"`
	HTTPStatus          int       `json:"httpStatus,omitempty"`
	InputTokens         int64     `json:"inputTokens,omitempty"`
	InputUnknown        bool      `json:"inputUnknown,omitempty"`
	OutputTokens        int64     `json:"outputTokens,omitempty"`
	CacheReadTokens     int64     `json:"cacheReadTokens,omitempty"`
	CacheWriteTokens    int64     `json:"cacheWriteTokens,omitempty"`
	TotalTokens         int64     `json:"totalTokens,omitempty"`
	CostTotalUSD        float64   `json:"costTotalUsd,omitempty"`
}

DiagnosticEvent contains only fields approved for the observability schema.

type DiagnosticQuery 

type DiagnosticQuery struct {
	SessionID    string
	RunID        string
	RunLimit     int
	EventsPerRun int
	Before       *DiagnosticRunCursor
	OrderByStart bool
}

DiagnosticQuery bounds and optionally scopes one read of the local log.

type DiagnosticReport 

type DiagnosticReport struct {
	Runs        []DiagnosticRun `json:"runs"`
	GeneratedAt time.Time       `json:"generatedAt"`
}

DiagnosticReport is the privacy-safe, UI-facing projection of local events.

func ReadDiagnosticReport 

func ReadDiagnosticReport(path string, query DiagnosticQuery) (DiagnosticReport, error)

ReadDiagnosticReport reads the active log and its numeric rotations. A partially written final line is ignored so observing an active runtime is harmless.

type DiagnosticRun 

type DiagnosticRun struct {
	ID                   string            `json:"id"`
	SessionID            string            `json:"sessionId"`
	Status               string            `json:"status"`
	ErrorCode            string            `json:"errorCode,omitempty"`
	StartedAt            time.Time         `json:"startedAt"`
	UpdatedAt            time.Time         `json:"updatedAt"`
	DurationMS           int64             `json:"durationMs,omitempty"`
	TimeToFirstOutputMS  int64             `json:"timeToFirstOutputMs,omitempty"`
	CheckpointDurationMS int64             `json:"checkpointDurationMs,omitempty"`
	ToolDurationMS       int64             `json:"toolDurationMs,omitempty"`
	ApprovalDurationMS   int64             `json:"approvalDurationMs,omitempty"`
	ProviderRequests     int               `json:"providerRequests"`
	ToolCalls            int               `json:"toolCalls"`
	ApprovalRequests     int               `json:"approvalRequests"`
	Retries              int               `json:"retries"`
	ContextRecoveries    int               `json:"contextRecoveries"`
	InputTokens          int64             `json:"inputTokens,omitempty"`
	OutputTokens         int64             `json:"outputTokens,omitempty"`
	CacheReadTokens      int64             `json:"cacheReadTokens,omitempty"`
	CacheWriteTokens     int64             `json:"cacheWriteTokens,omitempty"`
	TotalTokens          int64             `json:"totalTokens,omitempty"`
	CostTotalUSD         float64           `json:"costTotalUsd,omitempty"`
	Events               []DiagnosticEvent `json:"events"`
	OmittedEvents        int               `json:"omittedEvents,omitempty"`
}

DiagnosticRun summarizes one user-visible run and carries its event timeline.

type DiagnosticRunCursor 

type DiagnosticRunCursor struct {
	StartedAt time.Time
	RunID     string
}

DiagnosticRunCursor identifies one stable position in start-time order. RunID disambiguates runs that started at the same timestamp.

type DiscardRecorder 

type DiscardRecorder struct{}

DiscardRecorder ignores every event.

func (DiscardRecorder) Close 

func (DiscardRecorder) Close() error

func (DiscardRecorder) DeleteSession 

func (DiscardRecorder) DeleteSession(string) error

func (DiscardRecorder) Record 

func (DiscardRecorder) Record(Event)

type Event 

type Event struct {
	Name      string
	Level     slog.Level
	Timestamp time.Time

	SessionID         string
	RunID             string
	TurnID            string
	StepID            string
	RequestID         string
	AttemptID         string
	Status            string
	ErrorCode         string
	Reason            string
	StartedAt         time.Time
	Duration          time.Duration
	TimeToFirstOutput time.Duration

	Provider           string
	Model              string
	ResponseModel      string
	ProviderResponseID string
	StopReason         string
	ToolCallID         string
	ToolName           string
	Attempt            int
	HTTPStatus         int
	MessageCount       int
	AttachmentCount    int

	InputTokens      int64
	InputUnknown     bool
	OutputTokens     int64
	CacheReadTokens  int64
	CacheWriteTokens int64
	TotalTokens      int64
	CostInput        float64
	CostOutput       float64
	CostCacheRead    float64
	CostCacheWrite   float64
	CostTotal        float64
}

Event is one bounded, privacy-safe observability record. It intentionally has no arbitrary attribute bag: adding a field requires an explicit schema decision, which keeps prompts, tool arguments, and provider payloads out of the local diagnostic log.

type FileOptions 

type FileOptions struct {
	MaxBytes int64
	MaxFiles int
}

FileOptions configures bounded local JSONL storage. MaxFiles includes the active file. Zero values use the product defaults.

type JSONLRecorder 

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

JSONLRecorder writes one JSON object per line to a bounded set of private local files.

func NewJSONL 

func NewJSONL(path string, options FileOptions) (*JSONLRecorder, error)

NewJSONL opens a JSONL recorder rooted at path.

func (*JSONLRecorder) Close 

func (r *JSONLRecorder) Close() error

func (*JSONLRecorder) DeleteSession 

func (r *JSONLRecorder) DeleteSession(sessionID string) error

DeleteSession removes matching records from the active log and every rotation while keeping the recorder open for subsequent events.

func (*JSONLRecorder) Record 

func (r *JSONLRecorder) Record(event Event)

type Recorder 

type Recorder interface {
	Record(Event)
	Close() error
}

Recorder accepts structured lifecycle events. Record is best-effort and must never make product work fail. Close releases recorder-owned resources.

func OrDiscard 

func OrDiscard(recorder Recorder) Recorder

OrDiscard replaces a nil recorder with a no-op implementation.

type SessionCleaner 

type SessionCleaner interface {
	DeleteSession(sessionID string) error
}

SessionCleaner removes every persisted observability event for one session.

Source Files

View all Source files

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.