apperrors

package
v0.6.33 Latest Latest
Warning

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

Go to latest
Published: Oct 22, 2026 License: MIT Imports: 37 Imported by: 0

Documentation

Overview

Package apperrors keeps application errors durably: every exception record the deployment's Collector forwards to backplane's audit/errors listener is stored whole — the exception, the record's attributes, its resource and the browser SDK's envelope (state and history) — grouped by fingerprint, bounded by burst limits and a retention, and served to the console as ErrorService. Related logs and traces are read from the independent telemetry stores when the installation has them.

Index

Constants

View Source
const (
	AttrType       = "exception.type"
	AttrMessage    = "exception.message"
	AttrStacktrace = "exception.stacktrace"
	AttrEventName  = "event.name"
	AttrKind       = "app.debug.kind"
	AttrEventID    = "app.debug.event.id"
	AttrRuntime    = "app.debug.runtime.id"
	AttrMechanism  = "app.debug.exception.mechanism"
	AttrHandled    = "app.debug.exception.handled"
	AttrGroupKey   = "app.debug.group.key"
	AttrIngest     = "backplane.ingest"
	AttrAudit      = "backplane.audit"
)

Attributes of an error record: the OTel exception conventions, the browser SDK's app.debug.* and backplane's own.

View Source
const (
	OriginSDK     = "sdk"
	OriginOTelLog = "otel_log"
	IngestProxy   = "proxy"
	IngestTrusted = "trusted"
)

Origins and ingests of a record.

View Source
const (
	DefaultRetention      = 90 * 24 * time.Hour
	DefaultBurstPerMinute = 60
	DefaultBurstPerDay    = 2000
)

Defaults of the settings.

View Source
const (
	StateOpen     = "open"
	StateResolved = "resolved"
	StateMuted    = "muted"
)

States of a group as stored.

View Source
const DefaultAuthor = "admin"

DefaultAuthor acts when no console session made the call.

Variables

View Source
var DefaultLimits = Limits{MaxRecord: defaultMaxRecord, MaxStack: defaultMaxStack, MaxField: defaultMaxField}

DefaultLimits of a stored record.

Functions

func Fingerprint

func Fingerprint(service, groupKey, typ, message, stack string) []byte

Fingerprint identifies the same exception at the same place: the service and the SDK's group key when it sends one; else the service, the type, the message normalized (numbers, hex ids, uuids and quoted text replaced) and the top frames' functions.

func HexFingerprint

func HexFingerprint(fingerprint []byte) string

HexFingerprint is a fingerprint as the API shows it.

func IsAudit

func IsAudit(record *logspb.LogRecord) bool

IsAudit reports whether the record is marked application audit.

func IsException

func IsException(record *logspb.LogRecord) bool

IsException reports whether the record is an exception: by the OTel conventions (exception.* attributes, event.name=exception) or the browser SDK's app.debug.kind=exception.

func Normalize

func Normalize(message string) string

Normalize replaces what varies between occurrences of one error.

func ParseFingerprint

func ParseFingerprint(text string) ([]byte, bool)

ParseFingerprint reads a fingerprint the API shows.

Types

type API

type API struct {
	consolev1.UnimplementedErrorServiceServer
	// contains filtered or unexported fields
}

API serves ErrorService over the store.

func (API) ErrorFacets

ErrorFacets implements ErrorService.

func (API) ErrorHistogram

ErrorHistogram implements ErrorService.

func (API) ErrorInfo

ErrorInfo implements ErrorService.

func (API) GetError

GetError implements ErrorService: one occurrence in full.

func (API) GetErrorGroup

GetErrorGroup implements ErrorService: the group over the range with its trend.

func (API) RelatedLogs

RelatedLogs implements ErrorService: through the telemetry stores.

func (API) SearchErrorGroups

SearchErrorGroups implements ErrorService.

func (API) SearchErrors

SearchErrors implements ErrorService: occurrences newest first, keyset paged.

func (API) SetErrorGroupState

SetErrorGroupState implements ErrorService: triage, audited.

type Limits

type Limits struct {
	// MaxRecord bounds the record as sent; a bigger one has its stack and
	// body cut and is marked truncated.
	MaxRecord int
	// MaxStack bounds the stack trace kept.
	MaxStack int
	// MaxField bounds the small text fields.
	MaxField int
}

Limits bound what a stored record takes.

type Option

type Option func(*Service)

Option configures New.

func WithAuthor

func WithAuthor(fn func(context.Context) string) Option

WithAuthor names who changes a group's state from the request's context (the console session); without it DefaultAuthor.

func WithRelated

func WithRelated(r Related) Option

WithRelated installs the reader of related logs and traces (the telemetry stores); without one RelatedLogs says unavailable.

type Record

type Record struct {
	Insert db.InsertErrorParams
	Touch  db.TouchErrorGroupParams
}

Record is one exception record as the store takes it: the occurrence's row and its group's touch.

func Records

func Records(req *collogspb.ExportLogsServiceRequest, now time.Time, limits Limits) ([]Record, int64)

Records are the exception records of the batch as the store takes them, and how many were rejected (invalid text, no resource). Records marked audit are not errors.

type Related interface {
	// Available: a log store is configured.
	Available() bool
	// Logs related to the occurrence, by the request's relation and range
	// (absent: a window around when).
	Logs(ctx context.Context, req *consolev1.RelatedLogsRequest, o *consolev1.ErrorOccurrence, when time.Time,
	) (*consolev1.RelatedLogsResponse, error)
}

Related reads what the telemetry stores hold around an occurrence.

type Service

type Service struct {
	deps.Component
	// contains filtered or unexported fields
}

Service keeps errors: the store's writer and the console's ErrorService.

func New

func New(parent deps.Scope, st deps.Dependency[*store.Store], settings Settings, opts ...Option) *Service

New creates the service under parent, over st.

func (*Service) Count

func (s *Service) Count(ctx context.Context, outcome string, n int64)

Count counts rejected records (the ingest's).

func (*Service) ErrorService

func (s *Service) ErrorService() (API, error)

ErrorService is the console's ErrorService.

func (*Service) Expire

func (s *Service) Expire(ctx context.Context, cutoff time.Time) error

Expire deletes the occurrences before cutoff, a batch at a time until none is left, then the groups without occurrences last seen before it.

func (*Service) Limits

func (s *Service) Limits() Limits

Limits of a stored record.

func (*Service) Ready

func (s *Service) Ready() bool

Ready reports whether records can be stored.

func (*Service) Register

func (s *Service) Register(r grpc.ServiceRegistrar)

Register registers ErrorService on r.

func (*Service) Save

func (s *Service) Save(ctx context.Context, records []Record) (int64, int64, error)

Save stores the records: each touches its group and is stored while the group's burst windows allow; a retried record (same key) is stored once. Returns how many were stored and how many only counted.

type Settings

type Settings struct {
	// Retention of occurrences; 0 keeps them for ever.
	Retention time.Duration `json:"retention" schemapb:"default=2160h;gte=0"`
	// BurstPerMinute and BurstPerDay bound the occurrences stored per group
	// (one fingerprint in one service) in a minute and in a day; past them
	// the group only counts.
	BurstPerMinute int64 `json:"burst_per_minute" schemapb:"default=60;gte=1"`
	BurstPerDay    int64 `json:"burst_per_day"    schemapb:"default=2000;gte=1"`
	// MaxRecordBytes bounds a stored record; a bigger one has its stack and
	// envelope cut and is marked truncated.
	MaxRecordBytes int64 `json:"max_record_bytes" schemapb:"default=524288;gte=4096"`
}

Settings are deployment-only: BACKPLANE_ERRORS_*.

Jump to

Keyboard shortcuts

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