Install:
- Git;
- Python 3.10–3.13 (3.13 is the release-CI version);
- Docker Engine or Docker Desktop with Compose v2 and Buildx; and
- optionally
uvfor resolving the checked-inuv.lock.
For adapter and unified-mode development, clone the OpAMP core repository beside this repository:
dev/
SignalGenerator-Python/
opamp2/ # clone of opamp-observe/opamp-core
The directory may have another name when --opamp-core-context or OPAMP_CORE_CONTEXT is supplied.
From SignalGenerator-Python:
# PowerShell
py -3.11 -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install --upgrade pip
python -m pip install -e ".[dev]"
python -m pip install -e "..\opamp2\consumer"
python -m pip install -e ".\integrations\opamp-simulator[dev]"
# Bash
python3.11 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install -e ".[dev]"
python -m pip install -e ../opamp2/consumer
python -m pip install -e "./integrations/opamp-simulator[dev]"
Confirm the environment:
python -m pip check
signal-generator --version
signal-generator-opamp-sim --version
pyproject.toml is the source of truth. uv.lock locks the complete core development resolution;
the adapter owns its separate compatibility lock and TOML metadata.
| Path | Ownership |
|---|---|
src/signal_generator |
Core configuration, logs, metrics, runtime, and Quart attachment |
integrations/opamp-simulator |
Independently built OpAMP adapter |
examples |
Validated log, metric, and adapter scenarios |
tests |
Unit, contract, integration, and container tests |
scripts |
Startup, security, benchmark, release, and regression utilities |
docs |
Design, operation, development, security, and release contracts |
The adapter consumes the generic simulator client from opamp-observe/opamp-core; its embeddable
lifecycle and all SignalGenerator-specific logic remain in the adapter. Do not add this feature to
the companion process launcher or the OpAMP provider.
python -m ruff check src tests scripts
python -m pylint src/signal_generator
python -m pytest -q
python -m xenon --max-absolute B --max-modules A --max-average A src/signal_generator
docker run --rm -v "${PWD}:/repo" -w /repo rhysd/actionlint:latest
cd integrations/opamp-simulator
python -m ruff check src tests
python -m pylint src/signal_generator_opamp_sim
python -m pytest -q
python -m xenon --max-absolute B --max-modules A --max-average A src/signal_generator_opamp_sim
The complete pre-package gate is:
python scripts/security_checks.py
For a task-oriented local check runner, use:
python scripts/dev.py
python scripts/dev.py unit containers audit pylint renovate
The developer CLI runs unit tests without the repository-wide coverage threshold, the supported
local container scenarios with guaranteed teardown, the core pip-audit and Pylint checks, and
Renovate in dry-run mode when installed. Add --include-unified --opamp-core-context ../opamp2 to
include the companion-dependent unified container profile.
It covers both distributions, branch coverage, cyclomatic complexity, source-security rules, and dependency auditing. Functions may be no worse than Radon B/McCabe 10, while module and package averages must remain A. Core branch coverage must remain at least 90%.
The quality GitHub Actions workflow does not run for pull requests or pushes to main whose
changes are limited to Markdown files and content under docs/. A change that includes any other
path still runs the complete workflow.
python -m build --outdir dist/core .
python -m build --outdir dist/adapter integrations/opamp-simulator
python -m twine check dist/core/* dist/adapter/*
python scripts/release_artifacts.py dist/core dist/adapter --output dist/evidence
Install the built wheels into a fresh virtual environment. Verify that the base adapter discovers
the opamp_consumer.plugins entry point without installing Quart, then install its unified extra
and import signal_generator_opamp_sim.quart_app.
Run all profiles sequentially:
python scripts/check_cloud_runner.py --cloud aws
python scripts/run_regression.py --profile all --opamp-core-context ../opamp2
The prerequisite checker is read-only; --cloud records the intended runner type. The regression
script scopes each Compose project by profile, emits a JSON report, captures service logs on
failure, and tears down in a finally path.
GitHub's composite unified-container job is currently suppressed because the released
opamp-core packages do not yet expose every mechanism required by the single-process simulator
composition. The repository variable ENABLE_OPAMP_CORE_SIMULATOR_INTEGRATION_TESTS is the
control: leave it unset or false to suppress the job, and set it to the exact value true after
the compatible opamp-core release. This does not affect the adapter's supervised plugin tests.
.github/workflows/cloud_regression.yml is manually dispatched from GitHub Actions. It selects a
self-hosted Linux runner with all of these labels:
self-hostedlinuxsignal-generator-regression- either
awsorazure
Use an ephemeral EC2 instance/Auto Scaling runner for AWS or an ephemeral Azure VM/VM Scale Set runner for Azure. Recommended minimums are 4 vCPU, 8 GiB RAM, and 30 GiB free storage. Install the GitHub runner, Python, Docker Engine, Compose v2, and Buildx; allow outbound HTTPS and container registry access, but no inbound application ports. Give the runner identity only repository-read access. The regression itself requires no cloud API credentials.
In GitHub:
- Open Actions → cloud regression → Run workflow.
- Choose
awsorazure, the source ref, andallor one profile. - Approve the matching
cloud-regression-awsorcloud-regression-azureenvironment. - Download the JSON evidence artifact after completion.
The workflow checks out this repository plus opamp-observe/opamp-core, verifies runner capacity,
runs the selected profiles, uploads reports even on failure, and performs a final scoped cleanup.
Configure the cloud runner group so only this repository and protected workflow can target it.
Preserve unrelated working-tree changes, add tests with implementation changes, keep schemas and examples synchronized, and update roadmap documentation whenever release notes defer work. See CONTRIBUTING.md and the release process.