telemetry

package
v0.2.2 Latest Latest
Warning

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

Go to latest
Published: Oct 3, 2026 License: Apache-2.0 Imports: 15 Imported by: 0

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

View Source
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
)
View Source
const TraceFlagsSampled uint32 = uint32(oteltrace.FlagsSampled)

TraceFlagsSampled is the W3C sampled flag.

Variables

View Source
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")
)
View Source
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")
)
View Source
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.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL