ForgeOpsTracker (forge_ops_tracker v0.1.0)

Copy Markdown View Source

Elixir error reporting client for a private, self-hosted ForgeOps tracker instance:

ForgeOpsTracker.init(dsn: "https://<api_key>@your-forgeops-host/api/v1/events")
ForgeOpsTracker.install_handlers()

See the module docs on ForgeOpsTracker.LoggerHandler for what install_handlers/0 actually covers (every process crash anywhere in the whole BEAM VM, via :logger -- a meaningfully stronger automatic-capture story than any single-thread uncaught-exception hook) and capture_exception/3 for reporting one you've already rescued yourself.

Summary

Functions

capture_exception(reason, stacktrace, context \\ %{})

Report an exception (or any raised/thrown term -- see ForgeOpsTracker.EventBuilder's own doc for why this doesn't require a real Exception struct) you've already rescued yourself

init(opts \\ [])

Configures the client. Call once at startup -- application.ex's own start/2, before the rest of your supervision tree starts, is the natural place. Accepts the same keys as ForgeOpsTracker.Configuration's struct fields

install_handlers()

Installs the :logger handler described in ForgeOpsTracker.LoggerHandler's own module doc. Call once, after init/1. Safe to call more than once -- a later call is a no-op.

Functions

capture_exception(reason, stacktrace, context \\ %{})

@spec capture_exception(term(), Exception.stacktrace(), map()) :: :ok

Report an exception (or any raised/thrown term -- see ForgeOpsTracker.EventBuilder's own doc for why this doesn't require a real Exception struct) you've already rescued yourself:

try do
  charge_card(order)
rescue
  e ->
    ForgeOpsTracker.capture_exception(e, __STACKTRACE__, %{order_id: order.id})
    reraise e, __STACKTRACE__
end

stacktrace has to come from the actual rescue/catch site (__STACKTRACE__) -- unlike languages where an exception object carries its own trace, Elixir's stacktrace is only available via that special form, and only for as long as nothing else has run since the rescue/catch (the same reason the example above captures it before doing anything else).

init(opts \\ [])

@spec init(keyword()) :: ForgeOpsTracker.Configuration.t()

Configures the client. Call once at startup -- application.ex's own start/2, before the rest of your supervision tree starts, is the natural place. Accepts the same keys as ForgeOpsTracker.Configuration's struct fields:

ForgeOpsTracker.init(dsn: "...", environment: "production")

Fields not passed here fall back to Application.get_env(:forge_ops_tracker, key) / FORGE_OPS_DSN-style environment variables read when this app started -- see ForgeOpsTracker.Configuration's own module doc.

install_handlers()

@spec install_handlers() :: :ok

Installs the :logger handler described in ForgeOpsTracker.LoggerHandler's own module doc. Call once, after init/1. Safe to call more than once -- a later call is a no-op.