Plan for Factorio Prometheus monitoring mod

factorio-prometheus-monitoring-mod.md

Factorio Prometheus Monitoring Mod

Plan for Factorio mod which allows the game state to be monitored by Promtheus.

Table Of Contents

• Overview
• Mod Components
  • Base Stations
  • Sensors
  • Alerts
• Design

Overview

This mod will emulate a real world factory monitoring setup. Where each part of the factory can be scanned for different metrics. And these metrics can be sent back to a server to be viewed, analysed, and alerted on.

In game components can be placed to scan specific properties of entities. These will report back to a Prometheus metrics server.

Mod Components

Metrics will be collected by sensors. Sensors will send information back to a base station. The base station will send information to Prometheus.

Base Stations

Base stations are used to group sensors by area.

For example one may have a separate base station for their iron smelting setup, iron mine, red science factory, oil processing setup, ect.

In practice base stations do nothing more than add a base_station label to metrics sent by connected sensors. They do not actually receive signals or events in the game code.

There are 2 in game items which relate to base stations:

• Base station
  • Name can be set
• Base station repeater: Used to extend coverage area
  • Target base station can be set

Sensors

Sensors collection metrics about in game entities to send back to Prometheus.

A sensor must be connected to a base station to work.

Sensors must be placed in the game to gather information. There are several types of sensors:

• Belt sensor
  • Place adjacent to belt
  • Measures a single belt's:
    • Flow rate
    • Material
    • Total count
    • Health
• Train sensor
  • A small train car
  • Measures:
    • Contents of all Train cars
    • Speed
    • Fuel status
    • Current station
    • Health
• Slot sensor
  • Place adjecent to an entity with any type of slot
    • ex: Turret, factory, furnace, chest, ect
  • Measures:
    • Input slot & output slot:
      • Material type(s)
      • Total count
      • Rate
      • Material type
      • Total count
      • Rate
    • Health

Alerts

Prometheus alerts can be configured to send messages to the game chat.

This will be done via a sidecar Go server which will recieve alert webhook
calls from Prometheus and send then via HTTP socket to a Lua Factorio component which will then display them in game chat.

Design

Metrics will be updated every 10 seconds. Not all sensors will be read every 10 seconds.

Sensors will be placed evenly into read groups.

There will be 10 read groups. Each read group will read its sensors at a specific time offset (Ex: read group 1 will read at seconds 11, 21, 31, ect. Read group 2 at seconds 2, 12, 22, 32, ect).

This should help distrubute the CPU load of looking at tons of sensors and hopefully not impact game perfomance.

Depending on how well Lua in Factorio perfoms metric will either be sent:

• After they are read in a read group
• After all read groups have been read

Depending on Lua performance in Factorio metrics will be sent via:

• A HTTP socket to a sidecar server
  • Exported to Prometheus via a custom Go server using the Prometheus Go client library
• A log file
  • Exported using a Fluentd like process to Prometheus

Outstanding Problems

• How many sensors?
  • Should 1 sensor be linked to 1 entity?
  • Or multiple entities of the same type?
• Power lines?
  • Maybe data should be transmitted to base stations over power lines
  • As long as there is a path from a sensor to the base station via some power line route
  • Should sensors require power?

I happened across this while looking for an existing solution (promfacto seems to be the only one, and it doesn't do quite what I was looking for). If you're interested in this project still, I'd love to collaborate.