Alerting and Webhooks

pyvorin-native 1.0.9 ships no alerting daemon, no webhook delivery and no notification channel of its own. What it ships instead is better for automation: structured, local, machine-readable signals with stable exit codes. Every alert described on this page is built from output we captured by running the installed build — nothing here depends on a dashboard you cannot inspect.

That design choice deserves a moment. Alerting built on exit codes and JSON reports keeps your monitoring inside your own infrastructure: the signal travels from the CLI to your cron jobs, your CI gates and your metrics collector without a third hop through a hosted service. The cost is that you assemble the alerts yourself. This page gives you the parts and three working recipes.

What the product actually emits

We ran every command below against the installed 1.0.9 build. These are the alerting surfaces that exist:

Outbound telemetry exists too, and one property of it matters for alerting: the security events — activation, validation_failed, tamper_detected, revoked — are always recorded and sent to the telemetry endpoint, while compile and execute events are sampled at 1%. Telemetry is fire-and-forget: it informs us, not you. If a tamper event fires, the place you will notice first is the import-time integrity failure on your own host, not a notification. Alert on the local signals.

Alerting on licence health

Licence failure is the one alert that pages someone in every shop running Pyvorin in production, so it gets the simplest possible check. pyvorin check runs the hard gate — offline validation of the stored lease, then an online revalidation if the offline check fails — and exits non-zero when the gate fails. That is the whole alert:

# /etc/cron.d/pyvorin — daily licence gate, alert on failure
15 6 * * * root /opt/pv/bin/pyvorin check >/dev/null 2>&1 || \
  logger -p user.err -t pyvorin "licence gate failed on $(hostname)"

For expiry warning you want more than a binary pass/fail — you want thirty days of runway. pyvorin status emits JSON, and the expires_at field is an ISO timestamp. A weekly cron that parses it gives you a graded warning without any extra tooling:

# Warn when the licence expires inside N days
/opt/pv/bin/pyvorin status | /opt/pv/bin/python -c '
import json, sys, datetime
s = json.load(sys.stdin)
exp = datetime.datetime.fromisoformat(s["expires_at"])
days = (exp - datetime.datetime.now(datetime.timezone.utc)).days
if days < 30:
    print(f"WARNING: pyvorin licence expires in {days} days")
'

Two behaviours worth remembering so the alert means what you think it means. First, a licence that validates offline passes the gate even if the online revalidation fails — a network partition alone will not page you, and the status JSON will still show active while the network problem persists. Second, after expiry there is an offline grace window (24 hours for trial tiers, 72 hours for basic and professional, 90 days for enterprise) before compiled features actually stop, so a missed warning is recoverable. Expiry alerts can be weekly, not hourly. One more subtlety from the field: if the host was cloned or restored from an image, expect a fingerprint mismatch before anything else — the stored identity covers hostname, account name and machine-id, and imaging tools routinely change all three at once.

CI checks: compilation and fallback rate

The strongest operational signal in the product is the compile report. Wire the gate into CI on files you have already claimed as native:

# Fail the build if any function regresses to fallback or fails validation
python -m pyvorin compile src/hotpaths.py --fail-on-fallback --report report.json
# exit 0: all COMPILED_FULL with oracle run
# exit 2: a function fell back, or compiled without validation
# exit 1: a function FAILED (e.g. oracle mismatch)

Exit 2 covers two different situations — a genuine fallback and a compile whose oracle never ran because the function needs arguments. During migration that distinction matters, and the report file settles it: read fallback_used and cpython_oracle_status per function rather than guessing from the exit code alone.

For trend alerting — the slow drift where a library upgrade quietly demotes half your hot paths — run bench --json in a scheduled CI job and record report.fallback_reason, report.drift_detected and the timing.mean_ms series in your own store. The full field list is documented under benchmarks and correctness validation. A rising fallback count across nightly runs is a real regression alert; a single fallback on one commit is a code review item.

Pulling OpenMetrics into your collector

python -m pyvorin run --compare --metrics executes the file against both Pyvorin and CPython and appends OpenMetrics text to the report. Metric names are prefixed pyvorin_run_; the ones we captured on the installed build include:

# TYPE pyvorin_run_speedup gauge
pyvorin_run_speedup 12.710630
# TYPE pyvorin_run_fallback_count gauge
pyvorin_run_fallback_count 0.000000
# TYPE pyvorin_run_deopt_count gauge
pyvorin_run_deopt_count 0.000000
# TYPE pyvorin_run_pyvorin_mean_ms gauge
pyvorin_run_pyvorin_mean_ms 0.028893
# TYPE pyvorin_run_cpython_mean_ms gauge
pyvorin_run_cpython_mean_ms 0.364281

These are emitted per invocation, so the natural pattern is a scheduled job that runs a representative entrypoint, writes the output to a Prometheus textfile collector directory, and lets your normal scrape pipeline handle thresholds. There is no long-running Pyvorin exporter in 1.0.9. This pull model is deliberate — nothing in the product opens a port.

Host health beyond the licence

One more cron-worthy check rounds out the set: python -m pyvorin doctor exits non-zero when any check fails, covering the runtime shared libraries, the C toolchain, AVX2 support, memory, disk, cache directory and licence state. On a healthy host it is quiet confirmation; after a system upgrade it is the fastest way to learn that a runtime library or compiler disappeared before your first failed job tells you. Run it after any change to the host image, and diff the output against the previous run rather than reading it fresh — the differences are the alert.

On webhooks

No webhook delivery exists in pyvorin-native 1.0.9. The verified outbound surface is two endpoints: the licence check and the batched telemetry flush. Neither offers customer-configured callback delivery for billing or licensing events, so any recipe that starts with "register a webhook URL" is building on a feature this build does not have. If push notifications matter to your operations, the honest path today is the cron and CI checks above feeding your existing pager pipeline. Webhook delivery for account events is the kind of thing we would announce against a specific release; check the release notes before designing around it.

A judgement call that saves noise

One decision the tooling cannot make: what deserves to page. Our advice from wiring these checks in anger — gate hard in CI, page softly in production. In CI, exit codes 1 and 2 on claimed files should block the merge; a compile regression is a diff someone just wrote. In production, do not page on individual fallbacks at all: the fallback path exists so that a demoted function keeps returning correct results, and paging on it trains the team to silence the alert. Page on the licence gate, on integrity failures, and on the trend in nightly fallback counts. Everything else belongs in a dashboard. The fallback is a feature working as designed. Treat it as an incident and you will break the one signal that matters.

Where to go next

• Pyvorin CLI reference — every flag behind the checks on this page, verified against the installed build.
• Error handling and diagnostics — the exit-code table and the failure records those codes summarise.
• Troubleshooting — what to do when one of these alerts fires.
• Security best practices — locking down the licence file and telemetry configuration the alerts depend on.

Last reviewed 30 April 2026 against pyvorin-native 1.0.9 installed at /root/pvfinal. Every command, exit code, JSON field and metric name on this page was captured from real runs on 13 September 2026. Webhook delivery was checked for and does not exist in this build; the section above says so rather than implying otherwise.