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 ContextWithChildSpan(ctx context.Context) (context.Context, *telemetryv1.TraceContext, error)
- func ContextWithTrace(ctx context.Context, trace *telemetryv1.TraceContext) (context.Context, error)
- func NewTraceContext(traceFlags uint32) (*telemetryv1.TraceContext, error)
- func TraceFromContext(ctx context.Context) (*telemetryv1.TraceContext, bool)
- func ValidateLogRecord(record *telemetryv1.LogRecord) error
- func ValidateTraceContext(trace *telemetryv1.TraceContext) error
- 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 ContextWithChildSpan ¶
func ContextWithChildSpan(ctx context.Context) (context.Context, *telemetryv1.TraceContext, error)
ContextWithChildSpan derives a child of the span in ctx and returns a new context carrying it.
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 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 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.