The files feature emits :telemetry events for
the lifecycle of file download requests. Event definitions live in
Edgehog.Files.Telemetry (lib/edgehog/files/telemetry.ex); the Prometheus
mapping lives in Edgehog.Files.PromExPlugin
(lib/edgehog/files/prom_ex_plugin.ex).
See the observability overview for how to attach handlers and for the identifier cardinality options.
Events
Both lifecycles follow the start/stop convention. start measurements are
%{count: 1, system_time: System.system_time()}; stop measurements are
%{count: 1, duration: duration, retries: retries} with duration in native time
units. stop metadata adds result (:ok or :error), reason, duration,
and duration_unit (:native).
File download requests
| Event | Emitted when | Measurements | Metadata |
|---|---|---|---|
[:edgehog, :files, :file_download_request, :start] | The file download request provisioner (lib/edgehog/files/file_download_request/provisioner/core.ex) starts provisioning a download | count, system_time | transfer_type (:download), destination_type, progress_tracked, needs_encoding, started_at, tenant, plus, unless files_telemetry_include_identifiers is false, request_id, device_id, file_id |
[:edgehog, :files, :file_download_request, :stop] | The download request terminates, successfully or not | count, duration, retries | Start metadata plus result, reason (the provisioning outcome, e.g. :ready or :already_ready, or the failure reason), duration, duration_unit |
File upload requests*
The file_upload_request_started/1, file_upload_request_completed/5, and
file_upload_request_failed/5 functions and the corresponding PromEx metrics
exist, with the same shape as the download events (transfer_type: :upload,
source_type instead of destination_type, identifiers request_id and
device_id) The tables below document the events as defined so consumers and
future emitters stay consistent:
| Event | Measurements | Metadata |
|---|---|---|
[:edgehog, :files, :file_upload_request, :start] | count, system_time | transfer_type (:upload), source_type, progress_tracked, needs_encoding, started_at, tenant, plus, unless identifiers are disabled, request_id, device_id |
[:edgehog, :files, :file_upload_request, :stop] | count, duration, retries | Start metadata plus result, reason, duration, duration_unit |
Prometheus metrics
Edgehog.Files.PromExPlugin exposes two event-metric groups. Identifier labels
(request_id, device_id, file_id) are only present when
files_telemetry_include_identifiers is true (the default).
Download (:files_file_download_request_event_metrics)
| Metric | Type | Source event / measurement |
|---|---|---|
edgehog_files_file_download_request_started_total | counter | download start, count. Labels: destination_type, request_id, device_id, file_id, tenant_slug |
edgehog_files_file_download_request_completed_total | counter | download stop, count. Labels: as above plus result, reason |
edgehog_files_file_download_request_duration_seconds | distribution | download stop, duration (converted to seconds). Labels: destination_type, device_id, result, reason, tenant_slug. Buckets: 100ms–60s |
edgehog_files_file_download_request_retries | last value | download stop, retries. Labels: destination_type, device_id, result, tenant_slug |
Upload (:files_file_upload_request_event_metrics)
| Metric | Type | Source event / measurement |
|---|---|---|
edgehog_files_file_upload_request_started_total | counter | upload start, count. Labels: source_type, request_id, device_id, tenant_slug |
edgehog_files_file_upload_request_completed_total | counter | upload stop, count. Labels: as above plus result, reason |
edgehog_files_file_upload_request_duration_seconds | distribution | upload stop, duration (converted to seconds). Labels: source_type, device_id, result, reason, tenant_slug. Buckets: 100ms–60s |
edgehog_files_file_upload_request_retries | last value | upload stop, retries. Labels: source_type, device_id, result, tenant_slug |
Note the asymmetry with containers: retries are a last_value gauge here versus
a distribution for container provisioning.