Help us shape the future of Go! Take the 2026 Go Developer Survey

telemetry

package
v1.10.0 Latest Latest
Warning

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

 Go to latest Published: Nov 3, 2026 License: MIT Imports: 10 Imported by: 0

Documentation

Overview

Package telemetry is the tracing and metrics plumbing Chronicle's packages share: the tracer every span comes from, the attribute keys spans carry, how a failed span is marked, and the metric series each component records.

Spans go to the global OpenTelemetry tracer provider, which forge.New installs. Metrics go to a go-utils metrics sink the caller hands in (in a Forge app, app.Metrics()), because forge installs no global MeterProvider and anything recorded through otel.Meter is never exported.

Nothing here ever puts personal data, secrets, payloads or error text on a span or a metric. Attributes are counts, booleans, enum strings and opaque stream IDs. Metric labels are fixed enums.

Index

Constants

View Source 
const (
	MetricEventsRecorded       = "chronicle_events_recorded_total"
	MetricRecordDuration       = "chronicle_record_duration_seconds"
	MetricEventsArchived       = "chronicle_events_archived_total"
	MetricEventsPurged         = "chronicle_events_purged_total"
	MetricCheckpointsAttempted = "chronicle_checkpoints_attempted_total"
	MetricSchedulerRunDuration = "chronicle_scheduler_run_duration_seconds"
)

Metric names as Chronicle registers them. A Forge app exports each one with its namespace prefix, so chronicle_events_recorded_total scrapes as forge_chronicle_events_recorded_total.

View Source 
const (
	LabelOperation = "operation"
	LabelResult    = "result"
	LabelJob       = "job"
)

Label keys.

View Source 
const (
	OperationRecord     = "record"
	OperationRecordOnce = "record_once"

	ResultOK         = "ok"
	ResultError      = "error"
	ResultNothingNew = "nothing_new"
	ResultLostRace   = "lost_race"

	JobRetention  = "retention"
	JobCheckpoint = "checkpoint"
)

Label values. These are the only values any label ever takes.

View Source 
const (
	SpanRecordEvent       = "record event"
	SpanAcceptEvent       = "accept event"
	SpanVerifyChain       = "verify chain"
	SpanEnforceRetention  = "enforce retention"
	SpanEnforcePolicy     = "enforce retention policy"
	SpanCheckpointStreams = "checkpoint streams"
	SpanTakeCheckpoint    = "take checkpoint"
	SpanGenerateReport    = "generate compliance report"
	SpanEraseSubject      = "erase subject"
)

Span names. Each is a verb and an object, with no IDs in it.

View Source 
const (
	// AttrHashScheme is the digest scheme an event was written under, such
	// as chronicle/v4 or chronicle/v5.
	AttrHashScheme = attribute.Key("chronicle.hash.scheme")
	// AttrSealed is whether the event's personal payload was encrypted for
	// crypto-erasure before it was hashed.
	AttrSealed = attribute.Key("chronicle.sealed")
	// AttrStreamID is the opaque stream ID (a TypeID, stream_...). It names
	// an app and tenant's chain, never a person.
	AttrStreamID = attribute.Key("chronicle.stream.id")

	AttrVerifyValid    = attribute.Key("chronicle.verify.valid")
	AttrVerifyVerified = attribute.Key("chronicle.verify.events_checked")
	AttrVerifyGaps     = attribute.Key("chronicle.verify.gaps")
	AttrVerifyTampered = attribute.Key("chronicle.verify.tampered")
	AttrVerifyPartial  = attribute.Key("chronicle.verify.partial")

	AttrRetentionArchive  = attribute.Key("chronicle.retention.archive")
	AttrRetentionExpired  = attribute.Key("chronicle.retention.expired")
	AttrRetentionArchived = attribute.Key("chronicle.retention.archived")
	AttrRetentionPurged   = attribute.Key("chronicle.retention.purged")

	AttrStreamsScanned      = attribute.Key("chronicle.checkpoint.streams_scanned")
	AttrStreamsDue          = attribute.Key("chronicle.checkpoint.streams_due")
	AttrCheckpointsTaken    = attribute.Key("chronicle.checkpoint.taken")
	AttrCheckpointResult    = attribute.Key("chronicle.checkpoint.result")
	AttrCheckpointEvents    = attribute.Key("chronicle.checkpoint.events")
	AttrCheckpointAlgorithm = attribute.Key("chronicle.checkpoint.algorithm")

	AttrReportType   = attribute.Key("chronicle.report.type")
	AttrReportEvents = attribute.Key("chronicle.report.events")

	AttrErasureEventsAffected = attribute.Key("chronicle.erasure.events_affected")
	AttrErasureKeysDestroyed  = attribute.Key("chronicle.erasure.keys_destroyed")
	AttrErasureLegacyRetained = attribute.Key("chronicle.erasure.legacy_key_retained")
	// AttrErasureFailedStep is the step a failed erasure stopped at: count,
	// record, mark, key_usage, destroy_keys or complete.
	AttrErasureFailedStep = attribute.Key("chronicle.erasure.failed_step")
)

Attribute keys. Every one is namespaced under chronicle.

View Source 
const InstrumentationName = "github.com/xraph/chronicle"

InstrumentationName is the tracer name on every span Chronicle starts.

Variables

View Source 
var RecordBuckets = []float64{0.0005, 0.001, 0.0025, 0.005, 0.01, 0.025, 0.05, 0.1, 0.25, 0.5, 1, 2.5, 5}

RecordBuckets are the bounds, in seconds, for MetricRecordDuration. A record is a stream lock, a digest and two or three queries, so the interesting range is sub-millisecond to a few seconds under contention.

View Source 
var SchedulerBuckets = []float64{0.01, 0.05, 0.1, 0.5, 1, 5, 10, 30, 60, 300, 900}

SchedulerBuckets are the bounds, in seconds, for MetricSchedulerRunDuration. A run covers every policy or every stream, so it can take minutes.

Functions

func Class 

func Class(err error, known ...Sentinel) string

Class names err for a span's status and its exception.type: the Name of the first sentinel err matches, a context error by its package-qualified name, and anything else by the Go type of the innermost error in its chain.

It never returns the error's message. Driver and library messages quote the values they were given (a duplicate key, a key ID derived from a subject), and those must not reach a span.

func Fail 

func Fail(span trace.Span, err error, known ...Sentinel)

Fail marks span as failed: an error status whose description is the error's class, and an exception event carrying only exception.type. It never records the error's message. A nil err does nothing.

func Result 

func Result(err error) string

Result is the result label for a call that either worked or did not.

func Start 

func Start(ctx context.Context, name string, opts ...trace.SpanStartOption) (context.Context, trace.Span)

Start starts an internal span. Pass trace.WithNewRoot for background work that must not hang off whatever span the context carries.

func Tracer 

func Tracer() trace.Tracer

Tracer returns Chronicle's tracer from the global provider.

It is looked up on every call rather than held in a package variable. A tracer taken from the global before a provider is installed only follows the first provider ever installed, so tests that swap providers, and apps that install theirs late, would otherwise lose spans.

Types

type CheckpointMetrics 

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

CheckpointMetrics counts checkpoint attempts by result. A nil *CheckpointMetrics records nothing.

func NewCheckpointMetrics 

func NewCheckpointMetrics(m gometrics.Metrics) *CheckpointMetrics

NewCheckpointMetrics registers the checkpoint counter on m. A nil m returns nil.

func (*CheckpointMetrics) Inc 

func (c *CheckpointMetrics) Inc(result string)

Inc counts one attempt that ended in result.

type RecordMetrics 

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

RecordMetrics is what Chronicle.Record and Chronicle.RecordOnce record on. A nil *RecordMetrics records nothing.

func NewRecordMetrics 

func NewRecordMetrics(m gometrics.Metrics) *RecordMetrics

NewRecordMetrics registers every record series on m up front, so a call never creates one. A nil m returns nil.

func (*RecordMetrics) Observe 

func (r *RecordMetrics) Observe(operation string, err error, elapsed time.Duration)

Observe records one call to operation that took elapsed and ended in err.

type RetentionMetrics 

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

RetentionMetrics counts what retention policies archive and purge. A nil *RetentionMetrics records nothing.

func NewRetentionMetrics 

func NewRetentionMetrics(m gometrics.Metrics) *RetentionMetrics

NewRetentionMetrics registers the retention counters on m. A nil m returns nil.

func (*RetentionMetrics) Add 

func (r *RetentionMetrics) Add(archived, purged int64)

Add records one policy's archived and purged counts.

type SchedulerMetrics 

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

SchedulerMetrics times the extension's background runs. A nil *SchedulerMetrics records nothing.

func NewSchedulerMetrics 

func NewSchedulerMetrics(m gometrics.Metrics) *SchedulerMetrics

NewSchedulerMetrics registers the run duration histogram on m. A nil m returns nil.

func (*SchedulerMetrics) Observe 

func (s *SchedulerMetrics) Observe(job string, err error, elapsed time.Duration)

Observe records one run of job that took elapsed and ended in err.

type Sentinel 

type Sentinel struct {
	Err  error
	Name string
}

Sentinel names an error value for Class.

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.