Skip to main content

​
Required Options

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()
});
OptionTypeDescription
sourceStringYour application or service name. Used to filter logs.
environmentEnvironmentDevelopment, Staging, or Production.
api_keyStringYour Timberlogs API key (starts with tb_live_ or tb_test_).

​
Optional Options

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()
});
OptionTypeDefaultDescription
versionOption<String>NoneYour application version (e.g., "1.2.3").
datasetOption<String>NoneDefault dataset for grouping/routing logs.
user_idOption<String>NoneDefault user ID attached to all logs.
session_idOption<String>NoneDefault session ID attached to all logs.
batch_sizeOption<usize>10Number of logs to batch before sending. Must be > 0.
flush_interval_msOption<u64>5000Milliseconds between auto-flush.
min_levelOption<LogLevel>DebugMinimum level to send (Debug, Info, Warn, Error).
on_errorOption<ErrorCallback>NoneCalled when background flush fails after all retries.
retryOption<RetryConfig>See belowRetry configuration for failed requests.

​
Retry Configuration

The SDK automatically retries failed requests with exponential backoff. 
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: 
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: 
// 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.
FieldLimit
message1–10,000 characters
error_nameMax 200 characters
error_stackMax 10,000 characters
user_id, session_id, request_idMax 100 characters each
flow_id, datasetMax 50 characters each
ip_addressMax 100 characters
countryMax 10 characters
step_index0–1,000
tagsMax 20 items, 50 characters each

​
Environment Variables

We recommend storing sensitive values in environment variables: 
# .env
TIMBER_API_KEY=tb_live_xxxxxxxxxxxxx

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