clog

README

clog

clog sends structured log events to an OpenTracing-compatible backend (e.g., Jaeger) by attaching them to active spans. It wraps jaeger-client-go with sensible defaults so you can start tracing with minimal setup.

Install

go get github.com/nanjj/clog

Quick Start

1. Initialise the tracer (usually in main)

tracer, err := clog.NewTracer("my-service")
if err != nil {
    panic(err)
}
clog.SetGlobalTracer(tracer)
defer tracer.Close() // flush pending spans before exit

2. Create spans and attach logs

span, ctx := clog.StartSpanFromContext(ctx, "CreateOrder")
defer span.Finish()

// Log structured key-value pairs on the span
span.LogKV("event", "order_created", "order_id", "12345")

// Or use the more type-safe log.Field API
span.LogFields(
    log.String("event", "payment_processed"),
    log.Int("amount_cents", 2999),
)

Environment Variables

clog reads standard Jaeger environment variables via config.FromEnv(). Values set before importing clog take priority over the built-in defaults.

Variable	Default	Description
JAEGER_SERVICE_NAME	(set via NewTracer(name))	Service name shown in traces
JAEGER_SAMPLER_TYPE	const	Sampler type (const, probabilistic, ratelimiting, remote)
JAEGER_SAMPLER_PARAM	1	Sampler parameter (e.g. 1 = sample all)
JAEGER_REPORTER_MAX_QUEUE_SIZE	64	Max spans in the send queue
JAEGER_REPORTER_FLUSH_INTERVAL	10s	How often to flush spans to the agent
JAEGER_TRACEID_128BIT	true	128-bit trace IDs (W3C Trace Context standard)
JAEGER_AGENT_HOST	localhost	Jaeger agent UDP host
JAEGER_AGENT_PORT	6831	Jaeger agent UDP port
JAEGER_REPORTER_LOG_SPANS	(not set)	Log reporter activity when set to true
JAEGER_DISABLED	(not set)	Disable tracing when set to true
JAEGER_TAGS	(not set)	Comma-separated key=value tags applied to all spans

Customising the agent endpoint

By default spans are sent to localhost:6831 (Jaeger agent UDP socket). To change:

export JAEGER_AGENT_HOST=jaeger.example.com
export JAEGER_AGENT_PORT=6831

Additional tags at construction time

tracer, err := clog.NewTracer("my-service",
    config.Tag("runner", "127.0.0.1:54321"),
    config.Tag("leader", "127.0.0.1:54312"),
)

API

clog.NewTracer(name string, opts ...config.Option) (*Tracer, error)

Creates a new Jaeger tracer. The name is used as the JAEGER_SERVICE_NAME. Additional config.Option values (e.g., config.Tag(...)) can be passed to customise the tracer further.

clog.NewTracerWithOptions(name string, opts ...Option) (*Tracer, error)

Creates a new Jaeger tracer with programmatic option overrides. Options are applied before reading environment variables, so they take precedence over env vars.

tracer, err := clog.NewTracerWithOptions("my-service",
    clog.With128Bit(true),
)

clog.With128Bit(enabled bool) Option

Enables or disables 128-bit trace IDs. Enabled by default via init() — pass With128Bit(false) to use legacy 64-bit trace IDs.

clog.CloseTracer(tracer *Tracer) error

Closes a tracer, flushing any pending spans. Safe to call with nil.

defer clog.CloseTracer(tracer)

clog.SetGlobalTracer(tracer *Tracer)

Registers the tracer as the OpenTracing global tracer. Required before calling StartSpanFromContext without a parent span in context.

clog.GlobalTracer() *Tracer

Returns the previously registered global tracer, or nil if none was set.

clog.StartSpanFromContext(ctx, name, opts...) (opentracing.Span, context.Context)

Starts a new span. If ctx already contains a parent span, the new span becomes a child of it; otherwise a root span is created via the global tracer. Returns the span and an updated context that carries it.

clog.ExtractFromEnv(ctx) opentracing.SpanContext

Extracts a parent span context from environment variables (CLOG_TRACEPARENT—W3C Trace Context, fallback UBER_TRACE_ID—Jaeger legacy). Used together with InjectToEnv to propagate traces across process boundaries.

clog.InjectToEnv(span opentracing.Span)

Serialises a span's context into environment variables (CLOG_TRACEPARENT, CLOG_BAGGAGE_*) so a child process can pick it up via ExtractFromEnv.

// Parent process
span, ctx := clog.StartSpanFromContext(ctx, "parent")
clog.InjectToEnv(span)

cmd := exec.Command("child-binary")
cmd.Env = os.Environ() // carries CLOG_TRACEPARENT
cmd.Run()

// Child process (child-binary)
ctx := context.Background()
parentCtx := clog.ExtractFromEnv(ctx) // reads CLOG_TRACEPARENT
span, ctx := clog.StartSpanFromContext(ctx, "child")
// span is a child of the parent
defer span.Finish()

Important Notes

1. 128-bit trace IDs: clog enables 128-bit trace IDs by default (JAEGER_TRACEID_128BIT=true). This aligns with the W3C Trace Context and OpenTelemetry standards. To use legacy 64-bit trace IDs, set JAEGER_TRACEID_128BIT=false before importing clog, or pass clog.With128Bit(false) to NewTracerWithOptions.

2. UDP packet limits: Jaeger's agent accepts spans over UDP. If you log many events in a single span, the combined payload may exceed the ~65 KB UDP packet limit. Use JAEGER_REPORTER_MAX_QUEUE_SIZE and JAEGER_REPORTER_FLUSH_INTERVAL to tune batching.

3. Always close: defer tracer.Close() in main and defer span.Finish() in each traced operation are required. Without them, buffered spans may never reach the backend. clog.CloseTracer(tracer) is a nil-safe convenience wrapper.

4. Child span lifecycle: A child span must be finished before its parent. The parent span only sends its logs and timing after Finish() is called.

5. init() side effects: Importing clog sets Jaeger environment variable defaults (see table above). These are only applied when the corresponding env var is unset, so explicit env vars always win.

6. Cross-process propagation: Use InjectToEnv/ExtractFromEnv to propagate traces across process boundaries (e.g., exec.Command). ExtractFromEnv is also called internally by StartSpanFromContext as a fallback when no parent span exists in context, so child processes can create child spans without calling ExtractFromEnv explicitly.

Documentation

Overview

Package clog provides structured log events via OpenTracing/Jaeger.

Basic usage:

tracer, err := clog.NewTracer("my-service")
if err != nil {
    log.Fatal(err)
}
defer tracer.Close()
clog.SetGlobalTracer(tracer)

span, ctx := clog.StartSpanFromContext(context.Background(), "operation")
defer span.Finish()
span.LogKV("event", "work-done", "count", 42)

Environment variables optionally set by init (only when unset):

JAEGER_SAMPLER_TYPE    const
JAEGER_SAMPLER_PARAM   1
JAEGER_TRACEID_128BIT  true

Reporter env vars MaxQueueSize and FlushInterval are NOT set by init; the Jaeger client's built-in defaults (100, 1s) are used instead. Set any of these before importing clog to override the default. Use NewTracerWithOptions for programmatic control.

Index

• func CloseTracer(tracer *Tracer) error
• func ExtractFromEnv(_ context.Context) opentracing.SpanContext
• func InjectToEnv(span opentracing.Span)
• func SetGlobalTracer(tracer *Tracer)
• func SpanFromContext(ctx context.Context) opentracing.Span
• func StartSpanFromContext(ctx context.Context, name string, opts ...opentracing.StartSpanOption) (opentracing.Span, context.Context)
• type Option
  • func With128Bit(enabled bool) Option
• type Tracer
  • func GlobalTracer() (tracer *Tracer)
  • func NewTracer(name string, opts ...config.Option) (tracer *Tracer, err error)
  • func NewTracerWithOptions(name string, opts ...Option) (*Tracer, error)

Functions

func CloseTracer

func CloseTracer(tracer *Tracer) error

CloseTracer closes a *Tracer, flushing any pending spans. Safe to call with nil — returns nil immediately.

func ExtractFromEnv

func ExtractFromEnv(_ context.Context) opentracing.SpanContext

ExtractFromEnv extracts a remote parent SpanContext from environment variables propagated by a parent process. Returns nil if no trace context is found.

Supported env vars (checked in order):

• CLOG_TRACEPARENT (W3C Trace Context, preferred)
• UBER_TRACE_ID (Jaeger legacy, backward-compatible)

CLOG_TRACEPARENT format (W3C):

00-{trace-id-32hex}-{span-id-16hex}-{flags-2hex}

Example:

00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01

UBER_TRACE_ID format (Jaeger legacy):

{trace-id}:{span-id}:{parent-span-id}:{flags}

func InjectToEnv

func InjectToEnv(span opentracing.Span)

InjectToEnv injects the span's context into environment variables so that child processes can continue the trace via StartSpanFromContext / ExtractFromEnv.

Call before exec'ing a child process:

span, _ := clog.StartSpanFromContext(ctx, "parent-op")
defer span.Finish()
clog.InjectToEnv(span)
// exec child ...

Sets CLOG_TRACEPARENT (W3C format) and CLOG_BAGGAGE_* for baggage items.

func SetGlobalTracer

func SetGlobalTracer(tracer *Tracer)

SetGlobalTracer registers the tracer as the OpenTracing global tracer. Must be called before StartSpanFromContext when there is no parent span.

func SpanFromContext

func SpanFromContext(ctx context.Context) opentracing.Span

SpanFromContext returns a span from context if one exists.

func StartSpanFromContext

func StartSpanFromContext(ctx context.Context,
	name string,
	opts ...opentracing.StartSpanOption) (opentracing.Span, context.Context)

StartSpanFromContext starts a span from context and returns the span and new context with the span. If a parent span exists in the context, the new span is created as a child of it. Otherwise, if a remote parent SpanContext has been propagated via environment variables (see ExtractFromEnv), the new span is created as a child of that remote parent. Otherwise a root span is started via the global tracer.

Types

type Option

type Option func()

Option programmatically overrides Jaeger tracer configuration. Options are applied before config.FromEnv(), so they take precedence over environment variables (but not over values set explicitly before calling NewTracerWithOptions).

func With128Bit

func With128Bit(enabled bool) Option

With128Bit enables or disables 128-bit trace IDs. Enabled by default via init. Pass With128Bit(false) to use legacy 64-bit trace IDs.

type Tracer

type Tracer struct {
	opentracing.Tracer
	io.Closer
}

Tracer wraps an OpenTracing tracer with its io.Closer. Call Close to flush pending spans before the process exits.

func GlobalTracer

func GlobalTracer() (tracer *Tracer)

GlobalTracer returns the previously registered global tracer, or nil if none was set or if the global tracer is not a clog.Tracer.

func NewTracer

func NewTracer(name string, opts ...config.Option) (tracer *Tracer, err error)

NewTracer creates a new Jaeger tracer with the given service name. The name is used as JAEGER_SERVICE_NAME. Additional config.Option values (e.g. config.Tag) can be passed to customise the tracer.

func NewTracerWithOptions

func NewTracerWithOptions(name string, opts ...Option) (*Tracer, error)

NewTracerWithOptions creates a new Jaeger tracer with programmatic option overrides. Options are applied before reading environment variables, so they take precedence over env vars.