Telemetry integration for LatticeStripe.

LatticeStripe emits :telemetry events for all HTTP requests and webhook signature verification. Attach handlers to these events to integrate with your observability stack (Prometheus, DataDog, OpenTelemetry, etc.).

HTTP Request Events

[:lattice_stripe, :request, :start]

Emitted before each HTTP request is dispatched.

Measurements:

Metadata:

[:lattice_stripe, :request, :stop]

Emitted after each HTTP request completes (success or API error).

Measurements:

Metadata (all start fields plus):

[:lattice_stripe, :request, :exception]

Emitted when an uncaught exception or throw escapes the request function. This covers transport-level bugs, not API errors (which produce [:lattice_stripe, :request, :stop] with status: :error). Handled automatically by :telemetry.span/3.

Measurements:

Metadata:

[:lattice_stripe, :request, :retry]

Emitted for each retry attempt before the retry delay sleep.

Measurements:

Metadata:

Webhook Verification Events

[:lattice_stripe, :webhook, :verify, :start]

Emitted before webhook signature verification begins.

Measurements:

Metadata:

[:lattice_stripe, :webhook, :verify, :stop]

Emitted after webhook signature verification completes.

Measurements:

Metadata:

[:lattice_stripe, :webhook, :verify, :exception]

Emitted when an uncaught exception escapes webhook verification. Handled automatically by :telemetry.span/3.

Measurements:

Metadata:

Usage with Telemetry.Metrics

If you're using telemetry_metrics with Prometheus or StatsD, here are ready-to-use metric definitions:

[
  # Request latency by resource and operation
  Telemetry.Metrics.summary("lattice_stripe.request.stop.duration",
    tags: [:resource, :operation, :status],
    unit: {:native, :millisecond}
  ),

  # Request throughput by outcome
  Telemetry.Metrics.counter("lattice_stripe.request.stop",
    tags: [:resource, :operation, :status]
  ),

  # Latency distribution (p50/p95/p99)
  Telemetry.Metrics.distribution("lattice_stripe.request.stop.duration",
    tags: [:resource, :operation],
    unit: {:native, :millisecond}
  ),

  # Retry rate by error type
  Telemetry.Metrics.counter("lattice_stripe.request.retry",
    tags: [:error_type]
  ),

  # Webhook verification outcomes
  Telemetry.Metrics.counter("lattice_stripe.webhook.verify.stop",
    tags: [:result, :error_reason]
  )
]

Invoice Auto-Advance Events

[:lattice_stripe, :invoice, :auto_advance_scheduled]

Emitted after a successful Invoice.create/3 when the returned invoice has auto_advance: true. This signals that Stripe will automatically finalize the draft invoice after approximately 1 hour. Attach a handler to log a warning or trigger a monitoring alert when auto-advance invoices are created.

Measurements:

Metadata:

Attaching a Default Logger

For instant visibility during development or to log all Stripe requests in production, use attach_default_logger/1:

# In your application start/2:
LatticeStripe.Telemetry.attach_default_logger()

# Or with options:
LatticeStripe.Telemetry.attach_default_logger(level: :debug)

This logs one line per request in the format:

[info] POST /v1/customers => 200 in 145ms (1 attempt, req_abc123)
[warn] GET /v1/payment_intents/pi_123 => :error in 301ms (3 attempts, connection_error)
[warning] Invoice in_123 (customer: cus_456) has auto_advance: true — Stripe will auto-finalize in ~1 hour

Converting Duration

The :duration measurement is in native time units. Convert to milliseconds:

duration_ms = System.convert_time_unit(duration, :native, :millisecond)