Get Started#

This guide provides step-by-step instructions to install and run Metrics Manager on your machine using Docker Compose.

Prerequisites#

  • Docker: 24.0+ (docker --version)

  • Docker Compose: 2.20+ (docker compose version)

  • Linux: Kernel 5.4+ (for system metrics collection)

  • RAM: 512 MB free

  • Disk: 2 GB free (for Docker image build)

See System Requirements for detailed hardware/software requirements.


Pre-built Image (Optional)#

This checkout targets the unreleased 2026.3.0 version. Until that image is published, use the build-from-source instructions. Registry examples below use the target release tag.

Instead of building from source, you can pull the pre-built Docker image from the registry:

docker pull intel/metrics-manager:2026.3.0

The image uses a digest-pinned python:3.12-slim-trixie base (Debian 13) and includes:

  • Telegraf 1.40.3 (system metrics agent)

  • qmassa 2.1.0 (Intel® GPU telemetry)

  • Native Go collectors: mm-plugin-cpu, mm-plugin-gpu, mm-plugin-npu, mm-plugin-proc, mm-plugin-membw, plus the opt-in mm-plugin-rapl

  • Python 3.12 runtime with FastAPI

  • supervisord process manager

GPU/NPU prerequisites: The host must provide the appropriate GPU/NPU drivers and telemetry interfaces. GPU collection uses qmassa and can require DRM, perf or MSR access; NPU telemetry requires supported PMT data and read permissions. Installing an image does not supply host kernel drivers. The extended build adds OpenVINO and VAAPI userspace tooling, not kernel drivers. See hardware-specific requirements.

Next: You can now run the image directly with docker run (see Running Without Docker Compose below), or continue below to build from source using Docker Compose.


Installation Steps#

Step 1: Clone the Repository#

git clone https://github.com/open-edge-platform/edge-ai-libraries.git -b main
cd edge-ai-libraries/microservices/metrics-manager

Step 2: Configure Environment#

Copy the example configuration file:

cp .env.example .env

The defaults work out of the box. Edit .env only if needed.

Key settings:

# Host ports (change if already in use)
HOST_METRICS_PORT=9090          # Metrics Manager REST API + SSE
HOST_TELEGRAF_PORT=9273         # Telegraf Prometheus endpoint
HOST_TELEGRAF_HTTP_PORT=8186    # Telegraf HTTP listener (InfluxDB Line Protocol)

# Logging
LOG_LEVEL=INFO                  # DEBUG | INFO | WARNING | ERROR

Step 3: (Optional) Set Proxy Variables#

If behind a corporate proxy, uncomment in .env:

http_proxy=http://proxy.example.com:8080
HTTP_PROXY=http://proxy.example.com:8080
https_proxy=http://proxy.example.com:8080
HTTPS_PROXY=http://proxy.example.com:8080
no_proxy=localhost,127.0.0.1
NO_PROXY=localhost,127.0.0.1

This passes proxy settings both to the Docker build and to the running container.

Step 4: Build and Start#

docker compose up --build

First build takes 3–10 minutes (compiles qmassa and Telegraf, then installs Python packages). Subsequent builds are cached and take under a minute.

To run in the background:

docker compose up --build -d

Running Without Docker Compose (docker run)#

If you prefer to run the container directly with docker run instead of Docker Compose, use the commands below. The image is pre-configured with all dependencies and environment defaults.

Prerequisites for docker run#

  • Docker: 24.0+ (no Docker Compose needed)

  • Linux: Kernel 5.4+

  • Host paths: /sys, /run, and optionally /dev/dri must be accessible

Minimal Setup (CPU + Memory + Temperature Only)#

docker run --rm \
  -p 9090:9090 \
  -p 9273:9273 \
  -v /sys:/sys:ro \
  -v /run:/run:ro \
  --pid host \
  intel/metrics-manager:2026.3.0

Then verify:

curl http://localhost:9090/health
curl -s http://localhost:9273/metrics | head

With Intel Arc GPU Support#

Add --device /dev/dri so qmassa can access GPU devices:

docker run --rm \
  --device /dev/dri \
  -p 9090:9090 \
  -p 9273:9273 \
  -v /sys:/sys:ro \
  -v /run:/run:ro \
  --pid host \
  intel/metrics-manager:2026.3.0

Verify GPU metrics:

curl -s http://localhost:9273/metrics | grep gpu

With Intel NPU Support#

Run in privileged mode to access /sys/class/intel_pmt:

docker run --rm --privileged \
  -p 9090:9090 \
  -p 9273:9273 \
  -v /sys:/sys:ro \
  -v /run:/run:ro \
  --pid host \
  intel/metrics-manager:2026.3.0

Verify NPU metrics:

curl -s http://localhost:9273/metrics | grep npu

With Both GPU and NPU#

docker run --rm --privileged \
  --device /dev/dri \
  -p 9090:9090 \
  -p 9273:9273 \
  -v /sys:/sys:ro \
  -v /run:/run:ro \
  --pid host \
  intel/metrics-manager:2026.3.0

With Custom Ports#

Map to different host ports:

docker run --rm \
  -p 19090:9090 \
  -p 19273:9273 \
  -v /sys:/sys:ro \
  -v /run:/run:ro \
  --pid host \
  intel/metrics-manager:2026.3.0

Then access on the new ports:

curl http://localhost:19090/health

With Environment Variables#

Pass configuration via -e:

docker run --rm \
  -p 9090:9090 \
  -p 9273:9273 \
  -e LOG_LEVEL=DEBUG \
  -e CORS_ORIGINS=http://localhost:3000 \
  -e METRICS_RETENTION_SECONDS=600 \
  -v /sys:/sys:ro \
  -v /run:/run:ro \
  --pid host \
  intel/metrics-manager:2026.3.0

See Environment Variables for all available variables.

Additional Native Collectors#

For optional per-CPU powerstat, high-resolution temperature, IRQ, network, storage, RAPL and Turbostat collection, follow Additional collectors in the native-enabled Docker image. Use this image’s native-consistent ENABLE_* flags or mounted .conf drop-ins, not legacy Python-reader switch names or the bare-metal configuration helper. The guide also covers the optional host-nic-telemetry deployment variant, explicit service switching, and host-network port exposure. Bridge mode remains the default; the host-NIC variant enables network collection unless explicitly disabled.

With Custom Metrics Directory (Volume Mount)#

To persist custom metric scripts across container restarts, mount a volume:

mkdir -p ./my-scripts

docker run --rm \
  -p 9090:9090 \
  -p 9273:9273 \
  -v /sys:/sys:ro \
  -v /run:/run:ro \
  -v ./my-scripts:/app/custom-metrics \
  --pid host \
  intel/metrics-manager:2026.3.0

Drop your scripts in ./my-scripts/ (they must be executable: chmod +x script.sh).

Background Execution#

Run in the background:

docker run -d \
  --name metrics-manager \
  -p 9090:9090 \
  -p 9273:9273 \
  -v /sys:/sys:ro \
  -v /run:/run:ro \
  --pid host \
  intel/metrics-manager:2026.3.0

Stop it:

docker stop metrics-manager
docker rm metrics-manager

View logs:

docker logs -f metrics-manager

Verify the Installation#

Run these checks after the container starts:

1. Service Health#

curl http://localhost:9090/health

Expected response: {"status": "healthy", ...}

2. System Metrics#

curl http://localhost:9273/metrics | head -30

Should show CPU, memory, temperature metrics.

3. Push a Test Metric#

curl -X POST http://localhost:9090/api/v1/metrics/simple \
  -H "Content-Type: application/json" \
  -d '{"name": "install_test", "value": 1.0}'

Expected response: {"accepted": 1, ...}

4. Query the Metric#

curl http://localhost:9090/api/v1/metrics/latest

Should show your install_test metric.


Installation Variants#

Custom Host Ports#

If ports 9090, 9273, or 8186 are in use, override them in .env:

# .env
HOST_METRICS_PORT=19090
HOST_TELEGRAF_PORT=19273
HOST_TELEGRAF_HTTP_PORT=18186

Then access the service on the new ports:

curl http://localhost:19090/health

Custom Telegraf Configuration#

Use your own Telegraf config:

TELEGRAF_CONFIG=./my-telegraf.conf docker compose up

Or set permanently in .env:

TELEGRAF_CONFIG=./my-telegraf.conf

Add Inputs on Top of Default Config#

The container loads .conf files recursively from the mounted telegraf.d/ directory, or the directory selected by TELEGRAF_CONFIG_DIR. Startup copies them into a private snapshot without modifying the originals. Recreate the selected container after changing these files.

For a bundled optional collector, prefer its enable flag. For example:

ENABLE_RAPL=true docker compose up -d --no-build --force-recreate metrics-manager

If custom configuration already declares the RAPL input, keep ENABLE_RAPL=false: the flag controls automatic additions, not your custom input. Enabling both is rejected as a conflict. RAPL requires readable host energy counters; package power can appear even when the hardware has no platform (psys) domain. See the complete additional native Docker collectors guide for prerequisites, other inputs and verification commands.

Restrict CORS Origins#

By default all origins are allowed (CORS_ORIGINS=*). To restrict:

# .env
CORS_ORIGINS=http://my-dashboard.local:3000,http://localhost:3000

Stopping and Removing#

# Stop the service
docker compose down

# Stop and remove volumes (clears custom metrics)
docker compose down -v

# Remove built images
docker compose down --rmi local

Exposed Ports#

Port

Protocol

Description

9090

HTTP / SSE

Metrics Manager REST API, SSE stream

9273

HTTP

Telegraf Prometheus endpoint (system + custom metrics)

8186

HTTP

Telegraf HTTP listener (InfluxDB Line Protocol)


Troubleshooting Installation#

Issue

Solution

Port already in use

Change ports in .env (e.g., HOST_METRICS_PORT=19090)

Build fails

Run docker builder prune to clear cache

Container will not start

Check logs: docker logs metrics-manager

No GPU/NPU metrics

Expected if hardware not present; other metrics continue

See Troubleshooting for more issues.


Next Steps#

Supporting Resources#

License#

Copyright (C) 2025-2026 Intel Corporation

SPDX-License-Identifier: Apache-2.0