obs

package
v0.14.4-dev.19 Latest Latest
Warning

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

Go to latest
Published: Nov 21, 2026 License: MIT Imports: 32 Imported by: 0

Documentation

Overview

Package obs records bounded, redacted events without opening runtime state on the launch path. Storage and process spooling implement Sink separately.

Index

Constants

View Source
const MaxEventBytes = 32 << 10
View Source
const MaxSpoolBytes = 16 << 20
View Source
const TracePageSize = 16

Variables

View Source
var ErrIssueNotFound = errors.New("diagnostic issue not found")

Functions

func CompareEvents

func CompareEvents(a, b Event) int

CompareEvents uses the persisted timestamp precision and stable identities across spool ingestion.

func CredentialKey

func CredentialKey(key string) bool

func CredentialShaped

func CredentialShaped(value string) bool

CredentialShaped is shared with Library capture; keep one credential policy.

func Fingerprint

func Fingerprint(event Event) string

func Go

func Go(name string, run func())

func ProcessTrace

func ProcessTrace(ctx context.Context) context.Context

func Redact

func Redact(value any) any

Redact accepts JSON-shaped attributes. Unknown types are omitted rather than invoking arbitrary String/MarshalJSON methods that might reveal credentials.

func SetDefault

func SetDefault(sink Sink, metadata Metadata) func()

SetDefault binds process-owned background work; request events keep their context.

func TraceCursor

func TraceCursor(event Event) string

func TraceParent

func TraceParent(ctx context.Context) string

func WithRecording

func WithRecording(ctx, source context.Context) context.Context

WithRecording keeps request cancellation and tracing while inheriting a process sink.

func WithSink

func WithSink(ctx context.Context, sink Sink, metadata Metadata) context.Context

func WithTrace

func WithTrace(ctx context.Context, header string) context.Context

Types

type DiagnosticRows

type DiagnosticRows struct {
	Nodes         []map[string]any `json:"mesh_nodes"`
	Sessions      []map[string]any `json:"sessions"`
	MissingTables []string         `json:"unavailable_tables,omitempty"`
}

func RelatedRows

func RelatedRows(ctx context.Context, home string, nodes, sessions []string) (DiagnosticRows, error)

RelatedRows reads only the involved session and mesh-node records, never credentials.

type Event

type Event struct {
	TS          time.Time      `json:"ts"`
	DurationUS  int64          `json:"duration_us"`
	TraceID     string         `json:"trace_id"`
	SpanID      string         `json:"span_id"`
	NodeID      string         `json:"node_id"`
	Proc        string         `json:"proc"`
	Kind        string         `json:"kind"`
	Name        string         `json:"name"`
	Level       string         `json:"level"`
	ErrorTrace  bool           `json:"error_trace,omitempty"`
	Status      int            `json:"status"`
	SessionID   string         `json:"session_id,omitempty"`
	User        string         `json:"user,omitempty"`
	Fingerprint string         `json:"fingerprint,omitempty"`
	Stack       string         `json:"stack,omitempty"`
	Attrs       map[string]any `json:"attrs"`
	// contains filtered or unexported fields
}

func From

func From(ctx context.Context) *Event

func IssueEvents

func IssueEvents(ctx context.Context, home, fingerprint string) ([]Event, error)

IssueEvents includes the complete retained traces containing this issue.

func ParseTraceCursor

func ParseTraceCursor(trace, cursor string) (Event, error)

func Query

func Query(ctx context.Context, home string, filter Filter) ([]Event, error)

Query reads retained day files and unconsumed spool lines without starting a writer.

func Start

func Start(ctx context.Context, kind, name string) (context.Context, *Event)

func TraceEvents

func TraceEvents(ctx context.Context, home, trace string) ([]Event, error)

func (*Event) End

func (e *Event) End()

func (*Event) Fail

func (e *Event) Fail(err error)

func (Event) Sanitized

func (e Event) Sanitized() Event

Sanitized is also used at spool and browser ingestion boundaries.

func (*Event) Set

func (e *Event) Set(key string, value any)

func (*Event) TraceParent

func (e *Event) TraceParent() string

type Filter

type Filter struct {
	Since                                                time.Time
	Kind, Level, Session, Node, Trace, Fingerprint, Grep string
	Limit                                                int
	// contains filtered or unexported fields
}

type Issue

type Issue struct {
	Fingerprint     string       `json:"fingerprint"`
	Kind            string       `json:"kind"`
	Title           string       `json:"title"`
	Status          string       `json:"status"`
	Regressed       bool         `json:"regressed"`
	FirstSeen       time.Time    `json:"first_seen"`
	LastSeen        time.Time    `json:"last_seen"`
	Count           int64        `json:"count"`
	ResolvedAt      time.Time    `json:"resolved_at,omitzero"`
	ResolvedBy      string       `json:"resolved_by,omitempty"`
	ResolvedVersion string       `json:"resolved_version,omitempty"`
	Note            string       `json:"note,omitempty"`
	Counts          []IssueCount `json:"counts"`
	Sample          *Event       `json:"sample,omitempty"`
	RecentTraces    []string     `json:"recent_traces,omitempty"`
}

func ChangeIssue

func ChangeIssue(ctx context.Context, home, fingerprint, status, version, note, who string) (Issue, error)

func GetIssue

func GetIssue(ctx context.Context, home, fingerprint string) (Issue, error)

func ListIssues

func ListIssues(ctx context.Context, home, status string) ([]Issue, error)

type IssueCount

type IssueCount struct {
	Node        string    `json:"node_id"`
	Count       int64     `json:"count"`
	FirstSeen   time.Time `json:"first_seen"`
	LastSeen    time.Time `json:"last_seen"`
	LastVersion string    `json:"last_version"`
	LastTrace   string    `json:"last_trace"`
}

type Metadata

type Metadata struct{ Version, Commit, NodeID, Proc string }

func BuildMetadata

func BuildMetadata(version, node, proc string) Metadata

type Queue

type Queue struct {
	Events  chan Event
	Dropped atomic.Uint64
}

func NewQueue

func NewQueue() *Queue

func (*Queue) Write

func (q *Queue) Write(event Event)

type Sink

type Sink interface{ Write(Event) }

Write must return immediately. A slow consumer drops at its bounded queue.

type Spool

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

func OpenSpool

func OpenSpool(home string, options SpoolOptions) (*Spool, error)

OpenSpool stays filesystem-free until the first event, including on Close.

func (*Spool) Close

func (s *Spool) Close() error

func (*Spool) Dropped

func (s *Spool) Dropped() uint64

func (*Spool) Write

func (s *Spool) Write(event Event)

type SpoolOptions

type SpoolOptions struct {
	Proc string
	Now  func() time.Time
}

type SpoolStats

type SpoolStats struct {
	Files, Events, Malformed, DroppedFiles int
	DroppedBytes                           int64
}

type Store

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

func Open

func Open(home string, options StoreOptions) (*Store, error)

func (*Store) Close

func (s *Store) Close() error

func (*Store) Dropped

func (s *Store) Dropped() uint64

func (*Store) Flush

func (s *Store) Flush(ctx context.Context) error

func (*Store) ForwardErrors

func (s *Store) ForwardErrors(ctx context.Context, main string, send func(context.Context, []Event) error) error

ForwardErrors sends bounded batches from retained days, acknowledging only committed uploads.

func (*Store) Import

func (s *Store) Import(ctx context.Context, events []Event) error

Import applies backpressure to bulk ingestion; live event producers use Write.

func (*Store) IngestSpool

func (s *Store) IngestSpool(ctx context.Context) (SpoolStats, error)

func (*Store) Write

func (s *Store) Write(event Event)

type StoreOptions

type StoreOptions struct {
	Metadata      Metadata
	State         *state.Store
	Now           func() time.Time
	FlushInterval time.Duration
	SweepInterval time.Duration
	MaxDayBytes   int64
}

type Trace

type Trace struct{ ID, Span string }

func NewTrace

func NewTrace() Trace

func ParseTraceParent

func ParseTraceParent(value string) Trace

ParseTraceParent starts a fresh trace for malformed or all-zero identifiers.

func (Trace) TraceParent

func (t Trace) TraceParent() string

type TracePage

type TracePage struct {
	Events     []Event `json:"events"`
	NextCursor string  `json:"next_cursor,omitempty"`
}

func ReadTracePage

func ReadTracePage(ctx context.Context, home, trace, cursor string) (TracePage, error)

ReadTracePage reads a bounded page without loading the complete retained trace.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL