Monitoring PuppyGraph with Prometheus

Summary

In this guide you will:

• Start PuppyGraph with metrics enabled using Docker Compose;
• Launch Prometheus with a ready-to-use scrape configuration;
• Confirm that PuppyGraph metrics are being collected.

For the full monitoring reference, including the available endpoints and the metrics PuppyGraph exposes, see Monitoring.

Prerequisites

• Docker and Docker Compose installed and available on your machine. Confirm with docker --version and docker compose version.

Prepare the Example Configuration

Prometheus Scrape Configuration

Save the following file as prometheus.yml inside your working directory:

global:
  scrape_interval: 15s
  evaluation_interval: 15s

scrape_configs:
  - job_name: puppygraph
    metrics_path: /metrics
    static_configs:
      - targets: ["puppygraph:8083"]
    basic_auth:
      username: puppygraph
      password: puppygraph123

• The target points to port 8083 of the puppygraph service defined in Docker Compose, where PuppyGraph serves its node metrics. Port 8081 serves the Web UI. Prometheus reaches port 8083 over the Compose network, so the Compose file below does not publish it on your host.
• Basic authentication uses the default PuppyGraph admin credentials (PUPPYGRAPH_USERNAME and PUPPYGRAPH_PASSWORD). Update both the PuppyGraph admin password and this configuration before running in production.
• In PuppyGraph 1.16.0 and later, the controlplane also reports local-table load metrics on port 8081. To collect them too, see Collect controlplane metrics below.

Docker Compose

Save the following file as docker-compose.yml in the same directory, updating the Prometheus volume path to match where you stored prometheus.yml:

version: "3.8"

services:
  puppygraph:
    image: puppygraph/puppygraph:latest
    container_name: puppygraph
    ports:
      - "8081:8081"
    environment:
      - METRICS_ENABLED=true

  prometheus:
    image: prom/prometheus:latest
    container_name: prometheus
    ports:
      - "9090:9090"
    volumes:
      - ./prometheus.yml:/etc/prometheus/prometheus.yml

networks:
  default:
    driver: bridge

• Replace ./prometheus.yml with the relative or absolute path to the file you created (use ./prometheus.yml if both files live in the same folder).
• Ensure the PuppyGraph container runs with METRICS_ENABLED=true so the /metrics endpoint remains available.
• This compose file enables the PuppyGraph metrics endpoint and mounts the Prometheus configuration so the scraper can discover PuppyGraph automatically.

Launch the Stack

Start the services:

docker compose up -d

Confirm that both containers are healthy:

docker compose ps

PuppyGraph exposes its UI at http://localhost:8081 and Prometheus at http://localhost:9090.

Verify Metrics Collection

Sign in to PuppyGraph at http://localhost:8081 using the default credentials (puppygraph / puppygraph123).

Open Prometheus at http://localhost:9090 and open Status > Target health to verify that the puppygraph target at http://puppygraph:8083/metrics is UP.

The puppygraph target should display state UP when metrics are being scraped successfully.

Open Query, enter a PuppyGraph metric such as puppy_compute_memory_usage_bytes in the expression field, and click Execute.

Query results confirm that Prometheus is reading PuppyGraph metrics from the /metrics endpoint.

If you see the target in the UP state and samples returned for your query, Prometheus is successfully scraping PuppyGraph.

Collect Controlplane Metrics

Version requirement

Controlplane local-table load metrics are available in PuppyGraph 1.16.0 and later.

The controlplane reports metrics about local-table loads on port 8081. That endpoint requires a user or service account with the CLUSTER:read permission, such as the default puppygraph admin, and ignores METRICS_AUTH_ENABLED. Add a second job to prometheus.yml:

  - job_name: puppygraph-controlplane
    metrics_path: /metrics
    static_configs:
      - targets: ["puppygraph:8081"]
    basic_auth:
      username: puppygraph
      password: puppygraph123

In production, use a service account with CLUSTER:read instead of the admin credentials. Restart Prometheus with docker compose restart prometheus, check that the puppygraph-controlplane target is UP, and query a metric such as puppy_controlplane_local_table_load_tasks_total. See Controlplane metrics for the metrics and what they mean.