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 in a Docker Container (Recommended)#
The recommended way to build is inside Docker, which handles all dependencies (Rust toolchain, Telegraf, Python) automatically.
Step 2: Copy Environment Configuration#
cp .env.example .env
Edit .env if needed (usually defaults work fine).
Step 3: Build the Docker Image#
docker compose build metrics-manager
This runs a multi-stage build:
Rust builder: Compiles qmassa and qmmd from their pinned upstream tags with locked dependencies.
Telegraf stage: Downloads the official pinned release archive and verifies its SHA-256 checksum. Telegraf is not rebuilt or patched locally.
Go builder: Compiles the six native telemetry collectors with the pinned Go toolchain.
Python builder: Installs runtime dependencies, optionally including OpenVINO.
Test target: Adds test dependencies and sources when explicitly selected.
Accelerator stage: For extended builds only, downloads the pinned Intel GPU/NPU userspace packages from official release assets, verifies SHA-256 digests and selects only the required packages. Pins are read directly from
versions.env; firmware and debug packages are excluded.Production target: Uses digest-pinned
python:3.12-slim-trixie(Debian 13), applies available Debian updates, and assembles the API, collectors and supervisor. Extended builds install the accelerator packages with normal APT dependency checks. Downloaded packages are build-only mounts, not retained archive layers in the final image.
For the two separately tagged RC1 builds, see Building both release-candidate variants.
First build duration: 3–10 minutes (depends on download speeds and CPU)
Subsequent builds: <1 minute (cached layers)
Step 4: Start the Service#
docker compose up
Or in the background:
docker compose up -d
Step 5: Verify#
curl http://localhost:9090/health
Building Locally (Without Docker)#
If you want to run the service locally without Docker, use the following approach:
Prerequisites#
Python 3.12+ (
python3 --version)uv: follow the uv installation instructions
Running telemetry backend: Telegraf with a Prometheus endpoint and HTTP ingestion listener. The steps below run the API separately from this backend.
Git
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
The test dependencies are a dependency group, not a test extra. Use
uv sync --group test; pip install -e ".[test]" does not install this group.
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: Verify the Telemetry Backend#
Check that your configured telemetry backend is reachable:
curl --fail http://127.0.0.1:9273/metrics | head
The example settings expect 127.0.0.1:9273 for metrics and 127.0.0.1:8186
for writes. Adapt them to your backend and do not start a second Telegraf on
occupied ports. The container’s
root-level telegraf.conf uses container paths and environment substitutions;
it is not a standalone host configuration.
Step 6: Run the Application#
.venv/bin/uvicorn app.main:app --reload --host 127.0.0.1 --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#
Via Docker (Recommended)#
# Run all tests
docker compose --profile test build metrics-manager-test
docker compose --profile test run --rm metrics-manager-test
# Run with coverage
docker compose --profile test run --rm metrics-manager-test \
python -m pytest tests/ -v --cov=app --cov-report=term-missing
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_versions.py::... PASSED
tests/test_telegraf_integration.py::... PASSED
This is an illustrative excerpt, not a fixed test count or timing guarantee. The Telegraf wiring tests inspect configuration and do not require a running Docker daemon. Binary-backed selection tests and live deployment tests have separate prerequisites; see the Testing Guide.
Development Setup#
For local development with hot-reload and debugging:
# Install dev dependencies
uv sync --group test --group dev
# Run with auto-reload
.venv/bin/uvicorn app.main:app --reload --host 127.0.0.1 --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:
Edit
telegraf.confin the metrics-manager root directoryOr mount a custom config:
TELEGRAF_CONFIG=./my-telegraf.conf docker compose upAdd custom
.conffiles totelegraf.d/, or select another source directory withTELEGRAF_CONFIG_DIR. Startup recursively copies these files into a private snapshot without modifying the mounted originals.Recreate the selected container to apply changes. Do not enable an automatic collector flag for an input already supplied by your custom configuration: overlapping inputs are rejected instead of collected twice.
See Additional Native Docker Collectors for a complete example and Environment Variables for Telegraf configuration settings.
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 |
|---|---|
|
First Docker build compiles Rust. Try |
|
Run from |
|
For Compose, set |
|
Build the Docker image or configure an existing telemetry backend. |
|
Check the collector-specific device/capability requirements; do not run the local API as root to grant collector access. |
Supporting Resources#
License#
Copyright (C) 2025-2026 Intel Corporation
SPDX-License-Identifier: Apache-2.0