Plugin Agent System Proposal

[svenvg93]

Component

Hub & Agent

Description

After suggestions for monitoring HAProxy #1546 and Internet performance #1079, I've been thinking about how we could support custom monitoring without adding load to the main project.

Proposal

Create a plugin agent template that third parties can use to build custom monitoring agents (Redis, PostgreSQL, HAProxy, Traefik , etc.) that integrate with Beszel.

Host Machine
├── Beszel Agent (port 45876)      ← system metrics
├── Traefik Plugin (port 45877)      ← Traefik metrics
└── HAProxy Plugin (port 45878)    ← haproxy metrics
         │
         └──── All connect to Hub using parent system's token

How it works

1. Template repo - We provide core connection code + a simple Collector interface (Or a Go module?)
2. New plugin_stats collection - Stores plugin data linked to parent system
3. Chart contributions - Plugin developers PR their charts to the main repo

Developer experience

agent.Run(agent.Config{
    ParentToken: os.Getenv("PARENT_TOKEN"),
    PluginType:  "traefik",
    Collector:   &Traefik Collector{},
})

Plugin metrics appear in a dedicated section on the parent system's page.

Hub Changes

New plugin_stats collection

Field	Type	Description
system	relation	Parent system ID
plugin_type	text	Plugin identifier (e.g., "traefik", "haproxy")
stats	json	Flexible metrics data
type	select	Record type (1m, 10m, 20m, 120m, 480m)
created	autodate	Timestamp

Backend modifications

• Agent connection - Accept X-Plugin-Type header, validate against parent system's token
• Data storage - Write plugin data to plugin_stats collection (not system_stats)
• Aggregation - Reuse existing aggregation pattern for plugin stats
• Frontend - New plugin section on system page, fetch from plugin_stats

[henrygd]

Great ideas, thanks!

I haven't used it in a very long time, but this sounds a bit like how Prometheus works with third party exporters. I've been meaning to look further into this because they're standardizing their OpenMetrics spec and it would be cool if we could support at least a subset of it and be compatible with some of the existing exporters. But this would likely require more work than using our own basic spec.

Quick thoughts:

Instead of plugins connecting directly to the hub, maybe they connect and register themselves with the local agent instead. Then the agent grabs metrics from them when necessary and includes it in the larger payload.

To avoid plugin developers needing to create front-end charts, maybe we use a standard interface to specify the chart type and other details. We can also add more chart types.

I'll try to think more about it this weekend and let you know if I come up with any other ideas.

[svenvg93]

Glad to hear you like the idea 😄, Think it would be a great addition to Beszel, while you can still focus on the System monitoring part.

I haven't used it in a very long time, but this sounds a bit like how Prometheus works with third party exporters. I've been meaning to look further into this because they're standardizing their OpenMetrics spec and it would be cool if we could support at least a subset of it and be compatible with some of the existing exporters. But this would likely require more work than using our own basic spec.

I thought about that as well, but it will require indeed more work for us to be able to handle that spec.

Instead of plugins connecting directly to the hub, maybe they connect and register themselves with the local agent instead. Then the agent grabs metrics from them when necessary and includes it in the larger payload.

That is a great idea! it crossed my mind as well, but I tried to avoid touching the Agent part. But If it's easier to use the local agent then thats a better option.

To avoid plugin developers needing to create front-end charts, maybe we use a standard interface to specify the chart type and other details. We can also add more chart types.

I prefer an approach where the developer is responsible for the charts, allowing plugin developers to build visualizations that best suit the data they collect—whether that’s requests per second, bits, or error counts. This also ensures that titles, descriptions, and axes are accurate for the collected data. Additionally, once tabs are in place (#1513), this would allow us to automatically add tabs for the different plugins running on a system.

[Romain-GUILLEMOT]

I like the direction discussed here, and I think it overlaps with something I had in mind.

What is described in this thread makes a lot of sense as a technical foundation for plugin-based monitoring without making the core project heavier.

The part I was imagining is not really a different direction, but more how something like this could maybe evolve on the user and distribution side over time.

For example, if Beszel ever moves further in that modular direction, I could imagine things like

• a frontend page to manage modules
• a UI to list installed or available modules
• support for importing modules from Git repositories or other external sources, so the community could build and share addons
• maybe some features becoming optional modules if that ever makes sense architecturally

The other part I had in mind was the agent side.

Because Beszel aims to stay lightweight, I think it could be interesting one day to support custom agent builds with only the modules needed for a specific machine.

For example, a Proxmox host would not necessarily need the same modules as a Kubernetes node.

This reminds me a little bit of Caddy with xcaddy, where you can build a custom binary with only the modules you want. Not that Beszel should work exactly the same way, just that the modular build idea feels relevant here too.

I could imagine this being exposed in the frontend with a page where users can

• create custom agent builds
• choose which modules are included
• list existing builds
• remove old builds
• check build status
• download generated binaries once compilation is finished

The add host flow could maybe integrate with that later as well, so the UI could let users select one of those custom builds and automatically update the installation command accordingly.

[svenvg93]

I like the idea of the module system, but would that not mean that the user need to rebuild and distributed the agent every time when there is an update, either for the module part or for the "main" agent. This would mean they won't be able to automate updates etc.

[bassiebal]

I've been looking at how LibreNMS and Netdata handle SNMP and maybe there is a middle ground that allows to start small but grow into this plugin system.

The plugin system makes sense for new metric categories that need new UI (Redis, HAProxy, Traefik). But there's a category of devices that report the same metrics Beszel already displays: network equipment, IPMI hosts, NAS devices etc. These just need CPU, memory, disk, network and temperature.

For those, the simpler path is abstracting the collection layer in the agent rather than the display layer in the hub. A provider interface that feeds into the existing Stats struct with local /proc as default and alternatives like SNMP or IPMI selected
via config:

  providers:
    - type: snmp
      address: 192.168.1.1
      community: public
    - type: ipmi
      address: 192.168.1.5
      username: admin
      password: secret

Standard MIBs (IF-MIB, HOST-RESOURCES-MIB) cover CPU, memory, disk and network on any SNMP device. Only temperature needs vendor-specific OIDs, handled by a small built-in profile library keyed on sysObjectID. Adding a new vendor would be a YAML profile, so no new go code and users might in the interim even place the OIDs they are missing in a yaml file next to the agent.

It might be a good starting point for now and it could complement the plugin system proposed here.

[cainmp]

I like this. SNMP by nature is light, and focusing on only the core stats that Beszel already collects, could allow a whole wide range of devices to be added with just one change.

[lukyjay]

Just to add to the benefits of this proposal:

1. Separate containers for GPU vendors would no longer be needed (assuming the GPU metrics could be a plugin)
2. Significant reduction in the work needed from the Beszel team to maintain this software since plugin providers could be third party repos that manage their own issues and dependencies

[infrapitech]

I have another use case for this proposal: monitoring the mail queue.

On my mail servers, the metric I actually need to alert on is the Postfix queue depth (postqueue -p | grep -c "^[0-9A-F]").

This fits the plugin model: a single integer metric, inexpensive to collect, one chart, and a threshold alert.

A thought on the approach suggested by @henrygd (plugins registering with the local agent rather than the hub): this would work very well here, since the collector is just a shell command or a directory count on the same machine.