API Reference
observe
import "github.com/danmestas/dagnats/observe"Index
- func ContextWithParentInfo(ctx context.Context, traceID, spanID string) context.Context
- type Attribute
- type Counter
- type ErrorReporter
- type Field
- type Gauge
- type Histogram
- type Level
- type Logger
- type Metrics
- type ParentInfo
- type Span
- type SpanContext
- type SpanKind
- type SpanOption
- type StatusCode
- type Telemetry
- type Tracer
func ContextWithParentInfo
func ContextWithParentInfo(ctx context.Context, traceID, spanID string) context.ContextContextWithParentInfo stores remote parent span info in ctx. Used by propagation code to pass trace context from incoming NATS messages to Tracer.Start without importing vendor packages.
type Attribute
Attribute is a typed key-value pair attached to spans and events. Value must be one of: string, int64, float64, bool — adapters may panic on other types to surface programmer errors early.
type Attribute struct {
Key string
Value any
}func BoolAttr
func BoolAttr(key string, val bool) AttributeBoolAttr constructs an Attribute with a bool value.
func Float64Attr
func Float64Attr(key string, val float64) AttributeFloat64Attr constructs an Attribute with a float64 value.
func Int64Attr
func Int64Attr(key string, val int64) AttributeInt64Attr constructs an Attribute with an int64 value.
func StringAttr
func StringAttr(key, val string) AttributeStringAttr constructs an Attribute with a string value.
type Counter
Counter is a monotonically increasing metric instrument.
type Counter interface {
Inc()
Add(delta float64)
}type ErrorReporter
ErrorReporter captures exceptions and messages to an external error-tracking backend. The concrete backend (e.g. Sentry) lives in a separate adapter package; this interface keeps engine/worker/api independent of any vendor import.
type ErrorReporter interface {
CaptureError(ctx context.Context, err error, tags map[string]string)
CaptureMessage(ctx context.Context, msg string, level Level)
}func NewNoopErrorReporter
func NewNoopErrorReporter() ErrorReporterNewNoopErrorReporter returns an ErrorReporter that discards all captures.
type Field
Field is a typed key-value pair for structured log and error report context.
type Field struct {
Key string
Value any
}func Err
func Err(err error) FieldErr constructs a Field that captures an error under the conventional “error” key.
func Int
func Int(key string, val int) FieldInt constructs a Field with an int value.
func String
func String(key, val string) FieldString constructs a Field with a string value.
type Gauge
Gauge is a metric that can go up or down (e.g. queue depth, active goroutines).
type Gauge interface {
Set(value float64)
Inc()
Dec()
}type Histogram
Histogram records observations in configurable buckets (e.g. latency, payload size).
type Histogram interface {
Observe(value float64)
}type Level
Level represents the severity of an observability event. Ordered from least to most severe; only values in levelStrings are valid.
type Level intconst (
LevelDebug Level = iota
LevelInfo
LevelWarn
LevelError
)func (Level) String
func (l Level) String() stringString returns the lowercase name of the level. Panics on unknown levels to surface programmer errors at the call site rather than silently corrupting output.
type Logger
Logger is the structured logging contract. Implementations must be safe for concurrent use. With returns a new Logger that prepends the given fields to every subsequent log call — it must never return nil.
type Logger interface {
Info(msg string, fields ...Field)
Error(msg string, err error, fields ...Field)
With(fields ...Field) Logger
}func NewNoopLogger
func NewNoopLogger() LoggerNewNoopLogger returns a Logger that discards all output.
type Metrics
Metrics is the factory for named metric instruments. Tags are label key-value pairs that the underlying backend attaches to each observation. The concrete backend (e.g. Prometheus, OTel) lives in a separate adapter package.
type Metrics interface {
Counter(name string, tags map[string]string) Counter
Histogram(name string, tags map[string]string) Histogram
Gauge(name string, tags map[string]string) Gauge
}func NewNoopMetrics
func NewNoopMetrics() MetricsNewNoopMetrics returns a Metrics factory that produces no-op instruments.
type ParentInfo
ParentInfo carries trace/span IDs from an extracted traceparent so that Tracer.Start implementations can link child spans to remote parents across process/message boundaries.
type ParentInfo struct {
TraceID string
SpanID string
}func ParentInfoFromContext
func ParentInfoFromContext(ctx context.Context) (ParentInfo, bool)ParentInfoFromContext returns any ParentInfo stored in ctx. Returns ok=false when no parent info is present.
type Span
Span represents a single unit of work in a distributed trace. End must be called exactly once; all other methods are safe to call in any order before End.
type Span interface {
End()
SetStatus(code StatusCode, description string)
SetAttributes(attrs ...Attribute)
RecordError(err error)
AddEvent(name string, attrs ...Attribute)
}type SpanContext
SpanContext exposes trace/span IDs for cross-process propagation. Span implementations may optionally implement this interface. Callers use type assertion: if sc, ok := span.(SpanContext); ok { … }
type SpanContext interface {
TraceID() string
SpanID() string
}type SpanKind
SpanKind describes the role a span plays in a distributed trace. Internal is the safe default; Server/Client distinguish RPC boundaries.
type SpanKind intconst (
SpanKindInternal SpanKind = iota
SpanKindServer SpanKind = iota
SpanKindClient SpanKind = iota
)type SpanOption
SpanOption is a sealed option type for Tracer.Start. The private marker method prevents external packages from implementing the interface, keeping the option set under our control while remaining extensible within observe.
type SpanOption interface {
// contains filtered or unexported methods
}func WithAttributes
func WithAttributes(attrs ...Attribute) SpanOptionWithAttributes attaches Attributes to the span at creation time.
func WithSpanKind
func WithSpanKind(kind SpanKind) SpanOptionWithSpanKind sets the kind of the span being started.
type StatusCode
StatusCode classifies the outcome of a span. Only StatusOK and StatusError are valid; callers that pass unknown values will encounter panics in adapters.
type StatusCode intconst (
StatusOK StatusCode = iota
StatusError StatusCode = iota
)type Telemetry
Telemetry bundles all observability interfaces. Passed as a single argument to component constructors instead of separate parameters. All fields must be non-nil — use Noop constructors for safe defaults.
type Telemetry struct {
Tracer Tracer
Logger Logger
Metrics Metrics
Errors ErrorReporter
}func NewNoopTelemetry
func NewNoopTelemetry() *TelemetryNewNoopTelemetry returns a Telemetry with all noop implementations. Safe default for tests and environments where telemetry is not needed.
type Tracer
Tracer creates Spans. Implementations must be safe for concurrent use. The returned context carries the new span so downstream calls can propagate it.
type Tracer interface {
Start(ctx context.Context, name string, opts ...SpanOption) (context.Context, Span)
}func NewNoopTracer
func NewNoopTracer() TracerNewNoopTracer returns a Tracer that produces no-op spans and discards all data.
Generated by gomarkdoc