Documentation
¶
Overview ¶
Package telemetry provides bounded, payload-free operational events for hosts that need to observe CRDT transport boundaries.
Index ¶
Constants ¶
This section is empty.
Variables ¶
var ( // ErrInvalidConfig reports a nil sink or invalid bounded queue size. ErrInvalidConfig = errors.New("crdt telemetry: invalid configuration") )
Functions ¶
func RegisterOpenTelemetryDroppedMetric ¶
func RegisterOpenTelemetryDroppedMetric(reporter *Reporter, options OpenTelemetryOptions) (metric.Registration, error)
RegisterOpenTelemetryDroppedMetric exports Reporter.Dropped as the crdt.telemetry.dropped ({event}) cumulative counter. It reads one atomic value only when the configured Metrics SDK collects, so it adds no work to Record's overload path. Call Unregister during host shutdown before discarding the Reporter or MeterProvider.
One reporter should be registered for a MeterProvider. Multiple reporters have no reporter-ID attribute by design: adding such an unbounded label would weaken the payload-free, low-cardinality contract.
Types ¶
type Event ¶
type Event struct {
Time time.Time
Component string
Operation string
Outcome Outcome
Duration time.Duration
ErrorCode crdt.ErrorCode
}
Event describes an operational boundary without including replica IDs, group IDs, endpoints, headers, payloads, or application values. Component and Operation should be fixed names chosen by the library or host.
type OpenTelemetryOptions ¶
type OpenTelemetryOptions struct {
MeterProvider metric.MeterProvider
// AllowedComponents and AllowedOperations explicitly add fixed host labels
// to the library's built-in telemetry vocabulary. Each list is limited to
// 16 short ASCII labels. Undeclared Event values are exported as "other".
// Do not add IDs, endpoints, headers, payload fragments, or business data.
AllowedComponents []string
AllowedOperations []string
}
OpenTelemetryOptions configures an explicit OpenTelemetry Metrics export. MeterProvider is required: this package never selects a process-global provider or configures an exporter, endpoint, credential, or retry policy. The host owns those deployment concerns.
type Options ¶
Options configures one bounded Reporter. QueueSize defaults to 256. Sink is required so construction cannot silently create a background no-op worker.
type Outcome ¶
type Outcome string
Outcome is the privacy-safe result category for one operational event.
type Reporter ¶
type Reporter struct {
// contains filtered or unexported fields
}
Reporter asynchronously delivers a bounded stream of operational events. Record never waits for Sink and never changes application behavior. It is safe for concurrent use. Call Close during host shutdown to request delivery shutdown; Close does not wait for a blocked third-party sink.
func (*Reporter) Close ¶
func (reporter *Reporter) Close()
Close stops normal event acceptance and requests that the worker exit. One event that raced with Close may still reach Sink. Close is idempotent and returns immediately even when a third-party Sink has blocked.
func (*Reporter) Done ¶
func (reporter *Reporter) Done() <-chan struct{}
Done closes after the delivery goroutine exits. It can remain open when a third-party Sink blocks, which is why Close never waits for it.
type Sink ¶
type Sink func(Event)
Sink receives events on a Reporter-owned goroutine. It may block or panic without delaying CRDT, transport, or request paths; a blocked sink only causes the report queue to fill and later events to be dropped.
func NewOpenTelemetrySink ¶
func NewOpenTelemetrySink(options OpenTelemetryOptions) (Sink, error)
NewOpenTelemetrySink adapts payload-free Events to OpenTelemetry Metrics. It records crdt.telemetry.events ({event}) and crdt.telemetry.duration (s) with only crdt.component, crdt.operation, crdt.outcome, and an optional crdt.error_code attribute. The Event timestamp is intentionally not exported: the configured Metrics SDK assigns collection timestamps.
Component and Operation are reduced to "other" unless they belong to the library's fixed vocabulary or an explicit host allow-list. This prevents URLs, headers, IDs, payload fragments, and application values from becoming metric attributes. Hosts must use fixed, low-cardinality labels.
The returned Sink is intended for Reporter. Reporter calls it from its bounded delivery goroutine, so a slow Metrics provider cannot delay CRDT or transport paths. This function does not configure an OTLP exporter.
Source Files