Building from Source#

This guide explains how to build Metrics Manager from source code for development, customization, or air-gapped deployments.

Prerequisites#

Before building, ensure you have:

  • System Requirements: See System Requirements

  • Source code: Cloned the repository (git clone https://github.com/open-edge-platform/edge-ai-libraries.git -b main)

  • Platform familiarity: Basic understanding of Docker and Docker Compose

Building Locally (Without Docker)#

If you want to run the service locally without Docker, use the following approach:

Prerequisites#

  • Python 3.10+ (python3 --version)

  • uv (fast Python package manager): pip install uv or see UV Documentation

  • Telegraf installed on the system (for system metrics)

  • qmassa binary (for GPU metrics) — compile from qmassa GitHub or skip if not needed

  • Git

Step 1: Clone and Navigate#

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

Step 2: Create a Virtual Environment#

python3 -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

Or with uv (faster):

uv venv
source .venv/bin/activate

Step 3: Install Dependencies#

uv sync --group test

Or with pip:

pip install -e ".[test]"

Step 4: Configure the Environment#

cp .env.example .env

Edit .env and set:

# Since Telegraf runs on the host (not in a container), use localhost
TELEGRAF_PORT=9273
TELEGRAF_HTTP_ENDPOINT=http://localhost:8186/write
PROMETHEUS_TELEGRAF_ENDPOINT=http://localhost:9273

Step 5: Start Telegraf#

On your host machine, start Telegraf with the bundled config:

telegraf --config telegraf.conf

This exposes metrics on http://localhost:9273/metrics and listens for writes on http://localhost:8186/write.

Step 6: Run the Application#

uvicorn app.main:app --reload --port 9090

The service will start on http://localhost:9090.

Step 7: Verify#

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

Running Tests#

Locally#

If you installed dependencies locally:

# Run all tests
pytest

# Run with verbose output
pytest -v

# Run with coverage
pytest --cov=app --cov-report=html

Expected Output#

========================= test session starts ==========================
tests/test_settings.py::...              PASSED
tests/test_logging_config.py::...        PASSED
tests/test_main.py::...                  PASSED
tests/test_models.py::...                PASSED
tests/test_store.py::...                 PASSED
tests/test_routes.py::...                PASSED
tests/test_metrics.py::...               PASSED
tests/test_rate_limit.py::...            PASSED
tests/test_sse.py::...                   PASSED
tests/test_npu_monitor_tool.py::...      PASSED
tests/test_npu_reader.py::...            PASSED
tests/test_telegraf_integration.py::...  SKIPPED (requires Docker)
========================= 179 passed in 1.70s ==========================

Development Setup#

For local development with hot-reload and debugging:

# Install dev dependencies
uv sync --group test --group dev

# Run with auto-reload
uvicorn app.main:app --reload --port 9090

# Run linting and formatting
black app/
ruff check app/

Building the Helm Chart#

If you are deploying to Kubernetes:

# Lint the Helm chart
make helm-lint

# Generate the chart package
make helm-package

# Push to OCI registry (requires authentication)
make helm-push

See Helm Deployment for full Kubernetes instructions.

Customization#

Modifying Telegraf Configuration#

The telegraf.conf file controls system metric collection. To customize:

  1. Edit telegraf.conf in the metrics-manager root directory

  2. Or mount a custom config: TELEGRAF_CONFIG=./my-telegraf.conf docker compose up

  3. Or drop additional .conf files in the telegraf.d/ directory

See Environment Variables for Telegraf customization examples.

Extending with Custom Inputs#

Add Python or shell scripts to /app/custom-metrics/:

# Example: create a fan speed monitor
cat > /app/custom-metrics/fan_speed.sh << 'EOF'
#!/bin/sh
rpm=$(cat /sys/class/hwmon/hwmon0/fan1_input)
echo "fan_speed,sensor=cpu_fan rpm=${rpm}i"
EOF
chmod +x /app/custom-metrics/fan_speed.sh

The script runs every 10 seconds and outputs InfluxDB Line Protocol.

Troubleshooting Build Issues#

Error

Solution

Rust toolchain not found

First Docker build compiles Rust. Try docker compose build --no-cache.

Module not found: app

Ensure you’re in the metrics-manager/ directory and have run uv sync or pip install -e .

Port 9090 already in use

Change port in .env: HOST_METRICS_PORT=19090

Telegraf not found

Install Telegraf: apt-get install telegraf (Debian/Ubuntu) or use Docker

Permission denied on /sys

Ensure you run with --privileged (Docker) or as root (local)

Supporting Resources#

License#

Copyright (C) 2025-2026 Intel Corporation

SPDX-License-Identifier: Apache-2.0