observability

Documentation

Overview

Package observability records handler events, audits and basic runtime metrics.

Index

• Constants
• Variables
• func AppendAudit(audits AuditLogStore, actor, action, target string, metadata map[string]any)
• func Middleware(eventLogs EventLogStore, metrics MetricsStore) middleware.Middleware
• type AuditDispatcher
  • func NewAuditDispatcher(store AuditLogStore, queueSize int, timeout time.Duration) (*AuditDispatcher, error)
  • func (d *AuditDispatcher) Append(entry AuditLogEntry) error
  • func (d *AuditDispatcher) Close(ctx context.Context) error
  • func (d *AuditDispatcher) Stats() AuditDispatcherStats
• type AuditDispatcherStats
• type AuditLogEntry
• type AuditLogQuery
• type AuditLogStore
• type EventLogEntry
• type EventLogQuery
• type EventLogStore
• type InMemory
  • func NewInMemory(capacity int) *InMemory
  • func (m *InMemory) AppendAudit(ctx context.Context, entry AuditLogEntry) error
  • func (m *InMemory) AppendEvent(ctx context.Context, entry EventLogEntry) error
  • func (m *InMemory) ListAudit(ctx context.Context, query AuditLogQuery) ([]AuditLogEntry, error)
  • func (m *InMemory) ListEvents(ctx context.Context, query EventLogQuery) ([]EventLogEntry, error)
  • func (m *InMemory) Observe(duration time.Duration, hasError bool, at time.Time)
  • func (m *InMemory) Snapshot(ctx context.Context) (MetricsSnapshot, error)
• type MetricsSnapshot
• type MetricsStore
• type Postgres
  • func NewPostgres(pool *pgxpool.Pool) *Postgres
  • func (p *Postgres) AppendAudit(ctx context.Context, entry AuditLogEntry) error
  • func (p *Postgres) AppendEvent(ctx context.Context, entry EventLogEntry) error
  • func (p *Postgres) EnsureSchema(ctx context.Context) error
  • func (p *Postgres) ListAudit(ctx context.Context, query AuditLogQuery) ([]AuditLogEntry, error)
  • func (p *Postgres) ListEvents(ctx context.Context, query EventLogQuery) ([]EventLogEntry, error)
  • func (p *Postgres) Observe(duration time.Duration, hasError bool, at time.Time)
  • func (p *Postgres) Snapshot(ctx context.Context) (MetricsSnapshot, error)

Constants

const (
	DefaultAuditQueueSize = 256
	DefaultAuditTimeout   = 2 * time.Second
)

Variables

var (
	ErrAuditDropped = errors.New("audit event dropped")
	ErrInvalidAudit = errors.New("invalid audit event")
)

Functions

func AppendAudit

func AppendAudit(audits AuditLogStore, actor, action, target string, metadata map[string]any)

func Middleware

func Middleware(eventLogs EventLogStore, metrics MetricsStore) middleware.Middleware

Types

type AuditDispatcher

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

AuditDispatcher keeps audit persistence outside mutation and Control paths. Its queue and store calls are bounded; audit remains non-authoritative.

func NewAuditDispatcher

func NewAuditDispatcher(store AuditLogStore, queueSize int, timeout time.Duration) (*AuditDispatcher, error)

func (*AuditDispatcher) Append

func (d *AuditDispatcher) Append(entry AuditLogEntry) error

func (*AuditDispatcher) Close

func (d *AuditDispatcher) Close(ctx context.Context) error

func (*AuditDispatcher) Stats

func (d *AuditDispatcher) Stats() AuditDispatcherStats

type AuditDispatcherStats

type AuditDispatcherStats struct {
	Dropped  uint64
	Failed   uint64
	Rejected uint64
}

type AuditLogEntry

type AuditLogEntry struct {
	Actor     string         `json:"actor"`
	Action    string         `json:"action"`
	Target    string         `json:"target"`
	Metadata  map[string]any `json:"metadata,omitempty"`
	CreatedAt time.Time      `json:"created_at"`
}

type AuditLogQuery

type AuditLogQuery struct {
	Limit  int
	Offset int
	Actor  string
	Action string
	Target string
}

type AuditLogStore

type AuditLogStore interface {
	AppendAudit(ctx context.Context, entry AuditLogEntry) error
	ListAudit(ctx context.Context, query AuditLogQuery) ([]AuditLogEntry, error)
}

type EventLogEntry

type EventLogEntry struct {
	ID         string    `json:"id"`
	Platform   string    `json:"platform"`
	Type       string    `json:"type"`
	ChatID     string    `json:"chat_id"`
	UserID     string    `json:"user_id"`
	Text       string    `json:"text,omitempty"`
	Command    string    `json:"command,omitempty"`
	Payload    string    `json:"payload,omitempty"`
	Error      string    `json:"error,omitempty"`
	DurationMS int64     `json:"duration_ms"`
	CreatedAt  time.Time `json:"created_at"`
}

type EventLogQuery

type EventLogQuery struct {
	Limit    int
	Offset   int
	Platform string
	Type     string
	UserID   string
	ChatID   string
	HasError *bool
}

type EventLogStore

type EventLogStore interface {
	AppendEvent(ctx context.Context, entry EventLogEntry) error
	ListEvents(ctx context.Context, query EventLogQuery) ([]EventLogEntry, error)
}

type InMemory

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

func NewInMemory

func NewInMemory(capacity int) *InMemory

func (*InMemory) AppendAudit

func (m *InMemory) AppendAudit(ctx context.Context, entry AuditLogEntry) error

func (*InMemory) AppendEvent

func (m *InMemory) AppendEvent(ctx context.Context, entry EventLogEntry) error

func (*InMemory) ListAudit

func (m *InMemory) ListAudit(ctx context.Context, query AuditLogQuery) ([]AuditLogEntry, error)

func (*InMemory) ListEvents

func (m *InMemory) ListEvents(ctx context.Context, query EventLogQuery) ([]EventLogEntry, error)

func (*InMemory) Observe

func (m *InMemory) Observe(duration time.Duration, hasError bool, at time.Time)

func (*InMemory) Snapshot

func (m *InMemory) Snapshot(ctx context.Context) (MetricsSnapshot, error)

type MetricsSnapshot

type MetricsSnapshot struct {
	EventsTotal      int64     `json:"events_total"`
	ErrorsTotal      int64     `json:"errors_total"`
	AverageLatencyMS int64     `json:"average_latency_ms"`
	LastEventAt      time.Time `json:"last_event_at"`
}

type MetricsStore

type MetricsStore interface {
	Observe(duration time.Duration, hasError bool, at time.Time)
	Snapshot(ctx context.Context) (MetricsSnapshot, error)
}

type Postgres

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

func NewPostgres

func NewPostgres(pool *pgxpool.Pool) *Postgres

func (*Postgres) AppendAudit

func (p *Postgres) AppendAudit(ctx context.Context, entry AuditLogEntry) error

func (*Postgres) AppendEvent

func (p *Postgres) AppendEvent(ctx context.Context, entry EventLogEntry) error

func (*Postgres) EnsureSchema

func (p *Postgres) EnsureSchema(ctx context.Context) error

func (*Postgres) ListAudit

func (p *Postgres) ListAudit(ctx context.Context, query AuditLogQuery) ([]AuditLogEntry, error)

func (*Postgres) ListEvents

func (p *Postgres) ListEvents(ctx context.Context, query EventLogQuery) ([]EventLogEntry, error)

func (*Postgres) Observe

func (p *Postgres) Observe(duration time.Duration, hasError bool, at time.Time)

func (*Postgres) Snapshot

func (p *Postgres) Snapshot(ctx context.Context) (MetricsSnapshot, error)