Buckets.Telemetry (buckets v1.0.0-rc.1)

Telemetry events for Buckets.

This module defines telemetry events that other applications can attach to.

Event Format

Events follow the convention: [:buckets, component, operation, stage]

Events

Cloud Operations

  • [:buckets, :cloud, :insert, :start] - Emitted when a file upload operation starts
  • [:buckets, :cloud, :insert, :stop] - Emitted when a file upload operation completes
  • [:buckets, :cloud, :insert, :exception] - Emitted when a file upload operation raises an exception
  • [:buckets, :cloud, :delete, :start] - Emitted when a file deletion operation starts
  • [:buckets, :cloud, :delete, :stop] - Emitted when a file deletion operation completes
  • [:buckets, :cloud, :delete, :exception] - Emitted when a file deletion operation raises an exception
  • [:buckets, :cloud, :read, :start] - Emitted when a file read operation starts
  • [:buckets, :cloud, :read, :stop] - Emitted when a file read operation completes
  • [:buckets, :cloud, :read, :exception] - Emitted when a file read operation raises an exception
  • [:buckets, :cloud, :load, :start] - Emitted when a file load operation starts
  • [:buckets, :cloud, :load, :stop] - Emitted when a file load operation completes
  • [:buckets, :cloud, :load, :exception] - Emitted when a file load operation raises an exception
  • [:buckets, :cloud, :url, :start] - Emitted when a URL generation operation starts
  • [:buckets, :cloud, :url, :stop] - Emitted when a URL generation operation completes
  • [:buckets, :cloud, :url, :exception] - Emitted when a URL generation operation raises an exception

Adapter Operations

  • [:buckets, :adapter, :put, :start] - Emitted when an adapter put operation starts
  • [:buckets, :adapter, :put, :stop] - Emitted when an adapter put operation completes
  • [:buckets, :adapter, :put, :exception] - Emitted when an adapter put operation raises an exception
  • [:buckets, :adapter, :get, :start] - Emitted when an adapter get operation starts
  • [:buckets, :adapter, :get, :stop] - Emitted when an adapter get operation completes
  • [:buckets, :adapter, :get, :exception] - Emitted when an adapter get operation raises an exception
  • [:buckets, :adapter, :url, :start] - Emitted when an adapter URL generation starts
  • [:buckets, :adapter, :url, :stop] - Emitted when an adapter URL generation completes
  • [:buckets, :adapter, :url, :exception] - Emitted when an adapter URL generation raises an exception
  • [:buckets, :adapter, :delete, :start] - Emitted when an adapter delete operation starts
  • [:buckets, :adapter, :delete, :stop] - Emitted when an adapter delete operation completes
  • [:buckets, :adapter, :delete, :exception] - Emitted when an adapter delete operation raises an exception

Authentication Operations

  • [:buckets, :auth, :token, :fetch, :start] - Emitted when token fetching starts
  • [:buckets, :auth, :token, :fetch, :stop] - Emitted when token fetching completes
  • [:buckets, :auth, :token, :fetch, :exception] - Emitted when token fetching raises an exception
  • [:buckets, :auth, :token, :refresh, :start] - Emitted when token refresh starts
  • [:buckets, :auth, :token, :refresh, :stop] - Emitted when token refresh completes
  • [:buckets, :auth, :token, :refresh, :exception] - Emitted when token refresh raises an exception

Usage

To attach to these events in your application:

:telemetry.attach(
  "my-handler-id",
  [:buckets, :cloud, :insert, :start],
  &MyApp.handle_cloud_insert/4,
  nil
)

def handle_cloud_insert(_event_name, measurements, metadata, _config) do
  # Process the event
  IO.inspect(measurements)
  IO.inspect(metadata)
end

You may attach a default logger handler, if you want basic logs for all telemetry events:

Buckets.Telemetry.attach_default_logger(:debug)

Summary

Functions

Attaches a default structured JSON Telemetry handler for logging.

Undoes Buckets.Telemetry.attach_default_logger/1 by detaching the attached logger.

Emits a telemetry event with the given name, measurements, and metadata.

Default telemetry event handler that logs events.

Wraps a function call with start and stop telemetry events.

Emits a start event and returns a function to emit the corresponding stop event.

Functions

Link to this function

attach_default_logger(opts \\ [])

@spec attach_default_logger(Logger.level() | keyword()) ::
  :ok | {:error, :already_exists}

Attaches a default structured JSON Telemetry handler for logging.

Link to this function

default_handler_id()

Link to this function

detach_default_logger()

@spec detach_default_logger() :: :ok | {:error, :not_found}

Undoes Buckets.Telemetry.attach_default_logger/1 by detaching the attached logger.

Examples

Detach a previously attached logger:

:ok = Buckets.Telemetry.attach_default_logger()
:ok = Buckets.Telemetry.detach_default_logger()

Attempt to detach when a logger wasn't attached:

{:error, :not_found} = Buckets.Telemetry.detach_default_logger()
Link to this function

emit_event(event_name, measurements, metadata)

@spec emit_event([atom()], map(), map()) :: :ok

Emits a telemetry event with the given name, measurements, and metadata.

Link to this function

handle_event(event_name, measurements, metadata, opts)

Default telemetry event handler that logs events.

Link to this function

span(event_prefix, metadata, fun)

@spec span([atom()], map(), (-> result)) :: result when result: any()

Wraps a function call with start and stop telemetry events.

Link to this function

start_event(event_prefix, metadata)

@spec start_event([atom()], map()) :: (map() -> :ok)

Emits a start event and returns a function to emit the corresponding stop event.

This is useful for span-like events where you want to measure the duration of an operation.