API Reference

Aperture

Constructor

func New(
    c *capitan.Capitan,
    logProvider log.LoggerProvider,
    meterProvider metric.MeterProvider,
    traceProvider trace.TracerProvider,
) (*Aperture, error)

Creates a new Aperture instance that observes all capitan events.

Parameters:

• c - Capitan instance to observe
• logProvider - OTEL log provider (required)
• meterProvider - OTEL meter provider (required)
• traceProvider - OTEL trace provider (required)

Returns:

• *Aperture - The aperture instance
• error - Initialization errors

Example:

ap, err := aperture.New(cap, logProvider, meterProvider, traceProvider)
if err != nil {
    log.Fatal(err)
}
defer ap.Close()

Methods

Apply

func (s *Aperture) Apply(schema Schema) error

Applies or updates the aperture configuration atomically. Use this for initial configuration and hot-reload scenarios.

Parameters:

• schema - Configuration schema (see Schema)

Returns:

• error - Schema validation errors

Example:

schema := aperture.Schema{
    Metrics: []aperture.MetricSchema{
        {Signal: "order.created", Name: "orders_total", Type: "counter"},
    },
}
err := ap.Apply(schema)

Hot-reload with flux:

capacitor := flux.New[aperture.Schema](
    file.New("config.yaml"),
    func(_, curr aperture.Schema) error {
        return ap.Apply(curr)
    },
)
capacitor.Start(ctx)

RegisterContextKey

func (s *Aperture) RegisterContextKey(name string, key any)

Registers a context key for extraction. Call this before Apply() if your schema uses context extraction.

Parameters:

• name - Name to reference in schema (e.g., "user_id")
• key - Actual Go context key type

Example:

type ctxKey string
const userIDKey ctxKey = "user_id"

ap.RegisterContextKey("user_id", userIDKey)

schema := aperture.Schema{
    Context: &aperture.ContextSchema{
        Logs: []string{"user_id"},
    },
}
ap.Apply(schema)

Logger

func (s *Aperture) Logger(name string) log.Logger

Returns an OTEL logger with the given name.

Meter

func (s *Aperture) Meter(name string) metric.Meter

Returns an OTEL meter with the given name.

Tracer

func (s *Aperture) Tracer(name string) trace.Tracer

Returns an OTEL tracer with the given name.

Close

func (s *Aperture) Close()

Stops observing capitan events. Does NOT shutdown providers.

Schema

Schema is the configuration format for aperture. It can be defined in Go, YAML, or JSON.

type Schema struct {
    Metrics []MetricSchema
    Traces  []TraceSchema
    Logs    *LogSchema
    Context *ContextSchema
    Stdout  bool
}

MetricSchema

type MetricSchema struct {
    Signal      string
    Name        string
    Type        string
    ValueKey    string
    Description string
}

Example:

schema := aperture.Schema{
    Metrics: []aperture.MetricSchema{
        {Signal: "order.created", Name: "orders_total", Type: "counter"},
        {Signal: "request.done", Name: "request_duration_ms", Type: "histogram", ValueKey: "duration"},
        {Signal: "system.cpu", Name: "cpu_usage", Type: "gauge", ValueKey: "percent"},
    },
}

TraceSchema

type TraceSchema struct {
    Start          string
    End            string
    CorrelationKey string
    SpanName       string
    SpanTimeout    string
}

Example:

schema := aperture.Schema{
    Traces: []aperture.TraceSchema{
        {
            Start:          "request.started",
            End:            "request.completed",
            CorrelationKey: "request_id",
            SpanName:       "http_request",
            SpanTimeout:    "1m",
        },
    },
}

LogSchema

type LogSchema struct {
    Whitelist []string
}

Example:

schema := aperture.Schema{
    Logs: &aperture.LogSchema{
        Whitelist: []string{"order.created", "order.failed"},
    },
}

ContextSchema

type ContextSchema struct {
    Logs    []string
    Metrics []string
    Traces  []string
}

Context keys must be registered with RegisterContextKey() before use.

Example:

ap.RegisterContextKey("user_id", userIDKey)
ap.RegisterContextKey("tenant_id", tenantIDKey)

schema := aperture.Schema{
    Context: &aperture.ContextSchema{
        Logs:    []string{"user_id", "tenant_id"},
        Metrics: []string{"tenant_id"},
    },
}

Stdout

type Schema struct {
    // ...
    Stdout bool
}

When true, events are also logged to stdout in addition to OTEL.

Schema Loading

LoadSchemaFromYAML

func LoadSchemaFromYAML(data []byte) (Schema, error)

Parses a YAML configuration into a Schema.

Example YAML:

metrics:
  - signal: order.created
    name: orders_total
    type: counter
  - signal: request.done
    name: request_duration_ms
    type: histogram
    value_key: duration

traces:
  - start: request.started
    end: request.completed
    correlation_key: request_id
    span_name: http_request
    span_timeout: 1m

logs:
  whitelist:
    - order.created
    - order.failed

context:
  logs:
    - user_id
  metrics:
    - tenant_id

stdout: false

LoadSchemaFromJSON

func LoadSchemaFromJSON(data []byte) (Schema, error)

Parses a JSON configuration into a Schema.

Schema.Validate

func (s Schema) Validate() error

Validates schema structure. Called automatically by Apply().

Providers

type Providers struct {
    Log   *sdklog.LoggerProvider
    Meter *sdkmetric.MeterProvider
    Trace *sdktrace.TracerProvider
}

Uses SDK types from go.opentelemetry.io/otel/sdk/{log,metric,trace}.

Shutdown

func (p *Providers) Shutdown(ctx context.Context) error

Shuts down all providers gracefully.

Field Type Handling

Aperture automatically converts capitan field types to OTEL attributes:

Custom field types are automatically JSON serialized to string attributes.