Documentation
¶
Overview ¶
Package diagnostics provides bounded, redacted operational log storage.
Index ¶
- Constants
- Variables
- func DescribeError(err error) (code, summary string)
- func RedactText(value string) string
- func WriteExport(w io.Writer, archive Export) error
- type AuditSink
- type BatchSink
- type BatchSinkFunc
- type ComponentSpec
- type Event
- type Export
- type ExportOptions
- type FileAuditStore
- type FileStore
- type Handler
- type MemoryStore
- type Page
- type Query
- type QueryAudit
- type ResourceCleanupAudit
- type ResourceCleanupAuditSink
- type Sanitizer
- type Shipper
- type ShipperOptions
- type Store
Constants ¶
const ( DefaultMaxBytes = 10 << 20 DefaultMaxAge = 14 * 24 * time.Hour DefaultLimit = 100 HardMaxLimit = 1000 )
const ExportSchemaVersion = 1
ExportSchemaVersion identifies the stable JSON contract written by WriteExport.
Variables ¶
var ErrShipperQueueFull = errors.New("diagnostics shipper queue is full")
var ErrStoreClosed = errors.New("diagnostics store is closed")
ErrStoreClosed is returned by FileStore.Append after Close.
Functions ¶
func DescribeError ¶ added in v0.1.63
DescribeError returns a stable, non-sensitive category and operator-facing summary for an error. Callers should log these fields instead of the raw error when the record may be persisted in the diagnostics store.
func RedactText ¶
RedactText removes common credential-bearing forms before text is allowed into durable diagnostics. This is intentionally conservative: structured attributes are allowlisted separately by Handler, while messages receive masking and a hard size bound at the store boundary.
Types ¶
type AuditSink ¶
type AuditSink interface {
RecordDiagnosticsQuery(context.Context, QueryAudit) error
}
type BatchSinkFunc ¶ added in v0.1.63
BatchSinkFunc adapts a function to BatchSink.
type ComponentSpec ¶ added in v0.1.63
type ComponentSpec struct {
Name string `json:"name"`
Description string `json:"description,omitempty"`
}
ComponentSpec describes one producer whose diagnostics are included in an export. Components are declared by the implementation that owns them, so a consumer can explain where an event came from without knowing Boxy's internal package layout.
type Event ¶
type Event struct {
ID string `json:"id"`
Timestamp time.Time `json:"timestamp"`
Level string `json:"level"`
Component string `json:"component,omitempty"`
Message string `json:"message,omitempty"`
Operation string `json:"operation,omitempty"`
Job string `json:"job,omitempty"`
Step string `json:"step,omitempty"`
Status string `json:"status,omitempty"`
Attempt int `json:"attempt,omitempty"`
ErrorCode string `json:"error_code,omitempty"`
ErrorSummary string `json:"error_summary,omitempty"`
// DurationMS is the elapsed time of the operation/step this event
// describes, in milliseconds. Zero means "not reported" — most events
// have no associated duration. See #355.
DurationMS int64 `json:"duration_ms,omitempty"`
Pool string `json:"pool,omitempty"`
Agent string `json:"agent,omitempty"`
Resource string `json:"resource,omitempty"`
Provider string `json:"provider,omitempty"`
Request string `json:"request,omitempty"`
}
Event is the safe, structured representation exposed by diagnostics. Fields not represented here must never cross the diagnostics boundary.
type Export ¶ added in v0.1.63
type Export struct {
SchemaVersion int `json:"schema_version"`
GeneratedAt time.Time `json:"generated_at"`
Sanitized bool `json:"sanitized"`
Components []ComponentSpec `json:"components"`
Events []Event `json:"events"`
}
Export is the portable, sanitized diagnostics archive.
func BuildExport ¶ added in v0.1.63
func BuildExport(events []Event, options ExportOptions) (Export, error)
BuildExport makes a bounded export and sanitizes every event. Sanitization uses stable placeholders for repeated values within this export, preserving correlation without exposing machine or user identity.
type ExportOptions ¶ added in v0.1.63
type ExportOptions struct {
GeneratedAt time.Time
Components []ComponentSpec
}
ExportOptions controls metadata for BuildExport. Event limits are enforced by the public package and cannot be disabled by a caller.
type FileAuditStore ¶
type FileAuditStore struct {
// contains filtered or unexported fields
}
func NewFileAuditStore ¶
func NewFileAuditStore(path string) (*FileAuditStore, error)
func (*FileAuditStore) RecordDiagnosticsQuery ¶
func (s *FileAuditStore) RecordDiagnosticsQuery(ctx context.Context, audit QueryAudit) error
func (*FileAuditStore) RecordResourceCleanup ¶ added in v0.1.59
func (s *FileAuditStore) RecordResourceCleanup(ctx context.Context, audit ResourceCleanupAudit) error
type FileStore ¶
type FileStore struct {
// contains filtered or unexported fields
}
FileStore is a bounded JSONL store. File metadata invalidates cached snapshots when another store or process changes the durable history.
func NewFileStore ¶
func (*FileStore) Close ¶ added in v0.1.69
Close stops the store accepting new events. It waits for an Append already in progress, and every later Append returns ErrStoreClosed without touching the filesystem. Query keeps working.
Appends otherwise recreate the store's directory (MkdirAll), so a log record that arrives after the owner has finished -- from any goroutine still using a slog handler wrapping this store -- could write the file back while the owner is removing its data directory (#376).
type Handler ¶
type Handler struct {
// contains filtered or unexported fields
}
Handler forwards records to the normal slog handler and independently stores a safe diagnostics projection. Storage failures are deliberately ignored so an observability disk problem cannot break the application.
type MemoryStore ¶
type MemoryStore struct {
// contains filtered or unexported fields
}
MemoryStore provides the same bounded query semantics for tests and embedders that do not need restart persistence.
func NewMemoryStore ¶
func NewMemoryStore() *MemoryStore
type Query ¶
type Query struct {
Since time.Time
Level string
Component string
Pool string
Agent string
Resource string
Provider string
Job string
Status string
Limit int
Cursor string
}
Query selects a bounded page of diagnostic events. Cursor values are opaque to callers and are produced by Page.NextCursor.
type QueryAudit ¶
type QueryAudit struct {
Actor string
Since string
Level string
Component string
Job string
Status string
Pool string
Agent string
Resource string
Provider string
Limit int
ResultCount int
}
QueryAudit is deliberately limited to safe query metadata.
type ResourceCleanupAudit ¶ added in v0.1.59
type ResourceCleanupAudit struct {
Actor string `json:"actor"`
Mode string `json:"mode"`
Force bool `json:"force"`
State string `json:"state"`
Unreferenced bool `json:"unreferenced"`
OlderThan string `json:"older_than,omitempty"`
CandidateCount int `json:"candidate_count"`
CleanedCount int `json:"cleaned_count"`
SkippedCount int `json:"skipped_count"`
ErrorCount int `json:"error_count"`
}
ResourceCleanupAudit describes safe metadata for an administrator cleanup mutation. It intentionally contains counts and IDs only; callers must not attach resource properties or provider credentials.
type ResourceCleanupAuditSink ¶ added in v0.1.59
type ResourceCleanupAuditSink interface {
RecordResourceCleanup(context.Context, ResourceCleanupAudit) error
}
ResourceCleanupAuditSink is optional so existing embedders with an audit sink that predates cleanup remain source-compatible.
type Sanitizer ¶ added in v0.1.63
type Sanitizer struct {
// contains filtered or unexported fields
}
Sanitizer is the public sanitization contract used by both exports and log shippers. It is intentionally stateful so repeated values receive the same placeholder during one incident report.
func NewSanitizer ¶ added in v0.1.63
func NewSanitizer() *Sanitizer
NewSanitizer returns a sanitizer with an empty per-report identity map.
type Shipper ¶ added in v0.1.63
type Shipper struct {
// contains filtered or unexported fields
}
Shipper is a bounded, retryable batch buffer. Submit never sends network traffic; callers choose when and where Flush sends the batch.
func NewShipper ¶ added in v0.1.63
func NewShipper(options ShipperOptions) *Shipper
NewShipper creates a bounded log shipper.
func (*Shipper) Flush ¶ added in v0.1.63
Flush sends at most MaxBatch events. A failed send leaves the batch queued at the front for a later retry.
func (*Shipper) Handler ¶ added in v0.1.63
Handler returns a slog handler that forwards safe events to next and queues a sanitized copy for the shipper. The next handler may be slog.Discard's equivalent when an agent has no local log destination.
type ShipperOptions ¶ added in v0.1.63
ShipperOptions bounds memory and transport work for a log source.