Get sentry-options working in your project with this step-by-step guide.
Installation Install the client library for your language:
Rust (Cargo.toml)
Python (pyproject.toml)
Python (pip)
[ dependencies ] sentry-options = "0.0.14"
Create a schema Define your configuration options in a JSON schema file. Create sentry-options/schemas/{namespace}/schema.json:
{ "version" : "1.0" , "type" : "object" , "properties" : { "feature.enabled" : { "type" : "boolean" , "default" : false , "description" : "Enable the feature" }, "feature.rate_limit" : { "type" : "integer" , "default" : 100 , "description" : "Rate limit per second" } } }
The namespace directory must match your repository name or be prefixed with it (e.g., seer, seer-autofix).
Supported types Type JSON Schema Example Default String "type": "string""default": "value"Integer "type": "integer""default": 42Float "type": "number""default": 3.14Boolean "type": "boolean""default": falseArray "type": "array""default": [1, 2, 3]
Array types require an items field: "items": {"type": "string"}. Nested arrays are not yet supported.
Use in your code
Initialize the library
Do this once during application startup: from sentry_options import init # Initialize early in your startup sequence init()
The library automatically loads schemas and values from:
SENTRY_OPTIONS_DIR environment variable, or/etc/sentry-options if it exists, orsentry-options/ in your working directory
Get an options namespace
from sentry_options import options # Get options for your namespace opts = options( 'my-service' )
Read option values
# Read values (returns schema default if not set) if opts.get( 'feature.enabled' ): rate = opts.get( 'feature.rate_limit' ) print ( f "Feature enabled with rate limit: { rate } " )
Values are validated against your schema. If no value is configured, the schema default is returned. Complete example Here’s a working example that reads options every 3 seconds:
from sentry_options import init, options import time # Initialize the library init() # Get options namespace testing = options( 'sentry-options-testing' ) # Read values periodically while True : time.sleep( 3 ) example_val = testing.get( 'example-option' ) float_val = testing.get( 'float-option' ) bool_val = testing.get( 'bool-option' ) string_val = testing.get( 'string-option' ) print ( f "values: { example_val } | { float_val } | { bool_val } | { string_val } " , flush = True , )
use std :: { thread :: sleep, time :: Duration }; use sentry_options :: {init, options}; fn main () -> anyhow :: Result <()> { // Initialize the library init () ? ; // Get options namespace let sentry_options = options ( "sentry-options-testing" ); // Read values periodically loop { sleep ( Duration :: from_secs ( 3 )); let string_value = sentry_options . get ( "example-option" ) ? ; let float_value = sentry_options . get ( "float-option" ) ? ; let bool_value = sentry_options . get ( "bool-option" ) ? ; println! ( "values: {} | {} | {}" , string_value , float_value , bool_value ); } }
Test locally Create a values file to override schema defaults for local development:
# Create values directory mkdir -p sentry-options/values/my-service # Create values file cat > sentry-options/values/my-service/values.json << 'EOF' { "options": { "feature.enabled": true, "feature.rate_limit": 200 } } EOF
The directory structure should look like:
sentry-options/ ├── schemas/ │ └── my-service/ │ └── schema.json └── values/ └── my-service/ └── values.json
Run your application and it will automatically pick up the values. Update values.json while the app is running to test hot-reload (changes detected within ~5 seconds).
For local testing, the library looks for sentry-options/ in your current working directory by default.
Next steps
Integration guide Complete guide to integrating sentry-options in production
API reference Full API documentation for Python and Rust clients
Schema definition Learn about schema format and validation rules
Hot-reload Understand how configuration updates work