logging

Documentation

Overview

Package logging projects Spice Agent events into the Spice-native structured logger through one bounded best-effort mailbox. It never treats diagnostic logging as durable history or execution authority.

Index

• Constants
• func NewMailbox(config Config) (*event.BestEffortObserver, error)
• type Config
  • func DefaultConfig() Config
  • func (config Config) Validate() error
• type CorrelationKey
  • func NewCorrelationKey(material []byte) (CorrelationKey, error)
  • func (key CorrelationKey) Format(state fmt.State, _ rune)
• type HealthSource
  • func NewHealthSource(config Config, processor *Processor) *HealthSource
  • func (source *HealthSource) HealthContribution() daemon.HealthContribution
• type Processor
  • func NewProcessor(config Config, mailbox *event.BestEffortObserver, logger *spicelogging.Logger) (*Processor, lifecycle.Cleanup, error)
  • func (processor *Processor) Close(ctx context.Context) error
  • func (processor *Processor) Snapshot() Snapshot
• type Snapshot
  • func (snapshot Snapshot) Closed() bool
  • func (snapshot Snapshot) DecodeFailures() uint64
  • func (snapshot Snapshot) Filtered() uint64
  • func (snapshot Snapshot) Handled() uint64
  • func (snapshot Snapshot) LogFailures() uint64
  • func (snapshot Snapshot) OverflowDropped() uint64
  • func (snapshot Snapshot) Processed() uint64

Constants

const ContractVersion = "spice.agent.logging/v1"

ContractVersion identifies the safe Agent event projection.

Functions

func NewMailbox

func NewMailbox(config Config) (*event.BestEffortObserver, error)

NewMailbox constructs the sole queue used by Agent logging. Model deltas are always filtered; tool progress is admitted only by explicit configuration.

Types

type Config

type Config struct {
	MailboxCapacity int
	IncludeProgress bool
	ReadinessImpact bool
	CorrelationKey  CorrelationKey
}

Config owns the bounded Agent logging mailbox and optional readiness impact. A zero CorrelationKey requests fresh process-local random key material.

func DefaultConfig

func DefaultConfig() Config

DefaultConfig returns conservative secret-safe production defaults.

func (Config) Validate

func (config Config) Validate() error

Validate rejects ambiguous or unbounded configuration.

type CorrelationKey

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

CorrelationKey is immutable HMAC material with no material accessor.

func NewCorrelationKey

func NewCorrelationKey(material []byte) (CorrelationKey, error)

NewCorrelationKey defensively copies exact 256-bit application-owned key material. Callers must treat the input as secret configuration.

func (CorrelationKey) Format

func (key CorrelationKey) Format(state fmt.State, _ rune)

Format redacts key material under every fmt verb.

type HealthSource

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

HealthSource is an optional passive fixed-code readiness contribution.

func NewHealthSource

func NewHealthSource(config Config, processor *Processor) *HealthSource

NewHealthSource constructs an in-memory-only health adapter.

func (*HealthSource) HealthContribution

func (source *HealthSource) HealthContribution() daemon.HealthContribution

HealthContribution never exposes handler errors or event payload text.

type Processor

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

Processor owns exactly one consumer for one Agent logging mailbox.

func NewProcessor

func NewProcessor(
	config Config,
	mailbox *event.BestEffortObserver,
	logger *spicelogging.Logger,
) (*Processor, lifecycle.Cleanup, error)

NewProcessor starts one lifecycle-owned consumer. Logger failures remain diagnostic accounting and never become Agent execution failures.

func (*Processor) Close

func (processor *Processor) Close(ctx context.Context) error

Close closes the mailbox after producers stop and waits for every accepted envelope to drain. Cancellation ends the wait without claiming completion.

func (*Processor) Snapshot

func (processor *Processor) Snapshot() Snapshot

Snapshot returns exact race-safe accounting. Expected filtering and capacity overflow are kept separate.

type Snapshot

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

Snapshot is one immutable accounting and health view.

func (Snapshot) Closed

func (snapshot Snapshot) Closed() bool

func (Snapshot) DecodeFailures

func (snapshot Snapshot) DecodeFailures() uint64

func (Snapshot) Filtered

func (snapshot Snapshot) Filtered() uint64

func (Snapshot) Handled

func (snapshot Snapshot) Handled() uint64

func (Snapshot) LogFailures

func (snapshot Snapshot) LogFailures() uint64

func (Snapshot) OverflowDropped

func (snapshot Snapshot) OverflowDropped() uint64

func (Snapshot) Processed

func (snapshot Snapshot) Processed() uint64