Welcome
This documentation aims to be a comprehensive guide to Detent. We’ll cover publishing knobs, reading them from C++, Python, Rust and the shell, rolling features out gradually, running the durable authority, deploying the daemons as system services, and how the whole thing works underneath.
So what is Detent, exactly?
Section titled “So what is Detent, exactly?”Detent is a runtime-configuration system for namespaced boolean and integer knobs. Applications read knobs synchronously from an in-memory snapshot; a background thread keeps that snapshot fresh from a file, an HTTP endpoint, or a durable authority, and swaps each validated update in atomically.
A detent is the click-stop that holds a knob at its setting. That’s the idea: your process always sees a complete, validated configuration, never something half-turned.
Detent has three moving parts:
detent::Client, the library your application links. It owns the read path, the evaluation rules and the background updater.detent-authority, the durable authority. Publishers open authenticated sessions and submit atomic, per-namespace transactions; it commits them through durable Raft consensus and delivers them to managed agents.detent-agentanddetent, the host-local agent and its shell reader. One agent per host receives deliveries and publishes immutable generations, sodetent get NAMEreads local files rather than the network, from any script or language.
The knob model, with its names, groups, overrides, rollout and evaluation
rules, is specified in
docs/design/knob-model.md.
Document Conventions
Section titled “Document Conventions”Throughout this guide there are a few conventions in the way documentation is laid out and formatted.
API Snippets
Section titled “API Snippets”Examples of HTTP calls to the durable authority look like this:
GET /v1/healthFor those, you can always copy the equivalent curl command, aimed at a local
detent-authority on its default port 8317, by hovering over the snippet and clicking
the copy-to-clipboard button.
Helpful Hints
Section titled “Helpful Hints”A number of small-but-handy pieces of information can make using Detent easier, more interesting, and less hazardous. Here’s what to look out for:
If you come across anything along the way that we haven’t covered, or if you know of a tip you think others would find handy, please file an issue and we’ll see about including it in this guide.