sentiero-cr

Crystal reporter shard for Sentiero — reports exceptions and custom events from Crystal/Marten apps to a Sentiero ingest server over HTTP. Mirrors the Ruby sentiero gem's reporter against the Plan 2 wire protocol.

Installation

Add to shard.yml:

dependencies:
  sentiero:
    github: stevegeek/sentiero-cr

Then shards install.

Configuration

require "sentiero"

Sentiero::Reporter.configure do |c|
  c.endpoint    = "https://ingest.example.com"   # Sentiero ingest base URL
  c.ingest_key  = ENV["SENTIERO_INGEST_KEY"]      # per-project bearer key
  c.project     = "my-app"                        # project identifier
  c.environment = "production"                    # e.g. "production", "staging"
  c.release     = "v1.2.3"                        # optional release tag

  # Async delivery (default: true, max_queue: 100 — drop-on-full, never blocks caller)
  c.async     = true
  c.max_queue = 200

  # HTTP timeouts (seconds)
  c.open_timeout = 2.0
  c.read_timeout = 3.0

  # Extra keys to scrub from context/payload (default list covers password, token, etc.)
  c.filter_keys = ["my_secret_field"]
end

Usage

Report an exception

begin
  do_something_risky
rescue ex
  Sentiero::Reporter.notify(ex)
end

With extra context:

Sentiero::Reporter.notify(
  ex,
  context:    {"user_id" => user.id.to_s, "plan" => "pro"},
  session_id: sid,    # links to the Sentiero session
  window_id:  wid,    # links to the Sentiero window
)

Track a custom event

Sentiero::Reporter.track(
  "signup",
  level:      "info",
  session_id: sid,
  payload:    {"plan" => "pro", "referrer" => "google"},
)

notify and track never raise into the caller — all delivery errors are swallowed and logged to STDERR.

Client-side scrubbing

Values whose key matches a known sensitive pattern (case-insensitive substring — password, token, secret, authorization, api_key, etc.) are replaced with [FILTERED] before the payload leaves the process. Add c.filter_keys for app-specific keys.

Marten middleware (optional)

For Marten apps: require "sentiero/marten" and add the middleware to your settings. The middleware catches unhandled exceptions, reads the session/window id cookies for linkage, reports to Sentiero, then re-raises so Marten's own error handling still fires.

# config/settings/base.cr
require "sentiero/marten"

Marten.configure do |config|
  config.middleware = [
    # ... your existing middleware ...
    Sentiero::Reporter::Middleware,
  ]
end

Cookie linkage

The middleware reads two cookies to link errors to Sentiero browser sessions:

These are set by the Sentiero JavaScript recorder in the browser.

Wire protocol

Compatible with Plan 2:

• POST <endpoint>/errors — exception payloads
• POST <endpoint>/track — custom event payloads
• Authorization: Bearer <ingest_key> header on every request
• project is NOT included in the body (server derives it from the key)

License

MIT