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.

Usage

Basic

package main

import (
	"context"

	"go.pitz.tech/okit"
)

func main() {
	var tags []okit.Tag

	// Metric emission
	okit.Observe("temperature_c", 20.9, tags...)

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

	// Tracing
	ctx, done := okit.Trace(context.Background(), tags...)
	defer done()
	_ = ctx.Err() // not needed, removes unused error

	// Logging
	okit.Debug("a message used for debugging", tags...)
	okit.Info("an informational message for the user", tags...)
	okit.Warn("a warning indicating an issue with the system", tags...)
	okit.Error("the system encountered an error", tags...)
}

HTTP

okit comes with built-in functionality to make it easy to trace HTTP operations.

package main

import (
	"net/http"

	okithttp "go.pitz.tech/okit/http"
)

func main() {
	// Instrument HTTP Clients
	okithttp.InstrumentClient(http.DefaultClient)

	// Add reporting endpoints
	mux := http.NewServeMux()
	okithttp.RouteEndpoint(mux, okithttp.NewEndpoint())

	// Instrument HTTP Handlers
	handler := okithttp.InstrumentHandler(mux)
	err := http.ListenAndServe("0.0.0.0:8080", handler)
	if err != nil {
		panic(err)
	}
}