Skip to content

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.

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:

  1. detent::Client, the library your application links. It owns the read path, the evaluation rules and the background updater.
  2. 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.
  3. detent-agent and detent, the host-local agent and its shell reader. One agent per host receives deliveries and publishes immutable generations, so detent get NAME reads 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.


Throughout this guide there are a few conventions in the way documentation is laid out and formatted.

Examples of HTTP calls to the durable authority look like this:

GET /v1/health

For 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.

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.