Telemetry events emitted by Firkin.

Firkin emits a single span per HTTP request routed through Firkin.Plug. Attach handlers in your application start callback using &Module.function/4 captures — not anonymous functions — so the runtime can hot-reload your code.

:telemetry.attach_many(
  "my-firkin-handler",
  [
    [:firkin, :request, :start],
    [:firkin, :request, :stop],
    [:firkin, :request, :exception]
  ],
  &MyApp.FirkinTelemetry.handle_event/4,
  %{}
)

Events

[:firkin, :request, :start]

Emitted when a request enters Firkin.Plug.

• Measurements: %{monotonic_time, system_time}
• Metadata:
  • :method — HTTP method (e.g. "GET")
  • :request_path — request path as seen by the plug
  • :request_id — value placed in the X-Amz-Request-Id response header
  • :telemetry_span_context — reference correlating start/stop/exception

[:firkin, :request, :stop]

Emitted when the request completes (including handled error responses).

• Measurements: %{monotonic_time, duration} (duration in native units)
• Metadata: all start metadata plus
  • :operation — one of the operation atoms listed below, or :unknown
  • :bucket — bucket name or nil (service-level requests)
  • :key — object key or nil
  • :status — HTTP status code on the response
  • :access_key_id — authenticated key id, or nil if auth failed
  • :error_code — S3 error code atom when the response was an error, otherwise nil

[:firkin, :request, :exception]

Emitted when an unhandled exception escapes request dispatch. The plug still sends a 500 InternalError response to the client.

• Measurements: %{monotonic_time, duration}
• Metadata: all start metadata plus the fields described for :stop (best-effort — :operation may be :unknown if the exception happened before classification) and

  • :kind — :error | :exit | :throw

  • :reason — the raised term
  • :stacktrace — the captured stacktrace

Operation atoms

The :operation metadata is one of:

• :list_buckets
• :create_bucket, :delete_bucket, :head_bucket, :get_bucket_location
• :list_objects_v2, :list_multipart_uploads
• :get_object, :head_object, :put_object, :delete_object, :delete_objects, :copy_object
• :create_multipart_upload, :upload_part, :complete_multipart_upload, :abort_multipart_upload, :list_parts
• :unknown — request did not match any recognised S3 operation