otello

otello

Unified observability library for Go backends. Provides tracing (Tempo), logging (Loki), metrics (Prometheus), and continuous profiling (Pyroscope) with standardized business context propagation.

Install

go get github.com/Heer0/otello

Quick Start

Tracing only (minimal)

shutdown, err := otello.Init(otello.Config{
    Service:   "my-service",
    Namespace: "my-ns",
})
if err != nil {
    log.Fatal().Err(err).Msg("otello init failed")
}
defer shutdown(ctx)

Full stack (tracing + logging + metrics + profiling)

shutdown, err := otello.Init(otello.Config{
    Service:   "my-service",
    Namespace: "my-ns",
    Loki:      &otello.LokiConfig{},
    Metrics:   &otello.MetricsConfig{},
    Pyroscope: &otello.PyroscopeConfig{},
})
defer shutdown(ctx)

Configuration

Business Context

Standardized attributes propagated across spans, logs, and metrics:

ctx = otello.WithBusinessContext(ctx, otello.BusinessContext{
    UserID:    "user-123",
    TenantID:  "tenant-456",
    Operation: "createCustomer",
    Entity:    "customer",
    EntityID:  "cust-789",
})

HTTP Middleware

net/http

handler := middleware.HTTP()(myHandler)

chi

r := chi.NewRouter()
r.Use(middleware.Chi())

Ignore paths/methods

r.Use(middleware.HTTP(middleware.HTTPConfig{
    IgnorePaths:   []string{"/health", "/metrics"},
    IgnoreMethods: []string{"OPTIONS"},
}))

GraphQL (gqlgen)

srv.Use(middleware.GqlgenExtension("my-graphql", middleware.GqlgenConfig{
    TraceFields: true,
}))

GORM

// Tracing only
otello.InitGORM(db)

// With slow query metrics + pool stats
sqlDB, _ := db.DB()
otello.InitGORMWithMetrics(db, sqlDB, 200*time.Millisecond)

Prometheus Metrics

r.Handle("/metrics", otello.MetricsHandler())

Continuous Profiling (Pyroscope)

When Pyroscope is set in the config, CPU, memory, goroutine, and mutex profiles are continuously pushed to Pyroscope.

The HTTP and GraphQL middlewares automatically tag profiles with endpoint and operation labels, so you can filter flamegraphs per route or GraphQL operation in Grafana.

NATS Propagation

// Producer
headers := otello.InjectTraceContext(ctx)
msg := &nats.Msg{Header: nats.Header(headers)} // adapt as needed

// Consumer
ctx = otello.ExtractTraceContext(ctx, otello.MapCarrier(receivedHeaders))

Span Helpers

// Auto-close pattern
ctx, end := otello.StartSpan(ctx, "processOrder")
defer end(err)

// Manual span control
ctx, span := otello.TraceOperation(ctx, "uploadFile",
    otello.AttrEntity.String("document"),
)
defer span.End()

Traced Logging

logger := otello.TracedLogger(ctx, baseLogger)
logger.Info().Msg("processing request") // includes trace_id, span_id, user_id, tenant_id