#Operations Guide

Version: 0.51.0 Updated: 2026-07-17 Applies to: ranvier (facade), ranvier-http, ranvier-inspector Category: Deep Dives

Production-ready configuration, health probes, structured logging, and telemetry for Ranvier applications.

#Configuration System

• RanvierConfig: 4-layer loading ??defaults, ranvier.toml, profile overrides, environment variables.
• Profile Overrides: RANVIER_PROFILE=prod activates [profile.prod] section in ranvier.toml.
• HttpIngress::config(): Applies server settings and initializes telemetry from config.

#Health & Readiness

• health_endpoint(): JSON health status with registered check results.
• readiness_liveness_default(): Kubernetes-style /ready and /live probes.
• health_check(): Register async health checks (DB connectivity, external service pings).

#Request Pipeline

• request_id_layer(): Ensures x-request-id propagation on every request/response.
• AccessLogGuard: Structured HTTP request/response logging as a Transition node.
• Path Redaction: AccessLogGuard.redact_paths() for sensitive endpoints like /auth/login.

#Structured Logging

• config.init_logging(): Initializes tracing subscriber from config.
• Three formats: json (production, machine-readable), pretty (development), compact.
• Per-module level overrides via logging.module_levels in ranvier.toml.

#Telemetry & OTLP

• TelemetryConfig: OTLP endpoint, protocol (gRPC/HTTP), service name, sample ratio.
• init_telemetry(): No-op when otlp_endpoint is None; auto-initializes TracerProvider when set.
• Inspector /metrics: Prometheus exposition format for Grafana/AlertManager integration.

#Workflows

1. Create ranvier.toml with server, logging, telemetry, and inspector sections.
2. Load config with RanvierConfig::load() and initialize logging with config.init_logging().
3. Pass config to HttpIngress::config() to apply server settings and start telemetry.
4. Add health_endpoint() and readiness_liveness_default() for Kubernetes probes.
5. Enable request_id_layer() for request tracing correlation.
6. Add AccessLogGuard to Axon pipelines for structured request logging.
7. Configure OTLP endpoint via environment variable for production tracing.

#Managed Lifecycle Runbook

1. Choose run_managed only after the service can treat operator shutdown as a typed cancellation and return 503 for interrupted requests; retain run during a compatibility canary if responses must drain unchanged.
2. Set one graceful_shutdown budget for connections and adapter-owned SSE/WebSocket tasks. Do not assume each phase receives the full duration.
3. Monitor forced-abort warnings. A non-zero count means cleanup exceeded the budget and requires workload tuning or durable recovery evidence.
4. Make long-running transitions observe bus.cancellation_token() at bounded async checkpoints. Blocking/CPU loops require their own cooperative yield.
5. Use the cancellation-aware Inspector and cluster-loop entrypoints when the embedding runtime must await all background owners.
6. Verify persisted Cancelled/Compensated state before broad rollout and keep RQ8 crash/reconnect procedures available for forced process loss.

#Canonical Load/Soak Release Runbook

Use this gate to reproduce the M419-RQ10 decision-fixture evidence. It is a maintainer release check, not an application template or a universal SLO.

1. Install Podman and start its Linux engine. Keep the Ranvier checkout on a committed SHA; full mode rejects tracked or untracked source changes.

2. From the workspace root, run quick mechanics first:

   Copy

   powershell -NoProfile -ExecutionPolicy Bypass -File ranvier/scripts/m419_load_soak_podman.ps1 -Mode Quick

   Quick mode shortens phases and cannot close a release requirement.

3. Run the canonical evidence without editing the policy after observing quick or full results:

   Copy

   powershell -NoProfile -ExecutionPolicy Bypass -File ranvier/scripts/m419_load_soak_podman.ps1 -Mode Full

4. Preserve the unique output directory printed by the wrapper. Confirm result.json has evidence_eligible: true, no environment mismatches, no failed checks, and the expected source SHA. Retain the raw latency gzip and all logs with the result and Markdown summary.

5. Verify the raw latency artifact independently when handing evidence off:

   Copy

   Get-FileHash ranvier/target/m419-load-soak/<run>/latency-samples.json.gz -Algorithm SHA256

   The lowercase digest must equal result.json → artifacts.latency_samples.sha256.

6. Treat missing RSS samples, malformed JSON, any non-2xx response, retention without eviction, non-zero active traces, a connection reset instead of typed 503, or source drift during the run as a failed gate.

7. A host-noise rerun is allowed once with the exact same committed source, policy, and environment. Preserve both runs. Product or harness bugs may be fixed normally; threshold changes require a separately reviewed contract.

The wrapper allows network only while fetching locked Cargo inputs. The actual build/run container has --network none, 2 CPUs, 2 GiB, and 512 pids. It records OCI image identity, kernel/CPU, cgroup values, Rust, Cargo, Node, and pre/post source state. RQ8 remains authoritative for PostgreSQL/Redis recovery and File Audit durability; this in-memory fixture makes no external-service, cross-machine throughput, WebSocket/SSE population, or adopter-wide latency claim.

#Supply-Chain, Handoff, and Provenance Runbook

Run these commands from a clean Ranvier repository checkout. Use Node 24, exact Rust 1.95.0 for provenance, cargo-audit 0.22.2, and cargo-deny 0.20.2:

cargo install cargo-audit --version 0.22.2 --locked
cargo install cargo-deny --version 0.20.2 --locked
node scripts/publish_boundary.mjs --check
node scripts/supply_chain_gate.mjs --self-test --output target/supply-chain/release.json
node scripts/maintenance_handoff_gate.mjs --self-test --output target/supply-chain/handoff.json
node scripts/release_provenance.mjs --self-test
node scripts/release_provenance.mjs

The advisory JSON deliberately has two views. Cargo-audit inventories the broad Cargo.lock, including inactive optional dependencies. Cargo-deny with all features and unpublished packages excluded is the release authority. Do not delete a broad finding merely because in_release_scope is false; retain it for monthly review. Any release-scope finding must be fixed or have a current structured triage record, and High/Critical remains no-go even when recorded. Remove a triage record as soon as the matching finding disappears because a stale record also fails the gate.

The provenance output must contain 12 .crate files, one source archive, SHA256SUMS, and provenance.json for the same clean commit. The script checks embedded VCS SHAs and compiles the extracted package cohort offline with a lock derived from the tracked Cargo.lock. Recalculate every digest before handoff. Local JSON is unsigned and must not be called a signature.

For a tag/manual CI bundle, verify GitHub's attestation and then compare the bundle checksum with the archived manifest:

gh attestation verify ranvier-provenance-<commit>.tar.gz --repo ranvier-rs/ranvier
sha256sum -c SHA256SUMS

Attestation verifies workflow identity for the bundle; it does not prove vulnerability absence or equality with crates.io. After publication, download the registry .crate files and compare their SHA-256 values separately. The backup tabletop proves a repository no-go decision path, not mailbox delivery, account permissions, or real incident response availability.

#Key Types