Config-Driven Observability for Go. Events In, Telemetry Out.
Bridge capitan events to OpenTelemetry logs, metrics, and traces with declarative YAML configuration. Change what you observe without recompiling.
Get Startedimport "github.com/zoobz-io/aperture"
// Create aperture with OTEL providers
ap, _ := aperture.New(cap, logProvider, meterProvider, traceProvider)
// Apply a schema — events become telemetry
ap.Apply(aperture.Schema{
Logs: aperture.LogSchema{
Whitelist: []string{"order.created", "order.failed"},
},
Metrics: []aperture.MetricSchema{
{Signal: "order.created", Type: "counter", Name: "orders_total"},
{Signal: "order.completed", Type: "histogram", Name: "order_duration_ms", Field: "duration"},
},
Traces: []aperture.TraceSchema{
{Start: "order.started", End: "order.completed", Name: "process_order", Correlation: "order_id"},
},
})
// Direct OTEL access when needed
logger := ap.Logger("checkout")
meter := ap.Meter("checkout")
tracer := ap.Tracer("checkout")Why Aperture?
Separate domain events from observability configuration entirely.
Three Signals, One Stream
A single capitan event becomes OTEL logs, metrics, and traces based on schema rules. No instrumentation in application code.
Schema-Driven Configuration
Define what gets observed in YAML or JSON. Change observability rules without recompiling — pair with flux for live reload.
Automatic Trace Correlation
Pair start and end events by correlation key into complete spans. Handles out-of-order delivery using emission timestamps.
Whitelist Log Filtering
Default logs everything; whitelist mode narrows to specific signals. Event fields become log attributes automatically.
Four Metric Instruments
Counter, gauge, histogram, and up-down counter. Map any event field to the right instrument type declaratively.
Context Extraction
Pull request-scoped values from context.Context into attributes. User ID, tenant, region — available across all three signal types.
Capabilities
Transform domain events into production-grade telemetry with declarative configuration.
| Feature | Description | Link |
|---|---|---|
| Log Transformation | Events become OTEL log records with automatic attribute mapping. Whitelist filtering and custom type JSON serialization. | Logs |
| Metric Collection | Counter increments, gauge snapshots, histogram distributions, and bidirectional counting from event fields. | Metrics |
| Trace Correlation | Start/end event pairs linked by correlation key become complete spans. Configurable timeout with out-of-order support. | Traces |
| Context Values | Extract context.Context values as OTEL attributes with cardinality-aware registration across logs, metrics, and traces. | Context |
| Schema Configuration | File-based YAML/JSON configuration with validation. Hot-reload via Apply() for atomic observability updates. | Schema |
| Testing Utilities | In-memory OTEL exporters for verifying log records, metric data points, and span attributes in unit tests. | Testing |
Articles
Browse the full aperture documentation.