Documentation
¶
Overview ¶
Package telemetry is the small amount of OpenTelemetry glue fabriq's core shares with the root module: the tracer, the helpers that keep background work off the trace that started it, the producer-to-consumer span link, an error marker that never copies error text onto a span, and the observer interfaces through which a host records fabriq's duration metrics.
Core records no metrics itself and installs no provider. Spans go to the global tracer provider (forge.New installs one); durations go to whatever observer the host wires in (fabriq's forge extension records them on its Prometheus registry). A nil observer records nothing.
Index ¶
- Constants
- func Classify(err error) string
- func Detach(ctx context.Context) context.Context
- func ErrorType(err error) string
- func Fail(span trace.Span, class string, err error)
- func LinkFromTraceparent(traceparent string) (trace.Link, bool)
- func StartConsumer(ctx context.Context, name, traceparent string, attrs ...attribute.KeyValue) (context.Context, trace.Span)
- func StartRoot(ctx context.Context, name string, opts ...trace.SpanStartOption) (context.Context, trace.Span)
- func Tracer() trace.Tracer
- func WithoutBaggage(ctx context.Context) context.Context
- type ApplyObserver
- type CommandObserver
Constants ¶
const ( ResultOK = "ok" ResultError = "error" ResultInvalid = "invalid" ResultConflict = "conflict" ResultNotFound = "not_found" )
Result values shared by fabriq's duration metrics and span attributes.
const ( AttrEntity = attribute.Key("fabriq.entity") AttrProjection = attribute.Key("fabriq.projection") AttrResult = attribute.Key("fabriq.result") AttrBatchSize = attribute.Key("fabriq.batch_size") AttrMutations = attribute.Key("fabriq.mutations") AttrOp = attribute.Key("fabriq.command.op") AttrModelKind = attribute.Key("fabriq.model.kind") AttrInputs = attribute.Key("fabriq.model.inputs") // AttrConsumerGroup is the OTel messaging semconv key for a consumer // group (proj:graph, proj:search, ...). AttrConsumerGroup = attribute.Key("messaging.consumer.group.name") // AttrMessagingSystem is the OTel messaging semconv system key. AttrMessagingSystem = attribute.Key("messaging.system") )
Attribute keys fabriq puts on spans. Values are counts, booleans and bounded enum strings, plus the entity name (spans only, never a metric label: runtime dynamic entities make it unbounded).
const ScopeName = "github.com/xraph/fabriq/core"
ScopeName is the instrumentation scope of every span core starts.
Variables ¶
This section is empty.
Functions ¶
func Classify ¶
Classify maps an error onto the bounded result enum the duration metrics use: ok, not_found, conflict or error.
func Detach ¶
Detach returns ctx with its span removed. Cancellation, deadlines and values (the tenant) survive; only the trace parent goes. Every long-lived loop calls it once where its ctx is made, so queries an idle tick runs never land in the boot or request trace the loop was started from (grove starts a db.client span under any valid span context, even an ended one).
func ErrorType ¶
ErrorType names err for an exception.type attribute: a known sentinel's name, else the Go type of the innermost wrapped error.
func Fail ¶
Fail marks span as failed. The status description is class, a short fixed string chosen by the caller, and the exception event carries only the error's type. Error text never reaches the span: driver and library messages quote values (keys, payload fragments, DSNs).
func LinkFromTraceparent ¶
LinkFromTraceparent turns a stored W3C traceparent into a span link. ok is false for an empty or malformed value.
func StartConsumer ¶
func StartConsumer(ctx context.Context, name, traceparent string, attrs ...attribute.KeyValue) (context.Context, trace.Span)
StartConsumer starts the span for one consumed message: a new root of kind Consumer, linked (not parented) to the producer context stored in traceparent. The request that produced the message has usually finished by the time it is consumed, so the consumer's work gets its own trace and the link leads back to the producer.
func StartRoot ¶
func StartRoot(ctx context.Context, name string, opts ...trace.SpanStartOption) (context.Context, trace.Span)
StartRoot starts a new root span on core's tracer from a detached copy of ctx, for one unit of background work. opts may add a kind, links and attributes.
Types ¶
type ApplyObserver ¶
ApplyObserver receives one observation per envelope a projection consumer applies. projection is graph, search, analytics or insights; result is ok or error.
type CommandObserver ¶
CommandObserver receives one observation per command batch the executor runs. op is create, update, delete, upsert, mixed for a batch that combines several, or unknown for an op value the executor doesn't define (such a batch always fails validation, so its result is invalid). result is ok, invalid, conflict, not_found or error.
Source Files
Directories
¶
| Path | Synopsis |
|---|---|
|
Package telemetrytest holds test helpers for fabriq's tracing: a span recorder installed as the global tracer provider, and a scan that proves a value never reached a span.
|
Package telemetrytest holds test helpers for fabriq's tracing: a span recorder installed as the global tracer provider, and a scan that proves a value never reached a span. |