Skip to main content
Sentry Options is a file-based configuration system that replaces database-stored options with git-managed, schema-validated config files. Services read options directly from mounted files with automatic hot-reload when values change.

​
Why sentry-options?

Traditional database-backed configuration systems introduce latency, complexity, and operational overhead. Sentry Options solves these problems by moving configuration to version-controlled files with built-in validation and hot-reload support.

Quickstart

Get started in minutes with our step-by-step guide for Rust and Python

Integration guide

Complete setup guide for integrating sentry-options into your service

API reference

Detailed API documentation for Rust and Python clients

Architecture

Learn how sentry-options works under the hood

​
Key features

Options are loaded into memory on initialization. File reads only happen during init and hot-reload events, providing sub-millisecond access times in your application code.
JSON schemas define your configuration structure with strict type checking. The system validates all values against schemas at build time and runtime, catching configuration errors before they reach production.
Configuration changes propagate automatically within 1-2 minutes without requiring pod restarts. The client library polls for file changes every 5 seconds and atomically reloads values when detected.
All configuration changes are tracked in git, providing complete audit history with blame, diffs, and rollback capabilities. No more wondering who changed what and when.
First-class clients for both Rust and Python with identical APIs. The Python client uses PyO3 bindings over the Rust implementation for performance and consistency.
Built for Kubernetes with automatic ConfigMap generation and injection. The CLI validates YAML against schemas and generates ConfigMaps ready for deployment.

​
How it works

Sentry Options follows a simple three-phase workflow:

​
Build time

Your service repository contains JSON schemas that define available options with types and defaults. These schemas are baked into your Docker image: 
# Copy schemas into image (enables validation and defaults)
COPY sentry-options/schemas /etc/sentry-options/schemas

ENV SENTRY_OPTIONS_DIR=/etc/sentry-options

​
CI/CD pipeline

The sentry-options-automator repository contains YAML files with runtime values. The CLI validates these values against your schemas, merges target-specific overrides, and generates ConfigMaps: 
sentry-options-cli write \
  --schemas schemas/ \
  --root option-values/ \
  --output-format configmap \
  --namespace seer \
  --target us

​
Runtime

Your application initializes the client library once at startup. The library validates values against schemas, provides defaults when values are missing, and automatically reloads when files change: 
from sentry_options import init, options

# Initialize early in startup
init()

# Get options namespace
opts = options('seer')

# Read values (returns schema default if not set)
if opts.get('feature.enabled'):
    rate = opts.get('feature.rate_limit')

​
Real-world use case

At Sentry, we use sentry-options to manage configuration for dozens of microservices across multiple regions. Here’s a typical scenario: Problem: The Seer service needs to gradually roll out a new autofix feature. The team wants to:
  • Enable the feature for specific organizations first
  • Apply different rate limits per region
  • Make adjustments without deploying new code
  • Track all configuration changes in git
Solution: Define a schema with feature flags and limits, then manage values through git:
Schema (seer repo)
{
  "version": "1.0",
  "type": "object",
  "properties": {
    "autofix.enabled": {
      "type": "boolean",
      "default": false,
      "description": "Enable autofix feature"
    },
    "autofix.rate_limit": {
      "type": "integer",
      "default": 100,
      "description": "Requests per second"
    },
    "autofix.enabled_orgs": {
      "type": "array",
      "items": {"type": "string"},
      "default": [],
      "description": "Organizations with early access"
    }
  }
}
Values (automator repo)
# option-values/seer/default/values.yaml
options:
  autofix.enabled: true
  autofix.rate_limit: 100
  autofix.enabled_orgs: ["sentry", "getsentry"]

# option-values/seer/us/values.yaml
options:
  autofix.rate_limit: 200  # Higher limit for US region
The team can now adjust these values via pull requests, with changes propagating to production within 1-2 minutes - no code deploys required.

​
Next steps

Quickstart

Install the client library and run your first example

Integration guide

Full setup guide for new services

Build docs developers (and LLMs) love

Get started for freeTalk to us