> ## Documentation Index
> Fetch the complete documentation index at: https://docs.timberlogs.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Configuration

> Full reference for all Rust SDK configuration options.

## Required Options

```rust theme={null}
use timberlogs::{TimberlogsClient, TimberlogsConfig, Environment};

let client = TimberlogsClient::new(TimberlogsConfig {
    source: "my-app".into(),           // Required: identifies your app/service
    environment: Environment::Production, // Required: Development, Staging, or Production
    api_key: "tb_live_xxx".into(),     // Required for HTTP transport
    ..Default::default()
});
```

| Option        | Type          | Description                                                     |
| ------------- | ------------- | --------------------------------------------------------------- |
| `source`      | `String`      | Your application or service name. Used to filter logs.          |
| `environment` | `Environment` | `Development`, `Staging`, or `Production`.                      |
| `api_key`     | `String`      | Your Timberlogs API key (starts with `tb_live_` or `tb_test_`). |

## Optional Options

```rust theme={null}
use timberlogs::{TimberlogsClient, TimberlogsConfig, Environment, LogLevel, RetryConfig};

let client = TimberlogsClient::new(TimberlogsConfig {
    source: "my-app".into(),
    environment: Environment::Production,
    api_key: std::env::var("TIMBER_API_KEY").unwrap(),

    // Optional settings
    version: Some("1.2.3".into()),
    dataset: Some("analytics".into()),
    user_id: Some("user_123".into()),
    session_id: Some("sess_abc".into()),
    batch_size: Some(10),
    flush_interval_ms: Some(5000),
    min_level: Some(LogLevel::Info),
    on_error: Some(Box::new(|err| {
        eprintln!("Timberlogs error: {err}");
    })),
    retry: Some(RetryConfig {
        max_retries: 3,
        initial_delay_ms: 1000,
        max_delay_ms: 30000,
    }),
    ..Default::default()
});
```

| Option              | Type                    | Default   | Description                                               |
| ------------------- | ----------------------- | --------- | --------------------------------------------------------- |
| `version`           | `Option<String>`        | `None`    | Your application version (e.g., `"1.2.3"`).               |
| `dataset`           | `Option<String>`        | `None`    | Default dataset for grouping/routing logs.                |
| `user_id`           | `Option<String>`        | `None`    | Default user ID attached to all logs.                     |
| `session_id`        | `Option<String>`        | `None`    | Default session ID attached to all logs.                  |
| `batch_size`        | `Option<usize>`         | `10`      | Number of logs to batch before sending. Must be > 0.      |
| `flush_interval_ms` | `Option<u64>`           | `5000`    | Milliseconds between auto-flush.                          |
| `min_level`         | `Option<LogLevel>`      | `Debug`   | Minimum level to send (`Debug`, `Info`, `Warn`, `Error`). |
| `on_error`          | `Option<ErrorCallback>` | `None`    | Called when background flush fails after all retries.     |
| `retry`             | `Option<RetryConfig>`   | See below | Retry configuration for failed requests.                  |

## Retry Configuration

The SDK automatically retries failed requests with exponential backoff.

```rust theme={null}
use timberlogs::RetryConfig;

RetryConfig {
    max_retries: 3,        // Number of retry attempts
    initial_delay_ms: 1000, // First retry delay
    max_delay_ms: 30000,    // Maximum delay between retries
}
```

## Log Level Filtering

Use `min_level` to filter out lower-priority logs:

```rust theme={null}
let client = TimberlogsClient::new(TimberlogsConfig {
    min_level: Some(LogLevel::Warn), // Only send warn and error logs
    ..Default::default()
});

client.debug("This will NOT be sent", None).await?;
client.info("This will NOT be sent", None).await?;
client.warn("This WILL be sent", None).await?;
client.error("This WILL be sent", None).await?;
```

## Setting User/Session at Runtime

You can update the user and session IDs after initialization:

```rust theme={null}
// After user logs in
client.set_user_id(Some("user_123".into())).await;
client.set_session_id(Some("sess_abc".into())).await;

// Clear on logout
client.set_user_id(None).await;
client.set_session_id(None).await;
```

## Validation Limits

The SDK validates fields before sending. Logs that exceed these limits will return a `TimberlogsError::Validation` error.

| Field                                 | Limit                            |
| ------------------------------------- | -------------------------------- |
| `message`                             | 1–10,000 characters              |
| `error_name`                          | Max 200 characters               |
| `error_stack`                         | Max 10,000 characters            |
| `user_id`, `session_id`, `request_id` | Max 100 characters each          |
| `flow_id`, `dataset`                  | Max 50 characters each           |
| `ip_address`                          | Max 100 characters               |
| `country`                             | Max 10 characters                |
| `step_index`                          | 0–1,000                          |
| `tags`                                | Max 20 items, 50 characters each |

## Environment Variables

We recommend storing sensitive values in environment variables:

```bash theme={null}
# .env
TIMBER_API_KEY=tb_live_xxxxxxxxxxxxx
```

```rust theme={null}
let client = TimberlogsClient::new(TimberlogsConfig {
    source: "my-app".into(),
    environment: Environment::Production,
    api_key: std::env::var("TIMBER_API_KEY").expect("TIMBER_API_KEY required"),
    ..Default::default()
});
```