MonitoringPlugin sk SK

MonitoringPlugin

MonitoringPlugin is an official ASF plugin, which allows you to monitor ASF process via Prometheus time-series database.

---

Screenshots

Show

---

Requirements

Due to technical constraints, this plugin requires generic variant of ASF.

---

Enabling the plugin

ASF does not come with MonitoringPlugin bundled by default, however, it's included as optional addition in every ASF release. Download the plugin from the official release that matches your ASF version, then create a dedicated plugins/ArchiSteamFarm.OfficialPlugins.Monitoring directory for the plugin, and finally extract the archive there.

On the next launch of ASF, the logs will indicate that the plugin has been successfully loaded through standard ASF logging mechanism. You can also verify this by navigating to /Api/metrics URL in your IPC interface. If you are using IPC password, you'll need proper authorization, e.g. appending ?password=<YourIPCPassword> to the /Api/metrics URL. The content you see should look similar to below:

# TYPE asf_build_info gauge
# HELP asf_build_info Build information about ASF in form of label values
asf_build_info{variant="source",version="6.0.2.5"} 1 1713715703686

# TYPE asf_runtime_info gauge
# HELP asf_runtime_info Runtime information about ASF in form of label values
asf_runtime_info{framework=".NET 8.0.4",operating_system="Debian GNU/Linux trixie/sid",runtime="linux-x64"} 1 1713715703686
(...)

Metrics regarding ASF and the bots have dedicated prefix asf_ in their name. Other metrics e.g. regarding the .NET runtime or ASF's HttpClient are automatically generated based on universal .NET process rules and do not carry such prefix.

---

Prometheus config

Once you verified the plugin is working correctly, you can add a scrape configuration to your Prometheus instance as such:

scrape_configs:
  - job_name: ArchiSteamFarm
    metric_name_escaping_scheme: underscores # Remove if using Prometheus V2.x - read more below
    metrics_path: /Api/metrics
    params:
      password:
        - YourIPCPassword
    static_configs:
      - targets:
          - 127.0.0.1:1242

Naturally, you need to ensure that your hosted Prometheus instance is able to reach ASF's IPC interface, adapt password and targets accordingly to your usage. If you do not have IPC password set (which is not recommended), you can skip the addition of the params section. In case you're running multiple ASF instances with different IPC passwords, you can add additional scrape configurations, one per instance, as the query parameters can not be set on a per-target basis. Otherwise, you can declare several targets if they share the same password.

---

Grafana dashboard

Once your metrics are gathered by Prometheus, it's possible to use Grafana for visualization. The plugin comes with /grafana-dashboard.json file served by standard IPC mechanisms, so assuming you're running your ASF instance with default settings, you can download it here. Alternatively, you can also grab the JSON file from our repository as well.

---

Prometheus, Grafana dashboard and metrics escaping scheme

ASF supports various metrics escaping schemes since V6.3.8.4, with unified, complete solution starting from V6.3.9.4 (as part of #3607).

This unfortunately causes a slight issue in regards to our Grafana dashboard, since for that to work you need precise metric names as parsed by Prometheus, and that software behaves in two different ways by default depending on whether you use V2.x or V3.x version of it. See UTF-8 Prometheus docs for more info.

While waiting for Prometheus V3.x to get widely adopted (with debian stable as current guideline), we recommend legacy approach, that is:

• Our Grafana dashboard comes with underscore names by default, that are recognized by Prometheus V2.x
• Use metric_name_escaping_scheme: underscores as part of ASF scrape config (as in example above), if using Prometheus V3.x

This is because, while Prometheus V3.x can be easily configured to use the legacy approach, Prometheus V2.x has no such job-specific option to force the new one to be used.

In the future, we'll likely refactor our Grafana dashboard to use the new recommended defaults, and the setting will no longer be required. Today doing that would cause issues for older Prometheus users, which is not warranted.

Of course, the plugin in ASF itself supports all different formatting options, so you can always pick the one you like and adapt the Grafana dashboard to it yourself - we're just making it easier for you with a simple one-line config change recommendation.