observability

package
v0.2.3 Latest Latest
Warning

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

 Go to latest Published: Mar 4, 2026 License: MIT Imports: 9 Imported by: 0

Documentation

Overview

Package observability provides metrics collection and tracing for CLI operations.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type CLIHooks 

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

CLIHooks implements basecamp.Hooks for CLI observability. It supports configurable verbosity levels:

  • 0: Silent (collect stats only, no output)
  • 1: Operations only (log SDK operations)
  • 2: Operations + requests (log both operations and HTTP requests)

func NewCLIHooks 

func NewCLIHooks(level int, collector *SessionCollector, writer *TraceWriter) *CLIHooks

NewCLIHooks creates a new CLIHooks with the given verbosity level. If collector is nil, metrics are not collected. If writer is nil, no trace output is produced.

func (*CLIHooks) Level 

func (h *CLIHooks) Level() int

Level returns the current verbosity level.

func (*CLIHooks) OnOperationEnd 

func (h *CLIHooks) OnOperationEnd(ctx context.Context, op basecamp.OperationInfo, err error, duration time.Duration)

OnOperationEnd is called when a semantic SDK operation completes.

func (*CLIHooks) OnOperationStart 

func (h *CLIHooks) OnOperationStart(ctx context.Context, op basecamp.OperationInfo) context.Context

OnOperationStart is called when a semantic SDK operation begins.

func (*CLIHooks) OnRequestEnd 

func (h *CLIHooks) OnRequestEnd(ctx context.Context, info basecamp.RequestInfo, result basecamp.RequestResult)

OnRequestEnd is called after an HTTP request completes.

func (*CLIHooks) OnRequestStart 

func (h *CLIHooks) OnRequestStart(ctx context.Context, info basecamp.RequestInfo) context.Context

OnRequestStart is called before an HTTP request is sent.

func (*CLIHooks) OnRetry 

func (h *CLIHooks) OnRetry(ctx context.Context, info basecamp.RequestInfo, attempt int, err error)

OnRetry is called before a retry attempt.

func (*CLIHooks) SetLevel 

func (h *CLIHooks) SetLevel(level int)

SetLevel changes the verbosity level at runtime.

type OperationMetrics 

type OperationMetrics struct {
	Service      string // e.g., "Todos", "Projects"
	Operation    string // e.g., "Complete", "List"
	ResourceType string // e.g., "todo", "project"
	IsMutation   bool
	ResourceID   int64
	Duration     time.Duration
	Error        error
}

OperationMetrics holds timing information for a high-level SDK operation.

type RequestMetrics 

type RequestMetrics struct {
	Method     string
	URL        string
	Attempt    int
	StatusCode int
	Duration   time.Duration
	FromCache  bool
	Retryable  bool
	Error      error
}

RequestMetrics holds timing and status information for a single HTTP request.

type RetryMetrics 

type RetryMetrics struct {
	Method  string
	URL     string
	Attempt int
	Error   error
}

RetryMetrics records a retry event.

type SessionCollector 

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

SessionCollector accumulates metrics across a CLI session. It is safe for concurrent use and uses counters instead of unbounded slices.

func NewSessionCollector 

func NewSessionCollector() *SessionCollector

NewSessionCollector creates a new SessionCollector.

func (*SessionCollector) RecordOperation 

func (c *SessionCollector) RecordOperation(m OperationMetrics)

RecordOperation records metrics for a high-level operation.

func (*SessionCollector) RecordOperationFromSDK 

func (c *SessionCollector) RecordOperationFromSDK(op basecamp.OperationInfo, err error, duration time.Duration)

RecordOperationFromSDK records metrics from SDK types.

func (*SessionCollector) RecordRequest 

func (c *SessionCollector) RecordRequest(m RequestMetrics)

RecordRequest records metrics for an HTTP request.

func (*SessionCollector) RecordRequestFromSDK 

func (c *SessionCollector) RecordRequestFromSDK(info basecamp.RequestInfo, result basecamp.RequestResult)

RecordRequestFromSDK records metrics from SDK types.

func (*SessionCollector) RecordRetry 

func (c *SessionCollector) RecordRetry(_ RetryMetrics)

RecordRetry records a retry event.

func (*SessionCollector) RecordRetryFromSDK 

func (c *SessionCollector) RecordRetryFromSDK(info basecamp.RequestInfo, attempt int, err error)

RecordRetryFromSDK records a retry event from SDK types.

func (*SessionCollector) Reset 

func (c *SessionCollector) Reset()

Reset clears all collected metrics and resets the start time.

func (*SessionCollector) Summary 

func (c *SessionCollector) Summary() SessionMetrics

Summary returns aggregated metrics for the session.

type SessionMetrics 

type SessionMetrics struct {
	StartTime       time.Time
	EndTime         time.Time
	TotalRequests   int
	CacheHits       int
	CacheMisses     int
	TotalOperations int
	FailedOps       int
	TotalRetries    int
	TotalLatency    time.Duration
}

SessionMetrics aggregates metrics for an entire CLI session.

func SessionMetricsFromMap 

func SessionMetricsFromMap(stats map[string]any) *SessionMetrics

SessionMetricsFromMap creates a SessionMetrics from a stats map (as used in JSON output). This allows renderers to use the same formatting logic as direct SessionMetrics consumers.

func (*SessionMetrics) FormatParts 

func (m *SessionMetrics) FormatParts() []string

FormatParts returns the formatted parts for a stats summary line. The parts are: duration, requests, cached, retries, failed. Zero-value fields are omitted (except duration which is always included).

type TraceWriter 

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

TraceWriter outputs human-readable trace information to stderr. It formats output with timestamps relative to session start.

func NewTraceWriter 

func NewTraceWriter() *TraceWriter

NewTraceWriter creates a new TraceWriter that writes to stderr.

func NewTraceWriterTo 

func NewTraceWriterTo(w io.Writer) *TraceWriter

NewTraceWriterTo creates a new TraceWriter that writes to the given writer.

func (*TraceWriter) Reset 

func (t *TraceWriter) Reset()

Reset resets the start time for relative timestamps.

func (*TraceWriter) WriteOperationEnd 

func (t *TraceWriter) WriteOperationEnd(op basecamp.OperationInfo, err error, duration time.Duration)

WriteOperationEnd writes an operation completion trace line. Format: [0.234s] Completed Todos.Complete (234ms)

func (*TraceWriter) WriteOperationStart 

func (t *TraceWriter) WriteOperationStart(op basecamp.OperationInfo)

WriteOperationStart writes an operation start trace line. Format: [0.234s] Calling Todos.Complete

func (*TraceWriter) WriteRequestEnd 

func (t *TraceWriter) WriteRequestEnd(info basecamp.RequestInfo, result basecamp.RequestResult)

WriteRequestEnd writes a request completion trace line. Format: [0.234s] <- 200 (45ms) or [0.234s] <- 200 (cached)

func (*TraceWriter) WriteRequestStart 

func (t *TraceWriter) WriteRequestStart(info basecamp.RequestInfo)

WriteRequestStart writes a request start trace line. Format: [0.234s] -> GET /buckets/123/todos Sensitive query parameters are redacted.

func (*TraceWriter) WriteRetry 

func (t *TraceWriter) WriteRetry(info basecamp.RequestInfo, attempt int, err error)

WriteRetry writes a retry trace line. Format: [0.234s] RETRY #2: connection reset

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.