# LitmusEdge 4.0.x API Documentation/DeviceHub/DeviceHub Prometheus Metrics - LE, LEM, LUNS API Docs ## Prometheus Metrics **GET** `{{edgeUrl}}/devicehub/metrics` # Prometheus Metrics Returns DeviceHub runtime metrics in the [Prometheus exposition format](https://prometheus.io/docs/instrumenting/exposition_formats/). Suitable for direct Prometheus scraping, ad-hoc `curl` inspection, or any client that understands the text-based exposition format. The response is `text/plain` with no streaming, no compression by default, and no pagination. One scrape returns the complete snapshot of every metric for every device. ## Endpoint ```http GET {{edgeUrl}}/devicehub/metrics ``` ## Authentication HTTP Basic Auth. **Username** is your API token, **password** is empty. Tokens are managed under `System > Access Control > Tokens`. ## Parameters None. ## Response `200 OK` -- `text/plain; version=0.0.4`. Standard Prometheus exposition. Each metric is preceded by `# HELP` and `# TYPE` lines, then one line per labelled series. All metrics carry `id` (device UUID) and `name` (device name with spaces replaced by `_`). ### Metric reference | Metric | Type | Description | |---------------------------------|-----------|------------------------------------------------------------------------------------------------------------------------| | `edge_dh_device_online_status` | gauge | `1` when the device's worker reports a healthy upstream connection, `0` otherwise. Mirrors `Device Connection Status`. | | `edge_dh_device_tags` | gauge | Count of registers (tags) currently configured on the device. Same value as `List Registers from Single Device > TotalCount`. | | `edge_dh_failed_tags` | counter | Total number of register reads that have failed since the DeviceHub service started. Resets on service restart. | | `edge_dh_processed_tags` | counter | Total number of register reads that have succeeded since the DeviceHub service started. Resets on service restart. | ### Example response (truncated) ```text # HELP edge_dh_device_online_status # TYPE edge_dh_device_online_status gauge edge_dh_device_online_status{id="41FBD12E-C6CD-4539-AD50-336D278B207C",name="Rack_2b_M258"} 1 edge_dh_device_online_status{id="474E42B0-C7B8-42DE-8DE2-FFED7030A563",name="DTA_windows_tia"} 0 # HELP edge_dh_device_tags # TYPE edge_dh_device_tags gauge edge_dh_device_tags{id="41FBD12E-C6CD-4539-AD50-336D278B207C",name="Rack_2b_M258"} 1 edge_dh_device_tags{id="779F42F3-54FC-4A87-B9A6-CD39CFA4A97D",name="Simulator2"} 4 # HELP edge_dh_failed_tags # TYPE edge_dh_failed_tags counter edge_dh_failed_tags{id="41FBD12E-C6CD-4539-AD50-336D278B207C",name="Rack_2b_M258"} 14 edge_dh_failed_tags{id="4C4B9CCC-F5E4-4C2E-A4C0-EAF5C32B0D1A",name="AB_CLX_API_testing"} 2.080253e+06 # HELP edge_dh_processed_tags # TYPE edge_dh_processed_tags counter edge_dh_processed_tags{id="41FBD12E-C6CD-4539-AD50-336D278B207C",name="Rack_2b_M258"} 2.774419e+06 edge_dh_processed_tags{id="89C52E9A-0901-4D8D-B842-7B533F64E1B7",name="ClassificationSimulator"} 2.2195712e+07 ``` Large counters are exposed in scientific notation (`2.080253e+06`) which Prometheus parses natively. ## Useful PromQL recipes ```promql # Devices currently offline edge_dh_device_online_status == 0 # Per-device read failure rate over 5m rate(edge_dh_failed_tags[5m]) # Per-device read success rate over 5m rate(edge_dh_processed_tags[5m]) # Tag-read success ratio rate(edge_dh_processed_tags[5m]) / (rate(edge_dh_processed_tags[5m]) + rate(edge_dh_failed_tags[5m])) # Total tags per device, ranked topk(10, edge_dh_device_tags) ``` ## Scrape configuration ```yaml scrape_configs: - job_name: 'litmusedge-devicehub' scheme: https tls_config: insecure_skip_verify: true metrics_path: /devicehub/metrics basic_auth: username: '' password: '' static_configs: - targets: ['10.17.8.42'] ``` Use a non-`insecure_skip_verify` config in production: install the device CA in your Prometheus container or mount it via `tls_config.ca_file`. ## Errors | HTTP status | When it happens | |---------------------|--------------------------------------------------------------------------------| | `400 Bad Request` | Missing or malformed query/body parameter. | | `401 Unauthorized` | Missing or invalid credentials. | | `403 Forbidden` | Token lacks permission for this operation. | | `404 Not Found` | Target entity does not exist. | | `5xx` | Service is unreachable, restarting, or internally errored. Inspect device logs under `System > Support`. | ### Scrape-specific notes - A `401` on scrape usually means the API token expired or was rotated. Update `basic_auth.username` and reload Prometheus. - The endpoint does not implement HTTP conditional GETs (`If-None-Match`, `If-Modified-Since`); every scrape returns a full snapshot. - For multi-device deployments, scrape each LE host as its own target rather than aggregating client-side -- it preserves the per-device labels for cross-device alerts. > **TLS note**: edge devices use a self-signed certificate by default. Either install the device CA in your client trust store or disable certificate verification when calling this endpoint directly. ### Response **Status**: 200 OK ```plain # HELP edge_dh_device_online_status # TYPE edge_dh_device_online_status gauge edge_dh_device_online_status{id="22416E46-4830-4A00-8BFD-45B2CB9978E1",name="apiTestDevice"} 1 edge_dh_device_online_status{id="41FBD12E-C6CD-4539-AD50-336D278B207C",name="Rack_2b_M258"} 1 edge_dh_device_online_status{id="474E42B0-C7B8-42DE-8DE2-FFED7030A563",name="DTA_windows_tia"} 0 edge_dh_device_online_status{id="4C4B9CCC-F5E4-4C2E-A4C0-EAF5C32B0D1A",name="AB_CLX_API_testing"} 0 edge_dh_device_online_status{id="779F42F3-54FC-4A87-B9A6-CD39CFA4A97D",name="Simulator2"} 1 edge_dh_device_online_status{id="89C52E9A-0901-4D8D-B842-7B533F64E1B7",name="ClassificationSimulator"} 1 edge_dh_device_online_status{id="BAFD349E-21B6-408A-AE2F-B9C682912571",name="Boiler"} 0 edge_dh_device_online_status{id="CDC283FB-72E2-42DF-A587-4D6299D70C9A",name="sim1"} 1 # HELP edge_dh_device_tags # TYPE edge_dh_device_tags gauge edge_dh_device_tags{id="22416E46-4830-4A00-8BFD-45B2CB9978E1",name="apiTestDevice"} 0 edge_dh_device_tags{id="41FBD12E-C6CD-4539-AD50-336D278B207C",name="Rack_2b_M258"} 1 edge_dh_device_tags{id="474E42B0-C7B8-42DE-8DE2-FFED7030A563",name="DTA_windows_tia"} 0 edge_dh_device_tags{id="4C4B9CCC-F5E4-4C2E-A4C0-EAF5C32B0D1A",name="AB_CLX_API_testing"} 1 edge_dh_device_tags{id="779F42F3-54FC-4A87-B9A6-CD39CFA4A97D",name="Simulator2"} 4 edge_dh_device_tags{id="89C52E9A-0901-4D8D-B842-7B533F64E1B7",name="ClassificationSimulator"} 8 edge_dh_device_tags{id="BAFD349E-21B6-408A-AE2F-B9C682912571",name="Boiler"} 0 edge_dh_device_tags{id="CDC283FB-72E2-42DF-A587-4D6299D70C9A",name="sim1"} 2 # HELP edge_dh_failed_tags # TYPE edge_dh_failed_tags counter edge_dh_failed_tags{id="22416E46-4830-4A00-8BFD-45B2CB9978E1",name="apiTestDevice"} 0 edge_dh_failed_tags{id="41FBD12E-C6CD-4539-AD50-336D278B207C",name="Rack_2b_M258"} 14 edge_dh_failed_tags{id="474E42B0-C7B8-42DE-8DE2-FFED7030A563",name="DTA_windows_tia"} 0 edge_dh_failed_tags{id="4C4B9CCC-F5E4-4C2E-A4C0-EAF5C32B0D1A",name="AB_CLX_API_testing"} 2.080253e+06 edge_dh_failed_tags{id="779F42F3-54FC-4A87-B9A6-CD39CFA4A97D",name="Simulator2"} 0 edge_dh_failed_tags{id="89C52E9A-0901-4D8D-B842-7B533F64E1B7",name="ClassificationSimulator"} 0 edge_dh_failed_tags{id="BAFD349E-21B6-408A-AE2F-B9C682912571",name="Boiler"} 0 edge_dh_failed_tags{id="CDC283FB-72E2-42DF-A587-4D6299D70C9A",name="sim1"} 0 # HELP edge_dh_processed_tags # TYPE edge_dh_processed_tags counter edge_dh_processed_tags{id="22416E46-4830-4A00-8BFD-45B2CB9978E1",name="apiTestDevice"} 0 edge_dh_processed_tags{id="41FBD12E-C6CD-4539-AD50-336D278B207C",name="Rack_2b_M258"} 2.774419e+06 edge_dh_processed_tags{id="474E42B0-C7B8-42DE-8DE2-FFED7030A563",name="DTA_windows_tia"} 0 edge_dh_processed_tags{id="4C4B9CCC-F5E4-4C2E-A4C0-EAF5C32B0D1A",name="AB_CLX_API_testing"} 0 edge_dh_processed_tags{id="779F42F3-54FC-4A87-B9A6-CD39CFA4A97D",name="Simulator2"} 1.1097856e+07 edge_dh_processed_tags{id="89C52E9A-0901-4D8D-B842-7B533F64E1B7",name="ClassificationSimulator"} 2.2195712e+07 edge_dh_processed_tags{id="BAFD349E-21B6-408A-AE2F-B9C682912571",name="Boiler"} 0 edge_dh_processed_tags{id="CDC283FB-72E2-42DF-A587-4D6299D70C9A",name="sim1"} 5.548928e+06 ``` ---