insatomcat/insatomcat-exporter repository overview

⁠insatomcat-exporter

A comprehensive Prometheus exporter for monitoring various infrastructure components that lack proper metrics exposure in existing exporters.

⁠Overview

This exporter fills the gaps left by standard exporters (libvirt-exporter, ceph-exporter, etc.) by providing additional metrics that are needed for production monitoring but aren't available elsewhere.

Current metrics:

• QEMU/KVM vhost thread CPU usage via libvirt

Planned metrics:

• Additional libvirt metrics not covered by prometheus-libvirt-exporter
• Ceph metrics missing from ceph-exporter
• Pacemaker cluster metrics
• Debian RT (Real-Time) kernel metrics
• Other infrastructure metrics as needed

This exporter is actively developed and new metrics are added based on real production needs.

⁠Current Features

⁠Vhost Thread Monitoring

Collects CPU time metrics for vhost threads associated with KVM virtual machines.

Metric exposed:

• virsh_vhost_cpu_time_seconds - CPU time (user+system) of vhost threads related to each domain, labeled by domain name and thread ID

⁠Quick Start

⁠Using Podman

podman run -d \
  --name insatomcat-exporter \
  --restart unless-stopped \
  -p 9184:9184 \
  -v /var/run/libvirt/libvirt-sock:/var/run/libvirt/libvirt-sock:ro \
  -v /var/run/libvirt/qemu:/var/run/libvirt/qemu:ro \
  --pid=host \
  docker.io/insatomcat/insatomcat-exporter:latest

⁠Using Docker

docker run -d \
  --name insatomcat-exporter \
  --restart unless-stopped \
  -p 9184:9184 \
  -v /var/run/libvirt/libvirt-sock:/var/run/libvirt/libvirt-sock:ro \
  -v /var/run/libvirt/qemu:/var/run/libvirt/qemu:ro \
  --pid=host \
  insatomcat/insatomcat-exporter:latest

⁠Using Quadlet (Recommended for production)

Create /etc/containers/systemd/insatomcat-exporter.container:

[Unit]
Description=Prometheus insatomcat Exporter
After=network-online.target libvirtd.service
Wants=network-online.target

[Container]
Image=docker.io/insatomcat/insatomcat-exporter:latest
PublishPort=9184:9184
Volume=/var/run/libvirt/libvirt-sock:/var/run/libvirt/libvirt-sock:ro
Volume=/var/run/libvirt/qemu:/var/run/libvirt/qemu:ro
PodmanArgs=--pid=host
SecurityLabelDisable=true

[Service]
Restart=always
RestartSec=5

[Install]
WantedBy=multi-user.target

Then enable and start:

sudo systemctl daemon-reload
sudo systemctl enable --now insatomcat-exporter.service

⁠Requirements

Current requirements (will expand as new metrics are added):

• For vhost metrics:
  • Host with libvirt/QEMU installed
  • Access to /var/run/libvirt/libvirt-sock
  • Access to /var/run/libvirt/qemu
  • Host PID namespace access (--pid=host)

⁠Verification

Once running, verify the exporter is working:

curl http://localhost:9184/metrics

Example output:

virsh_vhost_cpu_time_seconds{domain="vm1",thread="vhost-12345"} 123.45
virsh_vhost_cpu_time_seconds{domain="vm2",thread="vhost-67890"} 67.89

⁠Prometheus Configuration

Add this to your prometheus.yml:

scrape_configs:
  - job_name: 'insatomcat-exporter'
    static_configs:
      - targets: ['localhost:9184']
    scrape_interval: 30s

⁠docker-compose Example

version: '3.8'

services:
  insatomcat-exporter:
    image: insatomcat/insatomcat-exporter:latest
    container_name: insatomcat-exporter
    restart: unless-stopped
    ports:
      - "9184:9184"
    volumes:
      - /var/run/libvirt/libvirt-sock:/var/run/libvirt/libvirt-sock:ro
      - /var/run/libvirt/qemu:/var/run/libvirt/qemu:ro
    pid: host

⁠Use Cases

Current:

• Monitor CPU usage of vhost threads for KVM virtual machines
• Track performance of virtio-net network interfaces
• Identify VMs with high vhost CPU consumption
• Create alerts when vhost thread CPU usage exceeds thresholds

Upcoming:

• Monitor specific libvirt domain states and performance metrics
• Track Ceph cluster health metrics not exposed by standard exporters
• Monitor Pacemaker cluster resource states
• Track Debian RT kernel performance metrics
• And more based on production needs

⁠Roadmap

This exporter is designed to be a collection of metrics that should exist in other exporters but don't. Each new metric is added based on real production monitoring needs.

If you need a specific metric that's missing from standard exporters, feel free to open an issue or submit a PR.

⁠Tags

• latest - Latest stable release with all current metrics
• 1.0.0 - Initial release with vhost metrics
• Version tags will be added as new metrics are implemented

⁠Philosophy

Rather than creating multiple small exporters for each missing metric, this exporter consolidates all the "missing pieces" needed for complete infrastructure monitoring. It's meant to complement, not replace, existing exporters like prometheus-libvirt-exporter, ceph-exporter, etc.

⁠Source Code

Available on GitHub (link to be added)

⁠Contributing

Contributions are welcome! If you have metrics that should be added to fill gaps in existing exporters, please submit a PR or open an issue.

⁠Support

For issues, questions, or feature requests, please open an issue on GitHub or contact the maintainer.