leaseweb knowledge base logo - white color on the orange background
leaseweb knowledge base logo - white color on the orange background

Hardware Monitoring Raw Endpoints

< Back

Hardware Monitoring Raw Endpoints

Leaseweb monitors all the dedicated servers via out of band IPMI metrics. Hardware metrics are visible per server in the Customer Portal under Usage → Hardware Monitoring. This works well for a handful of servers. If you run tens or hundreds of servers, opening every server page is not practical. Therefore, Leaseweb provides hardware health metrics of all your dedicated servers via Prometheus-compatible API, which you can pull and plug straight into Grafana, Prometheus or any tool that speaks the Prometheus HTTP API.

Using the API

The base URL is https://api.leaseweb.com/bareMetals/v2/hardwareMonitoring/raw. Under it, the API serves the standard Prometheus HTTP API paths:

PathWhat it returns
/api/v1/queryThe result of a PromQL query at one point in time
/api/v1/query_rangeThe result of a PromQL query for a specified range of time
/api/v1/query_exemplarsReturns a list of exemplars for a valid PromQL query for a specific time range.Supported for compatibility; hardware metrics carry no exemplars, so this returns an empty list.
/api/v1/seriesThe time series that match a selector
/api/v1/labelsAll label names in your data
/api/v1/label/<name>/valuesAll values of one label, for example every server instance

For request parameters, response formats and more examples for each of these paths, see VictoriaMetrics API examples: Reads. When you follow those examples, replace the host with the base URL above and add the X-LSW-Auth header. Only the paths listed in the table above are available through the Leaseweb API.

Connect Grafana

  1. In Grafana, go to Connections → Data sources → Add data source and pick Prometheus.
  2. Set Prometheus server URL to https://api.leaseweb.com/bareMetals/v2/hardwareMonitoring/raw (the base URL, without /api/v1/...).
  3. Under HTTP headers, add a header named X-LSW-Auth with your API key as the value.
  4. Under Other: Use series endpoint: true
  5. Click Save & test.

Query from the command line

Store your API key in an environment variable, then call the API with curl:

export LSW_TOKEN="[YOUR_API_KEY]"
B=https://api.leaseweb.com/bareMetals/v2/hardwareMonitoring/raw

# BMC details of every monitored server
curl -s -H "X-LSW-Auth: $LSW_TOKEN" -G "$B/api/v1/query" \
  --data-urlencode 'query=ipmi_bmc_info'

# All temperature readings above 70 °C right now
curl -s -H "X-LSW-Auth: $LSW_TOKEN" -G "$B/api/v1/query" \
  --data-urlencode 'query=ipmi_temperature_celsius > 70'

# The list of servers (instance label values)
curl -s -H "X-LSW-Auth: $LSW_TOKEN" "$B/api/v1/label/instance/values"

Keep your API key out of scripts you commit to version control; read it from a secrets manager or environment variable instead.

Good to know

  • Refresh rate: metrics are collected every 5 minutes. The API is not suited for second-by-second monitoring.
  • History: metrics are kept for 30 days. To keep longer history, you could store the data on your own equipment.
  • Read-only, no alerting: the API does not send notifications or accept alert rules. Set up alerts in your own tools, for example Grafana alerting or your Prometheus rules, on top of the API.
  • Sensors vary by model: older or entry-level servers expose fewer sensors. A metric that is missing for one server is usually not reported by that server’s BMC.
  • Hardware level only: IPMI sees the physical machine, not your operating system. CPU load, disk usage, memory usage and application metrics are not included.
  • Gaps during maintenance: while a server reboots or its BMC is reset, some readings can be missing for one or more collection rounds.
  • Proxies: if a proxy between your tool and the API adds an X-Real-IP header, the API rejects the request with 401. Remove that header or call the API directly.

Frequently asked questions

Can other customers see my data? No. Each request is tied to your API key, and the API only returns series for servers on your account.

Does this install anything on my server? No. Data is read from the server’s BMC over IPMI using the read-only lswhwmon user. Nothing runs on your operating system.

One of my servers is missing from the results. Why? The lswhwmon IPMI user is most likely missing on that server. Run an IPMI reset from the Customer Portal to create it; data appears after the next collection rounds.

How do I turn monitoring off for a server? Delete the lswhwmon user in the server’s remote management interface. Collection for that server stops.

Grafana says “Save & test” failed. What should I check? Check that the URL ends in /hardwareMonitoring/rawwith no /api/v1 suffix, that the X-LSW-Auth header holds a valid API key, and that no proxy adds an X-Real-IP header.

Can I set alerts in the Customer Portal? Not today. Use the API with your own alerting tools.

Is there a cost? No. Hardware Monitoring and its API are included with your dedicated server.

Back to the top