Telemetry

Copy Markdown View Source

Foundation.Telemetry provides lightweight wrappers around :telemetry for emitting events and measuring function execution time. It optionally integrates with TelemetryReporter for forwarding events to external systems.

Emitting Events

alias Foundation.Telemetry

Telemetry.execute(
  [:my_app, :request, :complete],
  %{count: 1, bytes: 4096},
  %{status: 200, path: "/api/users"}
)

Measuring Duration

measure/3 times a function and emits a [:stop] event on success or an [:exception] event on failure:

result = Telemetry.measure(
  [:my_app, :db, :query],
  %{table: :users},
  fn -> Repo.all(User) end
)

This emits [:my_app, :db, :query, :stop] with %{duration: microseconds} on success, or [:my_app, :db, :query, :exception] on failure (then re-raises).

Custom Time Units

Telemetry.measure(
  [:my_app, :process],
  %{},
  fn -> expensive_work() end,
  time_unit: :millisecond
)

Reporter Integration

If the optional telemetry_reporter package is available, Foundation can start reporters and attach handlers:

# Start a reporter
{:ok, reporter} = Telemetry.start_reporter(
  name: :my_reporter,
  transport: MyTransport
)

# Attach handlers that forward telemetry events to the reporter
{:ok, handler_id} = Telemetry.attach_reporter(
  reporter: reporter,
  events: [[:my_app, :request, :complete]]
)

# Log directly
Telemetry.log(reporter, "api_call", %{status: 200}, :info)

# Detach when done
Telemetry.detach_reporter(handler_id)

If telemetry_reporter is not installed, these functions return {:error, :missing_dependency}.