Skip to main content

​
Required Options

const timber = createTimberlogs({
  source: 'my-app',         // Required: identifies your app/service
  environment: 'production', // Required: development, staging, or production
  apiKey: 'tb_live_xxx',     // Required for HTTP transport
})
OptionTypeDescription
sourcestringYour application or service name. Used to filter logs.
environment'development' | 'staging' | 'production'The environment your app is running in.
apiKeystringYour Timberlogs API key (starts with tb_live_ or tb_test_).

​
Optional Options

const timber = createTimberlogs({
  source: 'my-app',
  environment: 'production',
  apiKey: process.env.TIMBER_API_KEY,

  // Optional settings
  version: '1.2.3',           // Your app version
  dataset: 'analytics',       // Default dataset for log routing
  userId: 'user_123',         // Default user ID for all logs
  sessionId: 'sess_abc',      // Default session ID
  batchSize: 10,              // Logs to batch before sending
  flushInterval: 5000,        // Auto-flush interval in ms
  minLevel: 'info',           // Minimum log level to send
  onError: (err) => {},       // Error callback
  retry: {
    maxRetries: 3,
    initialDelayMs: 1000,
    maxDelayMs: 30000,
  },
})
OptionTypeDefaultDescription
versionstring-Your application version (e.g., '1.2.3').
datasetstring'default'Default dataset for grouping/routing logs.
userIdstring-Default user ID attached to all logs.
sessionIdstring-Default session ID attached to all logs.
batchSizenumber10Number of logs to batch before sending.
flushIntervalnumber5000Milliseconds between auto-flush.
minLevelLogLevel'debug'Minimum level to send (debug, info, warn, error).
onErrorfunction-Called when sending fails after all retries.
retryobjectSee belowRetry configuration for failed requests.

​
Retry Configuration

The SDK automatically retries failed requests with exponential backoff. 
{
  retry: {
    maxRetries: 3,        // Number of retry attempts
    initialDelayMs: 1000, // First retry delay
    maxDelayMs: 30000,    // Maximum delay between retries
  }
}

​
Log Level Filtering

Use minLevel to filter out lower-priority logs: 
const timber = createTimberlogs({
  // ...
  minLevel: 'warn', // Only send warn and error logs
})

timber.debug('This will NOT be sent')
timber.info('This will NOT be sent')
timber.warn('This WILL be sent')
timber.error('This WILL be sent')

​
Setting User/Session at Runtime

You can update the user and session IDs after initialization: 
// After user logs in
timber.setUserId('user_123')
timber.setSessionId('sess_abc')

// Clear on logout
timber.setUserId(undefined)
timber.setSessionId(undefined)

​
Validation Limits

Both SDKs validate fields before sending. Logs that exceed these limits will be rejected.
FieldLimit
message1–10,000 characters
source1–100 characters
errorNameMax 200 characters
errorStackMax 10,000 characters
userId, sessionId, requestIdMax 100 characters each
flowId, datasetMax 50 characters each
stepIndex0–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

const timber = createTimberlogs({
  source: 'my-app',
  environment: process.env.NODE_ENV || 'development',
  apiKey: process.env.TIMBER_API_KEY,
})