sseq

README

sseq

Lightweight tracing for Go: create spans and send them to Seq or Axiom.

No OpenTelemetry SDK. No plugin graph. One package surface: sseq.go.

Provider	HTTP	File (Vector)
Seq	CLEF → Seq ingest	CLEF file → Vector → Seq
Axiom	NDJSON → Axiom ingest	NDJSON file → Vector → Axiom

Quick start

sseq.SetupSeq("http://localhost:5342/ingest/clef", "", "my-service")
defer sseq.Shutdown()

err := sseq.Trace(ctx, "HTTP GET /api/users", "server", func(ctx context.Context) error {
    sseq.Set(ctx, "http.route", "/api/users")
    return sseq.Trace(ctx, "Query users", "", func(ctx context.Context) error {
        sseq.Set(ctx, "db.system", "postgres")
        return nil
    })
})

Setup

// Seq over HTTP
sseq.SetupSeq(endpoint, apiKey, application)

// Axiom over HTTP
sseq.SetupAxiom(token, dataset, application)

// File for Vector → Seq / Axiom
sseq.SetupSeqFile("spans.clef", application)
sseq.SetupAxiomFile("spans.ndjson", application)

API

Function	Purpose
SetupSeq / SetupAxiom	HTTP export
SetupSeqFile / SetupAxiomFile	File export for Vector
Shutdown	Flush and close
Trace(ctx, name, kind, fn)	Run work inside a span
Start(ctx, name, kind)	Manual span; returns (ctx, end)
Set(ctx, key, value)	Attribute on active span
Event(ctx, name, key, value, ...)	Point event on active span
Error(ctx, err)	Mark active span failed
IDs(ctx)	Read trace/span ids
Resume(ctx, traceID, parentSpanID)	Continue async work
HTTP(handler)	HTTP middleware (server spans)

kind may be empty: roots default to server, children to internal.

Async

sseq.Trace(ctx, "HTTP POST /orders", "server", func(ctx context.Context) error {
    traceID, spanID, _ := sseq.IDs(ctx)
    return bus.Publish(traceID, spanID, orderID)
})

workerCtx := sseq.Resume(context.Background(), traceID, spanID)
sseq.Trace(workerCtx, "Process order", "consumer", func(context.Context) error {
    return process(orderID)
})

Layout

sseq.go                      # public API only
internal/
  types.go                   # shared structs
  sender.go                  # batch flush
  providers/
    seq/                     # CLEF encode + HTTP
    axiom/                   # Axiom encode + HTTP
  file/                      # rotated file writer (Vector)
  trace/                     # span lifecycle

Testing

cd sseq
go test ./...
go test ./integration/... -run Integration

Seq Docker (integration)

docker run -d --name sseq-seq \
  -e ACCEPT_EULA=Y \
  -e SEQ_FIRSTRUN_ADMINUSERNAME=admin \
  -e SEQ_FIRSTRUN_ADMINPASSWORD='Admin123456!' \
  -p 5341:80 \
  -p 5342:5341 \
  datalust/seq:latest

Then open http://localhost:5341 and run:

go test ./integration/... -run TestIntegrationSpanTreeWithSeqDocker -v

Variable	Purpose
SSEQ_SKIP_INTEGRATION=1	Skip live integration tests
AXIOM_TOKEN / AXIOM_DATASET	Axiom credentials

Documentation

Overview

Package sseq is a lightweight tracing SDK for Go.

Core flow: Setup → Trace/Start → attributes/events → Shutdown. Spans are exported to Seq or Axiom over HTTP, or written to a file for Vector.

Index

• func Error(ctx context.Context, err error)
• func Event(ctx context.Context, name string, keyValues ...any)
• func HTTP(next http.Handler) http.Handler
• func IDs(ctx context.Context) (traceID, spanID string, ok bool)
• func Resume(ctx context.Context, traceID, parentSpanID string) context.Context
• func Set(ctx context.Context, key string, value any)
• func SetupAxiom(token, dataset, application string) error
• func SetupAxiomFile(filename, application string) error
• func SetupSeq(endpoint, apiKey, application string) error
• func SetupSeqFile(filename, application string) error
• func Shutdown()
• func Start(ctx context.Context, name, kind string) (context.Context, func())
• func Trace(ctx context.Context, name, kind string, fn func(context.Context) error) error

Functions

func Error

func Error(ctx context.Context, err error)

Error marks the active span in ctx as failed.

func Event

func Event(ctx context.Context, name string, keyValues ...any)

Event attaches a named point event to the active span in ctx.

func HTTP

func HTTP(next http.Handler) http.Handler

HTTP wraps an http.Handler and records each request as a server span.

func IDs

func IDs(ctx context.Context) (traceID, spanID string, ok bool)

IDs returns trace/span identifiers from ctx.

func Resume

func Resume(ctx context.Context, traceID, parentSpanID string) context.Context

Resume continues a remote trace in ctx for async workers.

func Set

func Set(ctx context.Context, key string, value any)

Set attaches a key/value attribute to the active span in ctx.

func SetupAxiom

func SetupAxiom(token, dataset, application string) error

SetupAxiom sends spans to Axiom over HTTP.

func SetupAxiomFile

func SetupAxiomFile(filename, application string) error

SetupAxiomFile writes Axiom NDJSON spans to a local file for Vector → Axiom.

func SetupSeq

func SetupSeq(endpoint, apiKey, application string) error

SetupSeq sends CLEF spans to Seq over HTTP.

func SetupSeqFile

func SetupSeqFile(filename, application string) error

SetupSeqFile writes CLEF spans to a local file for Vector → Seq.

func Shutdown

func Shutdown()

Shutdown flushes buffered spans and closes the sender.

func Start

func Start(ctx context.Context, name, kind string) (context.Context, func())

Start begins a span and returns ctx plus an end function. Call end when done.

func Trace

func Trace(ctx context.Context, name, kind string, fn func(context.Context) error) error

Trace runs fn inside a named span. kind may be empty for defaults (server for roots, internal for children).