Logging Methods

Detailed reference for all logging methods in the Timberlogs SDK.

Log Levels

Timberlogs supports four log levels, in order of severity:

Level	Use Case
`debug`	Detailed diagnostic information for debugging
`info`	General operational messages
`warn`	Warning conditions that might need attention
`error`	Error conditions that require immediate attention

Convenience Methods

`debug(message, data?, options?)`

Log debug-level messages for detailed diagnostic information.


// Simple debug
timber.debug('Cache lookup')
 
// With data
timber.debug('Cache hit', {
  key: 'user:123',
  ttl: 3600,
})
 
// With tags
timber.debug('Cache miss', { key: 'user:456' }, {
  tags: ['cache', 'performance'],
})

`info(message, data?, options?)`

Log informational messages about normal operations.


timber.info('User signed in', {
  userId: 'user_123',
  method: 'oauth',
})
 
timber.info('Order placed', {
  orderId: 'ord_xyz',
  total: 99.99,
})

`warn(message, data?, options?)`

Log warning conditions that might indicate a problem.


timber.warn('Rate limit approaching', {
  current: 950,
  limit: 1000,
  endpoint: '/api/users',
})
 
timber.warn('Deprecated API called', {
  endpoint: '/v1/legacy',
  recommendation: 'Use /v2/modern instead',
})

`error(message, errorOrData?, options?)`

Log errors. Accepts either an Error object or a data object.


// With Error object (extracts name, message, stack)
try {
  await riskyOperation()
} catch (err) {
  timber.error('Operation failed', err)
}
 
// With data object
timber.error('Validation failed', {
  field: 'email',
  value: 'invalid',
  reason: 'Invalid email format',
})
 
// With tags
timber.error('Payment failed', error, {
  tags: ['payments', 'critical'],
})

When you pass an Error object, the SDK automatically extracts:

errorName - The error’s constructor name
errorStack - The full stack trace
The error message is included in the data

Low-Level Method

`log(entry)`

Full control over the log entry. Use this when you need to set all fields explicitly.


timber.log({
  level: 'info',
  message: 'Custom log entry',
  data: {
    custom: 'data',
    nested: { value: 123 },
  },
  userId: 'user_123',
  sessionId: 'sess_abc',
  requestId: 'req_xyz',
  tags: ['important', 'billing'],
})

LogEntry Interface


interface LogEntry {
  level: 'debug' | 'info' | 'warn' | 'error'
  message: string
  data?: Record<string, unknown>
  userId?: string
  sessionId?: string
  requestId?: string
  errorName?: string
  errorStack?: string
  tags?: string[]
  flowId?: string
  stepIndex?: number
}

Data Object

The data parameter accepts any JSON-serializable object:


timber.info('Request completed', {
  // Primitives
  status: 200,
  duration: 123.45,
  cached: true,
 
  // Nested objects
  user: {
    id: 'user_123',
    role: 'admin',
  },
 
  // Arrays
  permissions: ['read', 'write', 'delete'],
})

Method Chaining

All logging methods return this for chaining:


timber
  .info('Step 1: Validation passed')
  .info('Step 2: Processing started')
  .debug('Debug details', { internal: true })
  .info('Step 3: Complete')

Filtering by Level

Use the minLevel config option to filter logs by severity:


const timber = createTimberlogs({
  // ...
  minLevel: 'warn', // Only send warn and error
})
 
timber.debug('Not sent')  // Filtered out
timber.info('Not sent')   // Filtered out
timber.warn('Sent')       // Sent
timber.error('Sent')      // Sent

Level order: debug < info < warn < error

Best Practices

Use Appropriate Levels


// Debug: Diagnostic details
timber.debug('SQL query executed', { query, duration })
 
// Info: Business events
timber.info('Order shipped', { orderId, trackingNumber })
 
// Warn: Potential issues
timber.warn('Retry attempt', { attempt: 2, maxRetries: 3 })
 
// Error: Failures
timber.error('Database connection failed', error)

Include Context


// Include identifiers for correlation
timber.info('Request processed', {
  requestId: req.id,
  userId: req.user.id,
  duration: Date.now() - start,
})

Use Structured Data


// Prefer structured data over string interpolation
// Good
timber.info('User updated', { userId: '123', field: 'email' })
 
// Avoid
timber.info(`User 123 updated their email`)