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
- Variables
- func Fingerprint(service, groupKey, typ, message, stack string) []byte
- func HexFingerprint(fingerprint []byte) string
- func IsAudit(record *logspb.LogRecord) bool
- func IsException(record *logspb.LogRecord) bool
- func Normalize(message string) string
- func ParseFingerprint(text string) ([]byte, bool)
- type API
- func (a API) ErrorFacets(ctx context.Context, req *consolev1.ErrorFacetsRequest) (*consolev1.ErrorFacetsResponse, error)
- func (a API) ErrorHistogram(ctx context.Context, req *consolev1.ErrorHistogramRequest) (*consolev1.ErrorHistogramResponse, error)
- func (a API) ErrorInfo(context.Context, *consolev1.ErrorInfoRequest) (*consolev1.ErrorInfoResponse, error)
- func (a API) GetError(ctx context.Context, req *consolev1.GetErrorRequest) (*consolev1.GetErrorResponse, error)
- func (a API) GetErrorGroup(ctx context.Context, req *consolev1.GetErrorGroupRequest) (*consolev1.GetErrorGroupResponse, error)
- func (a API) RelatedLogs(ctx context.Context, req *consolev1.RelatedLogsRequest) (*consolev1.RelatedLogsResponse, error)
- func (a API) SearchErrorGroups(ctx context.Context, req *consolev1.SearchErrorGroupsRequest) (*consolev1.SearchErrorGroupsResponse, error)
- func (a API) SearchErrors(ctx context.Context, req *consolev1.SearchErrorsRequest) (*consolev1.SearchErrorsResponse, error)
- func (a API) SetErrorGroupState(ctx context.Context, req *consolev1.SetErrorGroupStateRequest) (*consolev1.SetErrorGroupStateResponse, error)
- type Limits
- type Option
- type Record
- type Related
- type Service
- func (s *Service) Count(ctx context.Context, outcome string, n int64)
- func (s *Service) ErrorService() (API, error)
- func (s *Service) Expire(ctx context.Context, cutoff time.Time) error
- func (s *Service) Limits() Limits
- func (s *Service) Ready() bool
- func (s *Service) Register(r grpc.ServiceRegistrar)
- func (s *Service) Save(ctx context.Context, records []Record) (int64, int64, error)
- type Settings
- type Upstream
Constants ¶
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" // AttrTenant is the resource attribute naming the tenant (an // installation, a customer) a record was received for: a gateway in // front of an upstream installation sets it. AttrTenant = "tenant.id" )
Attributes of an error record: the OTel exception conventions, the browser SDK's app.debug.* and backplane's own.
const ( OriginSDK = "sdk" OriginOTelLog = "otel_log" IngestProxy = "proxy" IngestTrusted = "trusted" )
Origins and ingests of a record.
const ( DefaultRetention = 90 * 24 * time.Hour DefaultBurstPerMinute = 60 DefaultBurstPerDay = 2000 )
Defaults of the settings.
const ( StateOpen = "open" StateResolved = "resolved" StateMuted = "muted" )
States of a group as stored.
const DefaultAuthor = "admin"
DefaultAuthor acts when no console session made the call.
Variables ¶
var DefaultLimits = Limits{MaxRecord: defaultMaxRecord, MaxStack: defaultMaxStack, MaxField: defaultMaxField}
DefaultLimits of a stored record.
Functions ¶
func Fingerprint ¶
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 ¶
HexFingerprint is a fingerprint as the API shows it.
func IsException ¶
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 ParseFingerprint ¶
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 ¶
func (a API) ErrorFacets( ctx context.Context, req *consolev1.ErrorFacetsRequest, ) (*consolev1.ErrorFacetsResponse, error)
ErrorFacets implements ErrorService.
func (API) ErrorHistogram ¶
func (a API) ErrorHistogram( ctx context.Context, req *consolev1.ErrorHistogramRequest, ) (*consolev1.ErrorHistogramResponse, error)
ErrorHistogram implements ErrorService.
func (API) ErrorInfo ¶
func (a API) ErrorInfo(context.Context, *consolev1.ErrorInfoRequest) (*consolev1.ErrorInfoResponse, error)
ErrorInfo implements ErrorService.
func (API) GetError ¶
func (a API) GetError(ctx context.Context, req *consolev1.GetErrorRequest) (*consolev1.GetErrorResponse, error)
GetError implements ErrorService: one occurrence in full.
func (API) GetErrorGroup ¶
func (a API) GetErrorGroup( ctx context.Context, req *consolev1.GetErrorGroupRequest, ) (*consolev1.GetErrorGroupResponse, error)
GetErrorGroup implements ErrorService: the group over the range with its trend.
func (API) RelatedLogs ¶
func (a API) RelatedLogs( ctx context.Context, req *consolev1.RelatedLogsRequest, ) (*consolev1.RelatedLogsResponse, error)
RelatedLogs implements ErrorService: through the telemetry stores.
func (API) SearchErrorGroups ¶
func (a API) SearchErrorGroups( ctx context.Context, req *consolev1.SearchErrorGroupsRequest, ) (*consolev1.SearchErrorGroupsResponse, error)
SearchErrorGroups implements ErrorService.
func (API) SearchErrors ¶
func (a API) SearchErrors( ctx context.Context, req *consolev1.SearchErrorsRequest, ) (*consolev1.SearchErrorsResponse, error)
SearchErrors implements ErrorService: occurrences newest first, keyset paged.
func (API) SetErrorGroupState ¶
func (a API) SetErrorGroupState( ctx context.Context, req *consolev1.SetErrorGroupStateRequest, ) (*consolev1.SetErrorGroupStateResponse, error)
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 ¶
WithAuthor names who changes a group's state from the request's context (the console session); without it DefaultAuthor.
func WithRelated ¶
WithRelated installs the reader of related logs and traces (the telemetry stores); without one RelatedLogs says unavailable.
func WithUpstream ¶ added in v0.6.83
WithUpstream installs the forwarder of accepted records; without one nothing leaves the installation.
type Record ¶
type Record struct {
Insert db.InsertErrorParams
Touch db.TouchErrorGroupParams
Burst db.TouchErrorBurstParams
// Source is the record as received, for the upstream.
Source upstream.Record
}
Record is one exception record as the store takes it: the occurrence's row, its group's touch and its tenant's burst windows in the group.
type Related ¶
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 ¶
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) ErrorService ¶
ErrorService is the console's ErrorService.
func (*Service) Expire ¶
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) Register ¶
func (s *Service) Register(r grpc.ServiceRegistrar)
Register registers ErrorService on r.
type Settings ¶
type Settings struct {
// Retention of occurrences; 0 keeps them for ever.
Retention time.Duration `json:"retention" schemapb:"default=2160h;gte=0"`
// Upstream forwards accepted records to the vendor's backplane.
Upstream upstream.Settings `json:"upstream"`
// 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_*.
Directories
¶
| Path | Synopsis |
|---|---|
|
Package upstream forwards the exception records an installation accepted to a configured OTLP/HTTP logs endpoint: typically a service of the installation, reached over the mesh's mutual TLS, that passes them on to the vendor (where errors group across installations by tenant.id).
|
Package upstream forwards the exception records an installation accepted to a configured OTLP/HTTP logs endpoint: typically a service of the installation, reached over the mesh's mutual TLS, that passes them on to the vendor (where errors group across installations by tenant.id). |