Skip to content

Config

Jump to bottom
lukassoo edited this page Sep 29, 2025 · 5 revisions

Config

Configuration files contain settings that allow you to customize how the exporter will work.
If the exporter gets updates and has more settings added they will be automatically added to the file on startup.
Configuration files are written in YAML.

Listen port

In case you want to change the port the exporter application listens on.

   listenPort: <defaultPort>

Every exporter has a different default port.
Keep in mind that if you use the default approach of forwarding ports with a "-p <hostPort>:<containerPort>" that this will affect the container port.

Target device

All exporters contain settings for the device they should export from.

Two fields setup the name and address of a target device:

  • name - The name of the device (will be in the exported metrics)
  • url - The URL address or IP of the device

Examples:

name: ServerPlug
url: 192.168.1.7

name: ServerPlug
url: http://test.mydomain.com

(I have not tested it with a https endpoint but it probably should just work - let me know if it doesn't)

Authentication / Security

All exporters also include authentication settings.

Older (Gen1) devices usually need your username and password since they use basic HTTP auth.

  • username
  • password

Make a secure username + password combo for your device to ensure only you and your exporters have access.

   username: SomeUser
   password: VerySecurePassword

Newer (Gen2+) devices only need the password since they use Digest Authentication.
On the first start or with a missing config file the exporter will generate the appropriate config so you don't have to write any additional settings.

You can leave the password and/or username empty if you are not using authentication but it is highly recommended that you do.

If you leave a shelly device without authentication - anyone on the WiFi/LAN network can just type its address in a browser and do whatever they want with it - including setting their own password and locking you out until you factory reset the device.

There are ways to scan for devices on the network so it's not even a guessing game to get the address.

If you know what you are doing and know how to prevent unauthorized access to the device without needing to setup passwords then you can also leave them empty.

Logs

Logs are essential when troubleshooting or looking for what went wrong.
By default logs are not saved to files to not fill up space unnecessarily and the log level is set to "Information".

These two fields control this behavior:

   logToFile: false
   logLevel: Information

Possible logLevels:

  • Verbose
  • Debug
  • Information
  • Warning
  • Error
  • Fatal

Setting a given level ignores all the lower levels.
The default "Information" level will ignore all Verbose and Debug logs.
As time goes on and issues get found and fixed, the amount of Verbose and Debug logs will most likely increase.
These levels are usually only useful for debugging and looking for issues when the exporter still works.
Warnings and errors are more serious and usually mean something is wrong.

If you have random issues where the exporter seems to not work properly.
It may be a good idea to have a look at the logs and see if there are any errors or warnings that would tell you what the issue is.

If there are none you can try to lower the log level to Debug or even Verbose to see additional information.
Keep in mind that the amount of logs can increase significantly when you do that.
In case you want to save or share the logs you should enable logging to file.

If you open an issue and want to share logs.
Make sure you don't accidentally leak private information through them.
Take a look at it and remove any IP and Authentication information that should not be public.
Alternatively paste only parts of logs or send them to me directly through email or other means of private communication.

Ignores

Each exporter exports different metrics - some have more, some have less.

All exporters allow you to ignore specific metrics if you don't need them.
For example you may not need to know about the state of a unused relay in a power meter.

Ignores are exporter specific and information about them will be in specific exporter sections.

An example from the Shelly Plug:

   ignorePowerMetric: false
   ignoreTemperatureMetric: false
   ignoreRelayStateMetric: true

This config ignores the relay state, leaving only the power and temperature metrics.

Multiple targets

Usually it is recommended to only export a single device from a single exporter.
However, it is possible to define multiple target devices if you want to.

Keep in mind that this will increase latency.
When Prometheus requests the metrics the exporter will need to request them from all target devices.
Currently this process is synchronous - one after the other.

This means that if the latency to one device is 100ms and 50ms for the second.
Prometheus will have to wait ~150ms for a response + latency between the exporter and Prometheus.
If this is something you need to work and it cannot be done by using multiple exporters - let me know.
Asynchronous requests are possible but there will be downsides and other issues when doing so.
Mainly the issue of what happens if one device doesn't respond at all or takes too long.
There would need to be logic for handling this situation.
Currently there is only one timeout time on all requests and Prometheus also has its own timeout logic.

To target multiple devices you simply have to duplicate a target device.
These differ between exporters.

Example single device config for a Shelly Plug:

   logToFile: false
   logLevel: Information
   targets:
   - name: ServerPlug
    url: 192.168.1.10
    username: SomeUser
    password: SomePassword
    ignorePowerMetric: false
    ignoreTemperatureMetric: false
    ignoreRelayStateMetric: true

Example two device config for a Shelly Plug:

   logToFile: false
   logLevel: Information
   targets:
   - name: Plug1
    url: 192.168.1.10
    username: SomeUser
    password: SomePassword
    ignorePowerMetric: false
    ignoreTemperatureMetric: false
    ignoreRelayStateMetric: true
   - name: Plug2
    url: 192.168.1.11
    username: SomeUser
    password: SomePassword
    ignorePowerMetric: false
    ignoreTemperatureMetric: false
    ignoreRelayStateMetric: true

Use old/incorrect metric names

Since version 1.5.0 this is a new setting that defaults to true on existing installations:
(To prevent breaking existing dashboards)

   useOldIncorrectMetricNames: true

New installations default to false and use new/correct metric names with labels.
You can manually set it to false and update your existing dashboards if you want to.

The difference is in the exported metrics.
Old:

   shellyPro3Em_serverRoom_1_current 0.541

New:

   shelly_current_amps{targetName="serverRoom",deviceModel="Pro3Em",phase="1"} 0.541

The new approach with labels is the correct way to do it and allows for much easier filtering/querying across multiple devices.

Clone this wiki locally