Documentation
¶
Overview ¶
Package telemetry provides dependency-light distributed trace propagation and structured JSONL logging over the candace.telemetry.v1 protobuf contracts. TraceContext is the portable boundary; this package deliberately does not depend on an observability SDK.
Index ¶
- Constants
- Variables
- func ContextWithTrace(ctx context.Context, trace *telemetryv1.TraceContext) (context.Context, error)
- func NewTraceContext(traceFlags uint32) (*telemetryv1.TraceContext, error)
- func RegisterOnce[T prometheus.Collector](registerer prometheus.Registerer, collector T) (T, error)
- func TraceFromContext(ctx context.Context) (*telemetryv1.TraceContext, bool)
- func ValidateLogRecord(record *telemetryv1.LogRecord) error
- func ValidateTraceContext(trace *telemetryv1.TraceContext) error
- type ChildSpan
- type JSONLLogger
Constants ¶
const ( // MaxAttributes bounds the number of attributes on one LogRecord. MaxAttributes = 32 // MaxAttributeKeyBytes bounds one attribute key. MaxAttributeKeyBytes = 64 // MaxAttributeValueBytes bounds one attribute value. MaxAttributeValueBytes = 1024 // MaxAttributeBytes bounds all attribute keys and values on one LogRecord. MaxAttributeBytes = 8192 )
const TraceFlagsSampled uint32 = uint32(oteltrace.FlagsSampled)
TraceFlagsSampled is the W3C sampled flag.
Variables ¶
var ( // ErrNilContext indicates that a propagation helper received a nil context. ErrNilContext = errors.New("telemetry: nil context") // ErrTraceContextNotFound indicates that a child span was requested without // a parent TraceContext in the context.Context. ErrTraceContextNotFound = errors.New("telemetry: trace context not found") )
var ( // ErrInvalidTraceContext is the sentinel for an invalid portable trace. ErrInvalidTraceContext = errors.New("telemetry: invalid trace context") // ErrInvalidLogRecord is the sentinel for a record rejected at the JSONL // write boundary. ErrInvalidLogRecord = errors.New("telemetry: invalid log record") )
var ( // ErrNilWriter indicates that a JSONL logger was constructed without a // destination. ErrNilWriter = errors.New("telemetry: nil JSONL writer") )
Functions ¶
func ContextWithTrace ¶
func ContextWithTrace(ctx context.Context, trace *telemetryv1.TraceContext) (context.Context, error)
ContextWithTrace stores trace as an OpenTelemetry SpanContext in ctx.
func NewTraceContext ¶
func NewTraceContext(traceFlags uint32) (*telemetryv1.TraceContext, error)
NewTraceContext starts a trace with cryptographically random OpenTelemetry trace and span identifiers. traceFlags must fit in the W3C one-byte field.
func RegisterOnce ¶ added in v0.3.0
func RegisterOnce[T prometheus.Collector](registerer prometheus.Registerer, collector T) (T, error)
RegisterOnce registers collector with registerer and returns the collector that ends up registered. When a collector is already registered under the same name and type, RegisterOnce returns that existing collector, so two builders of the same metric share one instance instead of the second registration failing. A name already held by a different concrete type is an error, so two collectors never silently share a name.
func TraceFromContext ¶
func TraceFromContext(ctx context.Context) (*telemetryv1.TraceContext, bool)
TraceFromContext converts the OpenTelemetry SpanContext in ctx to protobuf.
func ValidateLogRecord ¶
func ValidateLogRecord(record *telemetryv1.LogRecord) error
ValidateLogRecord checks the complete logging contract. Generated Liquid validation covers the record's scalar fields; nested messages and maps are deliberately checked here because refinement generation is non-recursive.
func ValidateTraceContext ¶
func ValidateTraceContext(trace *telemetryv1.TraceContext) error
ValidateTraceContext validates the portable trace fields used by Candace.
Types ¶
type ChildSpan ¶ added in v0.3.0
type ChildSpan struct {
Context context.Context
Trace *telemetryv1.TraceContext
}
ChildSpan is the compound result of ContextWithChildSpan: the derived child context and the trace context it carries.
type JSONLLogger ¶
type JSONLLogger struct {
// contains filtered or unexported fields
}
JSONLLogger writes one validated LogRecord per physical line. A logger is safe for concurrent use even when its destination io.Writer is not.
func NewJSONLLogger ¶
func NewJSONLLogger(writer io.Writer, service, component string) (*JSONLLogger, error)
NewJSONLLogger constructs a logger with service identity applied to every record emitted through Log. component may be empty.
func (*JSONLLogger) Log ¶
func (logger *JSONLLogger) Log( ctx context.Context, severity telemetryv1.Severity, event string, message string, attributes map[string]string, ) error
Log builds and writes a record, automatically adding the current timestamp and any TraceContext carried by ctx. The attributes map is copied.
func (*JSONLLogger) WriteRecord ¶
func (logger *JSONLLogger) WriteRecord(record *telemetryv1.LogRecord) error
WriteRecord validates and writes record without modifying it. Proto field names are retained in JSON so Loki queries match the canonical schema.
Source Files