Configuration

Full reference for all SDK configuration options.

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
  endpoint: 'https://...',   // Required for HTTP transport
})

Option	Type	Description
`source`	`string`	Your application or service name. Used to filter logs.
`environment`	`'development' \| 'staging' \| 'production'`	The environment your app is running in.
`apiKey`	`string`	Your Timberlogs API key (starts with `tb_live_` or `tb_test_`).
`endpoint`	`string`	The ingestion endpoint URL.

Optional Options


const timber = createTimberlogs({
  source: 'my-app',
  environment: 'production',
  apiKey: process.env.TIMBER_API_KEY,
  endpoint: 'https://timberlogs-ingest.enaboapps.workers.dev/v1/logs',
 
  // Optional settings
  version: '1.2.3',           // Your app version
  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,
  },
})

Option	Type	Default	Description
`version`	`string`	-	Your application version (e.g., `'1.2.3'`).
`userId`	`string`	-	Default user ID attached to all logs.
`sessionId`	`string`	-	Default session ID attached to all logs.
`batchSize`	`number`	`10`	Number of logs to batch before sending.
`flushInterval`	`number`	`5000`	Milliseconds between auto-flush.
`minLevel`	`LogLevel`	`'debug'`	Minimum level to send (`debug`, `info`, `warn`, `error`).
`onError`	`function`	-	Called when sending fails after all retries.
`retry`	`object`	See below	Retry 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)

Environment Variables

We recommend storing sensitive values in environment variables:


# .env
TIMBER_API_KEY=tb_live_xxxxxxxxxxxxx
TIMBER_ENDPOINT=https://timberlogs-ingest.enaboapps.workers.dev/v1/logs


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