Documentation
¶
Overview ¶
Package obs owns specd's structured operational logging.
Loggers are hard-wired to stderr so Brain tracing never mutates stdout, whose bytes are part of specd's deterministic CLI contract.
Index ¶
- func BrainLogPath(root, sessionID string) (string, error)
- func LogContextCompact(ctx context.Context, logger *slog.Logger, session string, ...)
- func LogEvent(ctx context.Context, logger *slog.Logger, event, session, worker, task string, ...)
- func MetricsEndpointAddr() string
- func NewLogger() *slog.Logger
- func NewSessionLogger(root, sessionID string) (*slog.Logger, io.Closer)
- func ParseFormat(raw string) string
- func ParseLevel(raw string) slog.Level
- func RecordDuration(name string, d time.Duration)
- func RenderPrometheusMetrics() string
- func WithFields(ctx context.Context, slug, phase, role string) context.Context
- type EndSpan
- type TimelineEvent
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func BrainLogPath ¶
BrainLogPath returns the structured timeline path for a Brain session.
func LogContextCompact ¶
func LogContextCompact(ctx context.Context, logger *slog.Logger, session string, estimatedTokens, hostReportedTokens, budget int, reason, file string)
LogContextCompact emits a context.compact timeline event (spec §4.7): the token ledger checkpoint a host produced when shedding context. It rides the same brain.log surface as LogEvent, so `specd replay` shows it inline.
func LogEvent ¶
func LogEvent(ctx context.Context, logger *slog.Logger, event, session, worker, task string, dur time.Duration, exit int)
LogEvent emits one stable Brain event.
func MetricsEndpointAddr ¶
func MetricsEndpointAddr() string
MetricsEndpointAddr returns the active metrics listener address, if enabled.
func NewLogger ¶
NewLogger returns a slog logger that writes to stderr only. SPECD_LOG_FORMAT selects JSON or text output; JSON is the default.
func NewSessionLogger ¶
NewSessionLogger mirrors logs to .specd/sessions/<sessionID>/brain.log. File setup is best-effort: failures are warned on stderr and logging continues to stderr only.
func ParseFormat ¶
ParseFormat maps SPECD_LOG_FORMAT to a slog output mode.
func ParseLevel ¶
ParseLevel maps SPECD_LOG to a slog level. Unknown values fail closed to warn.
func RecordDuration ¶
RecordDuration emits one structured duration metric through specd's existing stderr logger and stores it for the optional Prometheus text endpoint.
func RenderPrometheusMetrics ¶
func RenderPrometheusMetrics() string
RenderPrometheusMetrics renders the in-memory duration metrics in Prometheus text exposition format without requiring a Prometheus client dependency.
Types ¶
type TimelineEvent ¶
type TimelineEvent struct {
Time string `json:"time,omitempty"`
Level string `json:"level,omitempty"`
Message string `json:"msg,omitempty"`
Event string `json:"event"`
Slug string `json:"slug,omitempty"`
Phase string `json:"phase,omitempty"`
Role string `json:"role,omitempty"`
Session string `json:"session,omitempty"`
SessionID string `json:"session_id,omitempty"`
Worker string `json:"worker,omitempty"`
Task string `json:"task,omitempty"`
DurMS int64 `json:"dur_ms,omitempty"`
Exit int `json:"exit,omitempty"`
// Context-compaction fields (spec §4.7), present only on context.compact events.
EstimatedTokens int `json:"estimated_tokens,omitempty"`
HostReportedTokens int `json:"host_reported_tokens,omitempty"`
Budget int `json:"budget,omitempty"`
Reason string `json:"reason,omitempty"`
CompactionFile string `json:"compaction_file,omitempty"`
}
TimelineEvent is one parsed Brain structured event.
func ReadTimeline ¶
func ReadTimeline(root, sessionID string) ([]TimelineEvent, error)
ReadTimeline parses NDJSON slog output and keeps records carrying an event.
Source Files