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()
});
| 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
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.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
Usemin_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 aTimberlogsError::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:# .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()
});