observability

package
v0.5.1 Latest Latest
Warning

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

 Go to latest Published: Jul 19, 2026 License: MIT Imports: 19 Imported by: 0

Documentation

Index

Constants

This section is empty.

Variables

View Source 
var (
	ErrInvalidMutationOutcome = errors.New("invalid security audit mutation outcome")
	ErrSecurityAuditNotFound  = errors.New("security audit journal record not found")
	ErrSecurityAuditCompleted = errors.New("security audit mutation is already completed")
	ErrSecurityAuditCapacity  = errors.New("security audit journal capacity exhausted")
)
View Source 
var (
	ErrInvalidEvent              = errors.New("plugin observability event is invalid")
	ErrInvalidAuditDetails       = errors.New("plugin audit details are invalid")
	ErrInvalidDiagnosticSeverity = errors.New("plugin diagnostic severity is invalid")
	ErrInvalidDiagnosticMessage  = errors.New("plugin diagnostic message is invalid")
	ErrInvalidDiagnosticDetails  = errors.New("plugin diagnostic details are invalid")
	ErrInvalidDiagnosticFailure  = errors.New("plugin diagnostic failure is invalid")
	ErrDiagnosticScopeRequired   = errors.New("complete diagnostic owner scope is required")
)

Functions

func ValidateAuditEvent added in v0.5.0 

func ValidateAuditEvent(event AuditEvent) error

func ValidateDiagnosticEvent added in v0.5.0 

func ValidateDiagnosticEvent(event DiagnosticEvent) error

Types

type AuditEvent 

type AuditEvent struct {
	EventID           string         `json:"event_id,omitempty"`
	Type              string         `json:"type"`
	PluginID          string         `json:"plugin_id"`
	PluginInstanceID  string         `json:"plugin_instance_id,omitempty"`
	SurfaceID         string         `json:"surface_id,omitempty"`
	SurfaceInstanceID string         `json:"surface_instance_id,omitempty"`
	RequestID         string         `json:"request_id,omitempty"`
	Actor             string         `json:"actor,omitempty"`
	OccurredAt        time.Time      `json:"occurred_at,omitempty"`
	Details           map[string]any `json:"details,omitempty"`
}

type AuditSink 

type AuditSink interface {
	AppendPluginAudit(ctx context.Context, event AuditEvent) error
}

type DiagnosticDetails added in v0.5.0 

type DiagnosticDetails struct {
	OperationsDeleted         int64                     `json:"operations_deleted,omitempty"`
	StreamsDeleted            int64                     `json:"streams_deleted,omitempty"`
	InvocationID              string                    `json:"invocation_id,omitempty"`
	Method                    string                    `json:"method,omitempty"`
	FailureCode               string                    `json:"failure_code,omitempty"`
	RuntimeProcessFailureCode RuntimeProcessFailureCode `json:"runtime_process_failure_code,omitempty"`
	OperationID               string                    `json:"operation_id,omitempty"`
	StreamID                  string                    `json:"stream_id,omitempty"`
	RuntimeInstanceID         string                    `json:"runtime_instance_id,omitempty"`
	RuntimeGenerationID       string                    `json:"runtime_generation_id,omitempty"`
	RuntimeVersion            string                    `json:"runtime_version,omitempty"`
	RustIPCVersion            string                    `json:"rust_ipc_version,omitempty"`
	WASMABIVersion            string                    `json:"wasm_abi_version,omitempty"`
	RuntimeTargetOS           string                    `json:"runtime_target_os,omitempty"`
	RuntimeTargetArch         string                    `json:"runtime_target_arch,omitempty"`
	RuntimeArtifactSHA256     string                    `json:"runtime_artifact_sha256,omitempty"`
	OS                        string                    `json:"os,omitempty"`
	Arch                      string                    `json:"arch,omitempty"`
	Stream                    string                    `json:"stream,omitempty"`
	PackageHash               string                    `json:"package_hash,omitempty"`
	Artifact                  string                    `json:"artifact,omitempty"`
	PluginInstanceID          string                    `json:"plugin_instance_id,omitempty"`
	StoreID                   string                    `json:"store_id,omitempty"`
	Operation                 string                    `json:"operation,omitempty"`
	Hostcall                  string                    `json:"hostcall,omitempty"`
	Code                      string                    `json:"code,omitempty"`
	ConnectorID               string                    `json:"connector_id,omitempty"`
	Transport                 string                    `json:"transport,omitempty"`
	RevokeEpoch               uint64                    `json:"revoke_epoch,omitempty"`
	StageID                   string                    `json:"stage_id,omitempty"`
	Reason                    string                    `json:"reason,omitempty"`
	SurfaceInstanceID         string                    `json:"surface_instance_id,omitempty"`
}

func (DiagnosticDetails) Valid added in v0.5.0 

func (details DiagnosticDetails) Valid() bool

type DiagnosticEvent 

type DiagnosticEvent struct {
	EventID              string             `json:"event_id,omitempty"`
	Type                 string             `json:"type"`
	Severity             DiagnosticSeverity `json:"severity"`
	Message              string             `json:"message"`
	PluginID             string             `json:"plugin_id,omitempty"`
	PluginInstanceID     string             `json:"plugin_instance_id,omitempty"`
	SurfaceID            string             `json:"surface_id,omitempty"`
	SurfaceInstanceID    string             `json:"surface_instance_id,omitempty"`
	ActiveFingerprint    string             `json:"active_fingerprint,omitempty"`
	RequestID            string             `json:"request_id,omitempty"`
	CorrelationID        string             `json:"correlation_id,omitempty"`
	MutationOutcome      mutation.Outcome   `json:"mutation_outcome,omitempty"`
	OwnerSessionHash     string             `json:"-"`
	OwnerUserHash        string             `json:"-"`
	OwnerEnvHash         string             `json:"-"`
	SessionChannelIDHash string             `json:"-"`
	OccurredAt           time.Time          `json:"occurred_at,omitempty"`
	Details              DiagnosticDetails  `json:"details,omitempty"`
	Failure              Failure            `json:"-"`
}

type DiagnosticLister 

type DiagnosticLister interface {
	ListPluginDiagnostics(ctx context.Context, req ListDiagnosticRequest) ([]DiagnosticEvent, error)
}

type DiagnosticSeverity added in v0.5.0 

type DiagnosticSeverity string
const (
	DiagnosticSeverityInfo    DiagnosticSeverity = "info"
	DiagnosticSeverityWarning DiagnosticSeverity = "warning"
)

func (DiagnosticSeverity) Valid added in v0.5.0 

func (severity DiagnosticSeverity) Valid() bool

type DiagnosticsSink 

type DiagnosticsSink interface {
	AppendPluginDiagnostic(ctx context.Context, event DiagnosticEvent) error
}

type Failure added in v0.5.0 

type Failure struct {
	Code      FailureCode      `json:"code"`
	Component FailureComponent `json:"component"`
	Operation FailureOperation `json:"operation"`
}

Failure is a stable diagnostic description that intentionally excludes the underlying error text. It is safe to persist at adapter and action boundaries.

func FailureFromError added in v0.5.0 

func FailureFromError(code FailureCode, component FailureComponent, operation FailureOperation, cause error) Failure

func (Failure) Empty added in v0.5.0 

func (f Failure) Empty() bool

func (Failure) Error added in v0.5.0 

func (f Failure) Error() string

func (Failure) Valid added in v0.5.0 

func (f Failure) Valid() bool

type FailureCode added in v0.5.0 

type FailureCode string
const (
	FailureAdapter FailureCode = "adapter_failure"
	FailureOwner   FailureCode = "owner_failure"
	FailureScope   FailureCode = "scope_failure"
	FailureAction  FailureCode = "action_failure"
)

func (FailureCode) Valid added in v0.5.0 

func (code FailureCode) Valid() bool

type FailureComponent added in v0.5.0 

type FailureComponent string
const (
	FailureComponentExecution FailureComponent = "execution"
	FailureComponentHTTP      FailureComponent = "http"
	FailureComponentLifecycle FailureComponent = "lifecycle"
	FailureComponentRuntime   FailureComponent = "runtime"
	FailureComponentSecrets   FailureComponent = "secrets"
	FailureComponentSecurity  FailureComponent = "security"
)

func (FailureComponent) Valid added in v0.5.0 

func (component FailureComponent) Valid() bool

type FailureOperation added in v0.5.0 

type FailureOperation string
const (
	FailureOperationExecutionRetentionPrune  FailureOperation = "execution.retention_prune"
	FailureOperationExecutionFail            FailureOperation = "execution.fail"
	FailureOperationExecutionDurationPersist FailureOperation = "execution.duration_persist"
	FailureOperationHTTPAdapter              FailureOperation = "http.adapter"
	FailureOperationLifecycle                FailureOperation = "lifecycle.operation"
	FailureOperationRuntimeStop              FailureOperation = "runtime.stop"
	FailureOperationRuntimeRevoke            FailureOperation = "runtime.revoke"
	FailureOperationRuntimeProcessStop       FailureOperation = "runtime.process.stop"
	FailureOperationRuntimeProcessExit       FailureOperation = "runtime.process.exit"
	FailureOperationRuntimeProcessOutput     FailureOperation = "runtime.process.output"
	FailureOperationRuntimeHostcall          FailureOperation = "runtime.hostcall"
	FailureOperationRuntimeIPCInvalidate     FailureOperation = "runtime.ipc.invalidate"
	FailureOperationSecretsAdapter           FailureOperation = "secrets.adapter"
	FailureOperationSecurityEventPersist     FailureOperation = "security_event.persist"
	FailureOperationSecurityMutationComplete FailureOperation = "security_mutation.complete"
	FailureOperationSecurityAuditExport      FailureOperation = "security_audit.export"
	FailureOperationMethodReject             FailureOperation = "method.reject"
)

func (FailureOperation) Valid added in v0.5.0 

func (operation FailureOperation) Valid() bool

type ListDiagnosticRequest 

type ListDiagnosticRequest struct {
	PluginID             string             `json:"plugin_id,omitempty"`
	PluginInstanceID     string             `json:"plugin_instance_id,omitempty"`
	SurfaceInstanceID    string             `json:"surface_instance_id,omitempty"`
	OwnerSessionHash     string             `json:"-"`
	OwnerUserHash        string             `json:"-"`
	OwnerEnvHash         string             `json:"-"`
	SessionChannelIDHash string             `json:"-"`
	Type                 string             `json:"type,omitempty"`
	Severity             DiagnosticSeverity `json:"severity,omitempty"`
	Limit                int                `json:"limit,omitempty"`
}

type MemorySecurityAuditJournal added in v0.5.0 

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

MemorySecurityAuditJournal is a fixed-capacity implementation for tests and in-memory hosts. Capacity pressure only evicts records that were exported; protected records make Begin fail closed. A non-positive MaxEntries uses the platform default and never disables retention limits.

func NewMemorySecurityAuditJournal added in v0.5.0 

func NewMemorySecurityAuditJournal(opts ...MemorySecurityAuditJournalOptions) *MemorySecurityAuditJournal

func (*MemorySecurityAuditJournal) BeginSecurityAudit added in v0.5.0 

func (j *MemorySecurityAuditJournal) BeginSecurityAudit(_ context.Context, event AuditEvent) (SecurityAuditRecord, error)

func (*MemorySecurityAuditJournal) CompleteSecurityAudit added in v0.5.0 

func (j *MemorySecurityAuditJournal) CompleteSecurityAudit(_ context.Context, eventID string, outcome mutation.Outcome, details map[string]any) error

func (*MemorySecurityAuditJournal) ListPendingSecurityAudits added in v0.5.0 

func (j *MemorySecurityAuditJournal) ListPendingSecurityAudits(_ context.Context) ([]SecurityAuditRecord, error)

func (*MemorySecurityAuditJournal) ListUnexportedSecurityAudits added in v0.5.0 

func (j *MemorySecurityAuditJournal) ListUnexportedSecurityAudits(_ context.Context) ([]SecurityAuditRecord, error)

func (*MemorySecurityAuditJournal) MarkSecurityAuditExported added in v0.5.0 

func (j *MemorySecurityAuditJournal) MarkSecurityAuditExported(_ context.Context, eventID string) error

func (*MemorySecurityAuditJournal) ReconcilePendingSecurityAudits added in v0.5.0 

func (j *MemorySecurityAuditJournal) ReconcilePendingSecurityAudits(_ context.Context) error

type MemorySecurityAuditJournalOptions added in v0.5.0 

type MemorySecurityAuditJournalOptions struct {
	Now        func() time.Time
	MaxEntries int
}

type MemoryStore 

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

func NewMemoryStore 

func NewMemoryStore(opts ...MemoryStoreOptions) *MemoryStore

func (*MemoryStore) AppendPluginAudit 

func (s *MemoryStore) AppendPluginAudit(_ context.Context, event AuditEvent) error

func (*MemoryStore) AppendPluginDiagnostic 

func (s *MemoryStore) AppendPluginDiagnostic(_ context.Context, event DiagnosticEvent) error

func (*MemoryStore) BeginSecurityAudit added in v0.5.0 

func (s *MemoryStore) BeginSecurityAudit(ctx context.Context, event AuditEvent) (SecurityAuditRecord, error)

MemoryStore exposes the journal contract as well as the ordinary audit sink, allowing a host configured with one in-memory observability adapter to retain the same mutation semantics as a persistent store.

func (*MemoryStore) CompleteSecurityAudit added in v0.5.0 

func (s *MemoryStore) CompleteSecurityAudit(ctx context.Context, eventID string, outcome mutation.Outcome, details map[string]any) error

func (*MemoryStore) ListPendingSecurityAudits added in v0.5.0 

func (s *MemoryStore) ListPendingSecurityAudits(ctx context.Context) ([]SecurityAuditRecord, error)

func (*MemoryStore) ListPluginDiagnostics 

func (s *MemoryStore) ListPluginDiagnostics(_ context.Context, req ListDiagnosticRequest) ([]DiagnosticEvent, error)

func (*MemoryStore) ListUnexportedSecurityAudits added in v0.5.0 

func (s *MemoryStore) ListUnexportedSecurityAudits(ctx context.Context) ([]SecurityAuditRecord, error)

func (*MemoryStore) MarkSecurityAuditExported added in v0.5.0 

func (s *MemoryStore) MarkSecurityAuditExported(ctx context.Context, eventID string) error

func (*MemoryStore) ReconcilePendingSecurityAudits added in v0.5.0 

func (s *MemoryStore) ReconcilePendingSecurityAudits(ctx context.Context) error

type MemoryStoreOptions 

type MemoryStoreOptions struct {
	Now                 func() time.Time
	MaxAuditEvents      int
	MaxDiagnosticEvents int
}

type RuntimeProcessFailureCode added in v0.5.0 

type RuntimeProcessFailureCode string
const (
	RuntimeProcessFailed                      RuntimeProcessFailureCode = "RUNTIME_PROCESS_FAILED"
	RuntimeProcessExitUnexpected              RuntimeProcessFailureCode = "RUNTIME_PROCESS_EXIT_UNEXPECTED"
	RuntimeProcessExitUnrecognized            RuntimeProcessFailureCode = "RUNTIME_PROCESS_EXIT_UNRECOGNIZED"
	RuntimeProcessSignalled                   RuntimeProcessFailureCode = "RUNTIME_PROCESS_SIGNALLED"
	RuntimeProcessWriterCapacityOverflow      RuntimeProcessFailureCode = "IPC_WRITER_CAPACITY_OVERFLOW"
	RuntimeProcessWriterCapacityLimitExceeded RuntimeProcessFailureCode = "IPC_WRITER_CAPACITY_LIMIT_EXCEEDED"
	RuntimeProcessWriterStartFailed           RuntimeProcessFailureCode = "IPC_WRITER_START_FAILED"
	RuntimeProcessWriterClosed                RuntimeProcessFailureCode = "IPC_WRITER_CLOSED"
	RuntimeProcessWriterBatchSizeOverflow     RuntimeProcessFailureCode = "IPC_WRITER_BATCH_SIZE_OVERFLOW"
	RuntimeProcessWriterWriteFailed           RuntimeProcessFailureCode = "IPC_WRITER_WRITE_FAILED"
	RuntimeProcessWriterFlushFailed           RuntimeProcessFailureCode = "IPC_WRITER_FLUSH_FAILED"
	RuntimeProcessWriterPanicked              RuntimeProcessFailureCode = "IPC_WRITER_PANICKED"
)

func RuntimeProcessFailureCodes added in v0.5.0 

func RuntimeProcessFailureCodes() []RuntimeProcessFailureCode

RuntimeProcessFailureCodes returns an owned copy of the released diagnostic code set.

func (RuntimeProcessFailureCode) Valid added in v0.5.0 

func (code RuntimeProcessFailureCode) Valid() bool

type SQLiteStore 

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

func NewSQLiteStore 

func NewSQLiteStore(ctx context.Context, path string, opts ...MemoryStoreOptions) (*SQLiteStore, error)

func (*SQLiteStore) AppendPluginAudit 

func (s *SQLiteStore) AppendPluginAudit(ctx context.Context, event AuditEvent) error

func (*SQLiteStore) AppendPluginDiagnostic 

func (s *SQLiteStore) AppendPluginDiagnostic(ctx context.Context, event DiagnosticEvent) error

func (*SQLiteStore) BeginSecurityAudit added in v0.5.0 

func (s *SQLiteStore) BeginSecurityAudit(ctx context.Context, event AuditEvent) (SecurityAuditRecord, error)

func (*SQLiteStore) Close 

func (s *SQLiteStore) Close() error

func (*SQLiteStore) CompleteSecurityAudit added in v0.5.0 

func (s *SQLiteStore) CompleteSecurityAudit(ctx context.Context, eventID string, outcome mutation.Outcome, details map[string]any) error

func (*SQLiteStore) ListPendingSecurityAudits added in v0.5.0 

func (s *SQLiteStore) ListPendingSecurityAudits(ctx context.Context) ([]SecurityAuditRecord, error)

func (*SQLiteStore) ListPluginDiagnostics 

func (s *SQLiteStore) ListPluginDiagnostics(ctx context.Context, req ListDiagnosticRequest) ([]DiagnosticEvent, error)

func (*SQLiteStore) ListUnexportedSecurityAudits added in v0.5.0 

func (s *SQLiteStore) ListUnexportedSecurityAudits(ctx context.Context) ([]SecurityAuditRecord, error)

func (*SQLiteStore) MarkSecurityAuditExported added in v0.5.0 

func (s *SQLiteStore) MarkSecurityAuditExported(ctx context.Context, eventID string) error

func (*SQLiteStore) ReconcilePendingSecurityAudits added in v0.5.0 

func (s *SQLiteStore) ReconcilePendingSecurityAudits(ctx context.Context) error

type SecurityAuditExporter added in v0.5.0 

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

SecurityAuditExporter delivers complete journal records to a host sink. Marking a record exported happens only after the sink acknowledges it.

func NewSecurityAuditExporter added in v0.5.0 

func NewSecurityAuditExporter(journal SecurityAuditJournal, sink AuditSink) *SecurityAuditExporter

func (*SecurityAuditExporter) Export added in v0.5.0 

func (e *SecurityAuditExporter) Export(ctx context.Context) error

type SecurityAuditJournal added in v0.5.0 

type SecurityAuditJournal interface {
	BeginSecurityAudit(ctx context.Context, event AuditEvent) (SecurityAuditRecord, error)
	CompleteSecurityAudit(ctx context.Context, eventID string, outcome mutation.Outcome, details map[string]any) error
	ListPendingSecurityAudits(ctx context.Context) ([]SecurityAuditRecord, error)
	ListUnexportedSecurityAudits(ctx context.Context) ([]SecurityAuditRecord, error)
	MarkSecurityAuditExported(ctx context.Context, eventID string) error
	ReconcilePendingSecurityAudits(ctx context.Context) error
}

SecurityAuditJournal is the durable boundary for security mutation audit records. Implementations must make Begin and Complete atomic with respect to their own storage and must preserve records when an export fails.

type SecurityAuditRecord added in v0.5.0 

type SecurityAuditRecord struct {
	EventID           string             `json:"event_id"`
	Event             AuditEvent         `json:"event"`
	State             SecurityAuditState `json:"state"`
	Outcome           mutation.Outcome   `json:"mutation_outcome,omitempty"`
	CompletionDetails map[string]any     `json:"completion_details,omitempty"`
	CreatedAt         time.Time          `json:"created_at"`
	CompletedAt       *time.Time         `json:"completed_at,omitempty"`
	ExportedAt        *time.Time         `json:"exported_at,omitempty"`
}

SecurityAuditRecord is an immutable snapshot of a journal record. EventID is stable for the entire lifecycle and is also used for exporter idempotency.

type SecurityAuditState added in v0.5.0 

type SecurityAuditState string

SecurityAuditState describes the durable state of a security mutation audit. Pending records are written before a mutation starts and must never be exported as committed events until CompleteSecurityAudit is durable. 

const (
	SecurityAuditPending   SecurityAuditState = "pending"
	SecurityAuditCompleted SecurityAuditState = "completed"
)

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.