okit/README.md

okit

Short for "observability kit", okit aims to provide an all-in-one solution to application observability.

Why

Traditional approaches to observability treat logging, application metrics, and tracing as independent operations, with independent data streams. In practice, these elements are more or less all the same, with some minor differences between them. Developers often have to choose between logging a message, emitting a metric, or expanding a trace.

Logging

• Used by developers and operators to determine what issues an application may be facing.
• High cardinality data (errors, stack traces, user id / signature).
• Often sent to stdout/stderr and can optionally be captured by traditional logging solutions.

Tracing

• Used by developers and operators to troubleshoot performance issues across a set of distributed systems.
• Medium cardinality data (consistent structure, high variability in tag values)
• Typically available in real-time to assess product performance.

Metrics

• Used by developers and product managers to determine details about how their product is doing.
• Medium/High cardinality data (user id / signature, other metadata fields).
• Typically available in real-time to assess user experience / feature performance.

How

package main

import (
	"context"
	"os/signal"
	"syscall"
	"time"

	"go.pitz.tech/okit"
)

var tags []okit.Tag

func do(ctx context.Context) {
	ctx, done := okit.With(tags...).Trace(ctx)
	defer done()

	// DO WORK!
	select {
	case <-ctx.Done():
	case <-time.After(time.Second):
	}
}

func main() {
	ctx, shutdown := signal.NotifyContext(context.Background(), syscall.SIGINT, syscall.SIGTERM)
	defer shutdown()

	// Metric emission
	okit.Observe("", 0, tags...)

	// Multi-dimensional events
	okit.Emit("", tags...)

	// Tracing
	ctx, done := okit.Trace(context.Background())
	defer done()

	// Logging
	okit.Debug("", tags...)
	okit.Info("", tags...)
	okit.Warn("", tags...)
	okit.Error("", tags...)

	do(ctx)
}