Skip to main content

​
Installation

Add the sentry-options crate to your Cargo.toml:
Cargo.toml
[dependencies]
sentry-options = "0.0.14"

​
Quick start

use sentry_options::{init, options};

fn main() -> anyhow::Result<()> {
    // Initialize the global options store
    init()?;
    
    // Get a namespace handle
    let opts = options("sentry-options-testing");
    
    // Read option values
    let value = opts.get("example-option")?;
    println!("Option value: {}", value);
    
    Ok(())
}

​
Functions

​
init()

Initialize global options using fallback chain: SENTRY_OPTIONS_DIR env var, then /etc/sentry-options if it exists, otherwise sentry-options/.
​
return
Result<()>
Returns Ok(()) on success, or OptionsError::AlreadyInitialized if already initialized.
Example 
use sentry_options::init;

fn main() -> Result<(), Box<dyn std::error::Error>> {
    init()?;
    Ok(())
}

​
options(namespace)

Get a namespace handle for accessing options.
​
namespace
&str
required
The namespace to access
​
return
NamespaceOptions
Returns a handle for accessing options within the specified namespace.
Panics Panics if init() has not been called. Example 
use sentry_options::{init, options};

fn main() -> anyhow::Result<()> {
    init()?;
    let sentry_options = options("sentry-options-testing");
    
    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);
    Ok(())
}

​
Options struct

Options store for reading configuration values.

​
Options::new()

Load options using fallback chain: SENTRY_OPTIONS_DIR env var, then /etc/sentry-options if it exists, otherwise sentry-options/. Expects {dir}/schemas/ and {dir}/values/ subdirectories.
​
return
Result<Self>
Returns a new Options instance, or an OptionsError if initialization fails.
Example 
use sentry_options::Options;

let options = Options::new()?;
let value = options.get("my-namespace", "my-option")?;

​
Options::from_directory(base_dir)

Load options from a specific directory (useful for testing). Expects {base_dir}/schemas/ and {base_dir}/values/ subdirectories.
​
base_dir
&Path
required
The base directory containing schemas/ and values/ subdirectories
​
return
Result<Self>
Returns a new Options instance, or an OptionsError if initialization fails.
Example 
use sentry_options::Options;
use std::path::Path;

let options = Options::from_directory(Path::new("/custom/path"))?;
let value = options.get("test", "enabled")?;

​
Options::get(namespace, key)

Get an option value, returning the schema default if not set.
​
namespace
&str
required
The namespace to query
​
key
&str
required
The option key to retrieve
​
return
Result<Value>
Returns the option value as serde_json::Value, or an OptionsError if the namespace or option is unknown.
Example 
use sentry_options::Options;
use serde_json::json;

let options = Options::new()?;
let value = options.get("test", "enabled")?;
assert_eq!(value, json!(true));

​
Options::isset(namespace, key)

Check if an option has a value. Returns true if the option is defined and has a value, will return false if the option is defined and does not have a value. If the namespace or option are not defined, an Err will be returned.
​
namespace
&str
required
The namespace to query
​
key
&str
required
The option key to check
​
return
Result<bool>
Returns true if the option has a value, false if using default, or an OptionsError if the namespace or option is unknown.
Example 
use sentry_options::Options;

let options = Options::new()?;
let has_value = options.isset("test", "enabled")?;
if has_value {
    println!("Option has an explicit value");
} else {
    println!("Option is using default value");
}

​
NamespaceOptions struct

Handle for accessing options within a specific namespace.

​
NamespaceOptions::get(key)

Get an option value, returning the schema default if not set.
​
key
&str
required
The option key to retrieve
​
return
Result<Value>
Returns the option value as serde_json::Value, or an OptionsError if the option is unknown.
Example 
use sentry_options::{init, options};

fn main() -> anyhow::Result<()> {
    init()?;
    let sentry_options = options("sentry-options-testing");
    
    loop {
        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);
        std::thread::sleep(std::time::Duration::from_secs(3));
    }
}

​
NamespaceOptions::isset(key)

Check if an option has a key defined, or if the default is being used.
​
key
&str
required
The option key to check
​
return
Result<bool>
Returns true if the option has a value, false if using default, or an OptionsError if the option is unknown.
Example 
use sentry_options::{init, options};

fn main() -> anyhow::Result<()> {
    init()?;
    let opts = options("sentry-options-testing");
    
    if opts.isset("example-option")? {
        println!("Option has explicit value: {}", opts.get("example-option")?);
    } else {
        println!("Option using default value");
    }
    
    Ok(())
}

​
Error types

​
OptionsError

Enum representing all possible errors in the options system.

​
Variants

​
UnknownNamespace
String
Unknown namespace error. Contains the namespace name that was not found.
​
UnknownOption
{ namespace: String, key: String }
Unknown option error. Contains the namespace and option key that were not found.
​
Schema
ValidationError
Schema error. Wraps validation errors from schema loading or validation failures.
​
AlreadyInitialized
Options already initialized error. Raised when init() is called more than once.
Example 
use sentry_options::{init, options, OptionsError};

fn main() {
    init().unwrap();
    let opts = options("unknown-namespace");
    
    match opts.get("some-key") {
        Ok(value) => println!("Value: {}", value),
        Err(OptionsError::UnknownNamespace(ns)) => {
            eprintln!("Unknown namespace: {}", ns);
        }
        Err(OptionsError::UnknownOption { namespace, key }) => {
            eprintln!("Unknown option '{}' in namespace '{}'", key, namespace);
        }
        Err(e) => eprintln!("Error: {}", e),
    }
}

​
Complete example

examples/rust/src/main.rs
use std::{thread::sleep, time::Duration};

use sentry_options::{init, options};

/// An example usage of the Rust options client library
/// Every 3 seconds, prints out the value of example-option, float-option, and bool-option
///
/// Updating values in `../values` will be reflected in stdout
/// ^C to exit
fn main() -> anyhow::Result<()> {
    init()?;
    let sentry_options = options("sentry-options-testing");

    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
        );
    }
}

Build docs developers (and LLMs) love

Get started for freeTalk to us