Skip to content

Fritz! exporter for prometheus

This is a prometheus exporter for AVM Fritz! home network devices commonly found in Europe. This exporter uses the devices builtin TR-064 API via the fritzconnection python module.

The exporter should work with Fritz!Box and Fritz!Repeater Devices (and maybe others). It actively checks for supported metrics and queries the metrics for all devices configured (Yes, it has multi-device support for all you Mesh users out there.)

It has been tested against an AVM Fritz!Box 7590 (DSL), a Fritz!Box 5690 (fibre), a Fritz!Box 5530 Fiber, a Fritz!Box 6660 Cable (DOCSIS, FRITZ!OS 8.25), a Fritz!Repeater 2400 and a Fritz!WLAN Repeater 1750E. If you have another box and data is missing, please file an issue or PR on GitHub.

Prometheus required

As the scope of this exporter lies on a typical home device, this also means that there are a lot of people interested in it, who may not have had any contact with Prometheus. As a result of this there have been some misunderstandings in the past, how this all works.

To avoid frustration you will need to know this:

You must setup and configure Prometheus separately! If you are running in plain docker or docker-compose there is a docker-compose setup for Prometheus at https://github.com/vegasbrianc/prometheus which also includes Grafana to actually produce dashboards. This may work out of the box or can be used as a starting point.

The whole setup required is:

  • fritz_exporter: connects to your Fritz device, reads the metrics and makes them available in a format Prometheus understands
  • prometheus: connects to the exporter at regular time intervals, reads the data and stores it in its database
  • grafana: connects to prometheus and can query the database of metrics for timeseries and create dashboards from it.

Check out the Quickstart, which will bring up a simple and limited Prometheus, Grafana and exporter setup.

You cannot connect grafana to the exporter directly. This will not work.

Metrics

The following groups of metrics are currently available:

  • Base Information (uptime; model and Fritz!OS version in fritz_device_info)
  • Software Information (update available; its version in fritz_update_info)
  • Connection mode (DSL, fibre, cable, mobile fallback or offline; the access type in fritz_wan_access_type_info)
  • Host table (number of known devices; with host_info enabled, activity and speed of each host by MAC address, and its address, name and connection in fritz_host_info)
  • LAN statistics (Ethernet only)
  • WAN statistics (including the delegated IPv6 prefix)
  • DSL statistics
  • Fibre / GPON statistics (optical levels, SFP/GPON identity, fibre counters)
  • PPP statistics
  • WiFi statistics per band, with SSID and standard in fritz_wifi_info (with wifi_client_info enabled, also signal strength and speed of each client, with band and address in fritz_wifi_client_info)
  • Mesh backhaul links (data rate and state of the links between mesh nodes, read from the mesh master)
  • Provider management channel (TR-069 management server host, periodic inform, managed upgrades; USP controller enable flags, see below)
  • Telephony (number of configured telephone numbers; the numbers themselves are not exported)
  • WAN Layer1 (physical link) statistics, including 64-bit max bitrate for multi-gig links
  • DOCSIS cable channel statistics (auto-detected on cable boxes; power, MER/MSE, corrected/uncorrected errors, latency). On the Fritz!Box 6660 Cable, DOCSIS 3.1 channels report an uncorrected-error counter but no corrected one, so fritz_docsis_corrected_errors_total has no series for them.
  • Shared segment utilization (fritz_cable_segment_*, cable boxes; other boxes report no samples) and per-connection IPv4/IPv6 status, uptime, state and address (fritz_wan_connection_info) via the Fritz!OS REST API
  • Home Automation Devices (switches, heating valves, temperatures, power meters, and battery status; window/door sensors (open/closed) are not yet reported)

USP controllers

USP (User Services Platform, Broadband Forum TR-369) is a protocol that lets a remote party read and change settings of a device. Such a party is called a controller. Fritz!OS 8 lists the configured controllers in the TR-064 service X_AVM-DE_USPController1. When a controller is enabled, the box opens an outgoing connection to it and accepts its management commands.

  • fritz_usp_controller_enabled is 1 when the controller with the given index is enabled and 0 when it is configured but switched off.
  • fritz_usp_myfritz_enabled is 1 when the MyFRITZ controller (AVM's cloud service) is enabled.

On a FRITZ!Box 6660 Cable running FRITZ!OS 8.25 there is one controller, the MyFRITZ service, and both values are 0. The metrics are meant for alerting: a value switching to 1 means a remote party has been allowed to manage the box, which you would only expect after you (or your provider) changed that on purpose. The exporter only reports the flags. Endpoint IDs, host names and credentials are never read or exported.

Exporter self-monitoring

In addition to the Fritz device data above, the exporter reports metrics about its own operation:

  • fritz_device_reachable -- whether a device was reachable during the last scrape (labelled by friendly_name only)
  • fritz_scrapes_total -- number of completed scrape cycles per device
  • fritz_scrapes_timeouts_total -- scrapes skipped because a previous scrape was still in progress when the collector lock deadline was reached
  • fritz_scrapes_failed_total -- scrapes aborted by an unexpected error
  • fritz_read_problem -- 1 while the exporter skips data of a capability (labels capability and level): partial (some values or items could not be read), skipped (the whole capability), or error (a bug in the exporter, please report it). capability="ConnectionMode" stands for the fritz_connection_mode metric. The series disappears when the problem is gone, and is not exported while the device is unreachable. Use it to explain gaps in other metrics, or to alert on them; the log has the details: a warning when a problem appears, an hourly reminder while it lasts (with the time it started) and an info line when it is gone.

The standard prometheus_client process and interpreter metrics (process_*, python_gc_*, python_info) are exposed as well.

If there is any information missing or not displayed on your specific device, please open an issue on GitHub.

Event log

The exporter reads metrics, not the device's event log ("Ereignisse"). For that there is a companion tool, fritz_logextractor (documentation): it reads the event log and writes each new entry once as a JSON line, so a log stack such as Loki or Elasticsearch can keep it across reboots of the box. It brings a Grafana dashboard and example configs for common log collectors.

Known Problems

  • It seems like Fritz!OS does not internally count the packets for the Guest WiFi. So even though those counters are there they are always 0. This seems to be a problem with Fritz!OS and not the exporter. The counters are delivered nontheless, just in case this gets fixed by AVM.
  • On multi-gig fibre (and possibly cable) links the classic fritz_wan_max_bitrate values from GetCommonLinkProperties can be wrong (often stuck at 1000000) because they use a 32-bit field. Prefer fritz_wan_layer1_max_bitrate_bps from GetAddonInfos, which correctly reports e.g. 2.5 Gbit/s / 1.25 Gbit/s.
  • On WAN types that don't support the 64-bit Layer1 max bitrate fields (observed on cable), FRITZ!OS reports NewX_AVM_DE_Layer1DownstreamMaxBitRate64 / NewX_AVM_DE_Layer1UpstreamMaxBitRate64 as an empty string rather than omitting them or returning None. The exporter treats this the same as "not provided" and simply omits fritz_wan_layer1_max_bitrate_bps for that direction/device — it does not indicate a fault, only that this WAN type doesn't expose the field.
  • Fibre / X_AVM-DE_WANFiber gaps observed on FRITZ!Box 5690 (Fritz!OS 8.25): the web UI shows real optical readings, but several TR-064 GetInfo / GetStatistics fields are empty or zero. The exporter still exposes the TR-064 values when present. The Fritz! team has been contacted about these issues:
    • NewOpticalSignalLevel / NewTransmitOpticalLevel stay at 0 while the UI shows real RX/TX power (e.g. about -19.5 dBm / 2.4 dBm). Also seen on a FRITZ!Box 5530 Fiber. When TR-064 reports 0 for both, the exporter reads fritz_fiber_optical_signal_level and fritz_fiber_transmit_optical_level from the web UI page the UI itself uses (data.lua?page=fiberStats). That page holds one value per hour, so these two metrics then change only once an hour and can lag up to an hour behind the link: after a fibre outage they may still show the last good level for that long.
    • NewFiberMode stays at Unknown while the UI reports GPON (ITU G.984)
    • SFP metadata (NewSFPVendor, NewSFPPartNumber, NewSFPSerialNumber, NewSFPType) is empty
    • no TR-064 field for RX wavelength (UI shows 1490 nm; only NewTXWaveLength exists)
    • laser temperature and laser supply voltage exist only in the web UI, not in TR-064
    • GetStatistics RX counters (NewBytesReceived / NewPacketsReceived) and NewConnectionRateDown often stay at 0 while TX side is populated
  • If you receive Fatal Python error: init_interp_main: can't initialize time when running the container you may have to update libseccomp on your Docker host. This issue mainly happens on Raspberry Pi and is triggered by a version of libseccomp2 which is too old. See https://askubuntu.com/questions/1263284/apt-update-throws-signature-error-in-ubuntu-20-04-container-on-arm (Method 2) and https://github.com/pdreker/fritz_exporter/issues/38.
  • On some boxes LAN Packet counters are stuck at 0 even though the box reports the stats as available.
  • Fritz!OS does not allow passwords longer than 32 characters (as of 07.25). If you try to use a longer password, the admin ui will simply discard all characters after the 32nd. The UI will also cut your inserted password down to 32 characters. So you will be able to login in the UI with the long password. The exporter however does not alter your password and requests will result in a 401 Unauthorized error. So please be aware of this limit and choose a suitable password.
  • Collecting HostInfo (disabled by default) can be extremely slow and will cause some load on the device. It works, but it is slow as this feature needs two calls to the Fritz! device for every device it knows which will simply take some time. If you enable this, make sure your Prometheusm scrape_timeouts are set appropriately (30s should be OK for most setups, but you may need to go even higher).

Grafana Dashboards

Two Grafana dashboards come with the exporter, in misc/grafana in the repository. Take them from the tag of the exporter version you run, so they match its metrics, e.g. https://github.com/pdreker/fritz_exporter/tree/fritzexporter-v4.0.0/misc/grafana for 4.0.0; main has the dashboards of the next release. Import them with "Dashboards" -> "New" -> "Import" -> "Upload dashboard JSON file" in Grafana 10 or later, and pick your Prometheus data source and the device at the top.

  • Fritz!Exporter Overview (fritz-exporter-overview.json) shows every metric the exporter has, one row per topic (device, internet, DSL, cable, fibre, LAN, WiFi, mesh, hosts, smart home, provider management), with many kinds of panels. Use it to see what there is and as a starting point for your own dashboards. Rows that do not apply to a device stay empty.
  • Fritz!Exporter Home (fritz-exporter-home.json) shows what is useful every day on one screen: connection, traffic, line usage and quality, devices online, WiFi, mesh and smart home.

Hosts need host_info: true and WiFi clients wifi_client_info: true.

Helm Chart

There is a (rather crude) Helm chart under helm in the repository. It will deploy the exporter and also create a service monitor for Prometheus Operator to automatically scrape the exporter.

Helping out

If your device delivers some metrics which are not yet scraped by this exporter you can either create a Pull Request, which will be gladly accepted ;-)

Alternatively you can use the following commands and the little helper script in the root of this repository to let me know of metrics:

fritzconnection -i <FRITZ-IP> -s # Lists available services
fritzconnection -i <FRITZ-IP> -S <ServiceName> # Lists available action for a service
python -m fritz_export_helper <FRITZ-IP> <USERNAME> <PASSWORD> -s <ServiceName> -a <ActionName> # Will output the data returned from the device in a readable format

If you have found something you need/want, open an issue provide the following infos:

  1. Model of Device (e.g. FritzBox DSL 7590)
  2. ServiceName and ActionName
  3. Output from fritz_export_helper (make sure, there is not secret data, like password or WiFi passwords in there, before sending!)
  4. What output you need/want and a little bit of info of the environment (Cable, DSL, Hybrid LTE Mode, ... whatever might be relevant)

Disclaimer

Fritz! and AVM are registered trademarks of AVM GmbH. This project is not associated with AVM or Fritz other than using the devices and their names to refer to them.

Copyright 2019-2026 Patrick Dreker \<patrick@dreker.de>

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.