rtech-standards
Free for noncommercial use under PolyForm Noncommercial 1.0.0; commercial use needs a licence from Rico. View the source
- OBSERVABILITY_CONTRACT.md is the normative, semver'd spec for every log line an rTech service emits: fields, levels, labels, redaction, config and file paths. - conformance/envelope-cases.json is a language-agnostic set of test vectors. An implementation conforms when it passes every case. - packages/python/ (rtech-obs) is the reference implementation, built on loguru. - docs/decisions.md records each design decision and the reason for it.
The problem
Before this existed, the fleet had no log ingestion: about 139 service processes wrote to journald or nowhere, and Ansible kept no record of its runs. "What broke at 03:14, and what changed it" had no answer because the data was never written. Application logs and infrastructure run records need one shared envelope to land on one queryable timeline, and nine repos each writing their own logger would drift. One versioned package they all import does not.
How it works
Every record is a single-line JSON object. Five required fields (timestamp, level, service, host, message) are stamped by the package, never by the caller, so service names cannot be spelled five ways. Optional fields are correlation_id, event, error, duration_ms and context; any other key is moved into context. Exactly two fields, service and host, become Loki labels, because each extra label value creates a new index stream and a high-cardinality label would make Loki unusable. Secret-looking keys keep their name and have the value replaced with [REDACTED], recursively. Configuration is read once at start-up into a frozen object: a missing SERVICE_NAME or bad LOG_LEVEL fails closed, while an unwritable log file falls back to stdout with one loud warning.
Features
- Contract with RFC 2119 language and semver rules for wire changes
- Shared conformance fixture, with volatile fields matched by pattern
- Python package exporting init_observability, logger, with_context and with_logging (entry, exit and failure records with duration_ms)
- Recursive key-preserving redaction
- Background-thread file writes
- CI and a pre-push hook that run the same checks: fixture validity, contract/fixture version match, ruff, strict mypy, pytest (run as an unprivileged user so permission tests are real), and PR test selection by changed path
How it was built
The repository started on 2026-07-25 because the self-hosted services across about nine repositories had no log ingestion, and after an incident there was nothing to read.
The goal was one log envelope that application code and infrastructure tooling both emit, so a service's logs and the change that broke it land on one timeline.
It shipped as a version-pinned package rather than a document, because a document cannot be a dependency. The package stamps required fields so a service name is never spelled five ways.
Only two log labels are allowed, because one high-cardinality label would make the log store unusable. Redaction keeps the key and hides the value, and a missing log mount falls back to stdout instead of stopping start-up.
AI coding agents wrote the package, and Rico recorded every decision with its reason, including keeping Rust and Swift bindings on paper until someone imports them.