Getting Started

Installation

Install the Timberlogs SDK using your preferred package manager.

TypeScript / JavaScript

npm install timberlogs-client

pnpm add timberlogs-client

yarn add timberlogs-client

Requirements: Node.js 16 or later. TypeScript 4.7+ optional but recommended.

Python

pip install timberlogs-client

uv add timberlogs-client

poetry add timberlogs-client

Requirements: Python 3.8 or later.

Rust

Cargo.toml

[dependencies]
timberlogs = "1"
tokio = { version = "1", features = ["rt-multi-thread", "macros"] }

Requirements: Rust 2021 edition or later. Tokio async runtime.

Get Your API Key

Sign up at app.timberlogs.dev and create a workspace. Navigate to Settings > API Keys and create a new key.Your API key will look like: tb_live_xxxxxxxxxxxxx

Initialize the Client

import { createTimberlogs } from 'timberlogs-client'

const timber = createTimberlogs({
  source: 'my-app',           // Your app/service name
  environment: 'production',   // development, staging, or production
  apiKey: process.env.TIMBER_API_KEY,
})

import os
from timberlogs import create_timberlogs

timber = create_timberlogs(
    source="my-app",
    environment="production",
    api_key=os.getenv("TIMBER_API_KEY"),
)

use timberlogs::TimberlogsClient;
use std::env;

let timber = TimberlogsClient::new(timberlogs::TimberlogsConfig {
    source: "my-app".into(),
    environment: timberlogs::Environment::Production,
    api_key: env::var("TIMBER_API_KEY").unwrap(),
    ..Default::default()
});

Send Your First Log

// Simple info log
timber.info('Application started')

// Log with data
timber.info('User signed in', {
  userId: 'user_123',
  email: 'user@example.com'
})

// Log a warning
timber.warn('Rate limit approaching', {
  current: 950,
  limit: 1000
})

// Log an error with stack trace
try {
  await riskyOperation()
} catch (error) {
  timber.error('Operation failed', error)
}

# Simple info log
timber.info("Application started")

# Log with data
timber.info("User signed in", {
    "user_id": "user_123",
    "email": "user@example.com"
})

# Log a warning
timber.warn("Rate limit approaching", {
    "current": 950,
    "limit": 1000
})

# Log an error with stack trace
try:
    risky_operation()
except Exception as e:
    timber.error("Operation failed", e)

use serde_json::json;

// Simple info log
timber.info("Application started", None);

// Log with data
timber.info("User signed in", Some(json!({
    "user_id": "user_123",
    "email": "user@example.com"
})));

// Log a warning
timber.warn("Rate limit approaching", Some(json!({
    "current": 950,
    "limit": 1000
})));

// Log an error
timber.error("Operation failed", Some(json!({
    "error": "connection timeout"
})));

View in Dashboard

Head to app.timberlogs.dev and select your workspace. Your logs will appear in the Logs view within seconds.

Flush on Exit (Important!)

The SDK batches logs for efficiency. Make sure to flush before your process exits:

// Before shutdown
await timber.flush()

// Or use disconnect which flushes automatically
await timber.disconnect()

# Before shutdown
timber.flush()

# Or use disconnect which flushes automatically
timber.disconnect()

# Or use a context manager for automatic cleanup
with create_timberlogs(...) as timber:
    timber.info("Auto-flushed on exit")

// Before shutdown
timber.flush().await;

// Or use disconnect which flushes automatically
timber.disconnect().await;

Example: Express.js

import express from 'express'
import { createTimberlogs } from 'timberlogs-client'

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

app.use((req, res, next) => {
  timber.info('Request received', {
    method: req.method,
    path: req.path,
    ip: req.ip,
  })
  next()
})

app.get('/health', (req, res) => {
  res.json({ status: 'ok' })
})

// Graceful shutdown
process.on('SIGTERM', async () => {
  await timber.flush()
  process.exit(0)
})

app.listen(3000)

Example: FastAPI

import os
from contextlib import asynccontextmanager
from fastapi import FastAPI, Request
from timberlogs import create_timberlogs

timber = create_timberlogs(
    source="api-server",
    environment=os.getenv("ENVIRONMENT", "development"),
    api_key=os.getenv("TIMBER_API_KEY"),
)

@asynccontextmanager
async def lifespan(app: FastAPI):
    yield
    timber.disconnect()

app = FastAPI(lifespan=lifespan)

@app.middleware("http")
async def log_requests(request: Request, call_next):
    timber.info("Request received", {
        "method": request.method,
        "path": request.url.path,
        "ip": request.client.host,
    })
    return await call_next(request)

@app.get("/health")
def health():
    return {"status": "ok"}

Example: Actix Web

use actix_web::{web, App, HttpServer, HttpRequest, HttpResponse, middleware};
use timberlogs::{TimberlogsClient, TimberlogsConfig, Environment};
use std::env;

#[actix_web::main]
async fn main() -> std::io::Result<()> {
    let timber = TimberlogsClient::new(TimberlogsConfig {
        source: "api-server".into(),
        environment: Environment::Production,
        api_key: env::var("TIMBER_API_KEY").unwrap(),
        ..Default::default()
    });

    let timber = web::Data::new(timber);

    HttpServer::new(move || {
        App::new()
            .app_data(timber.clone())
            .route("/health", web::get().to(health))
    })
    .bind("0.0.0.0:3000")?
    .run()
    .await
}

async fn health() -> HttpResponse {
    HttpResponse::Ok().json(serde_json::json!({"status": "ok"}))
}

Query Logs from the Terminal

Install the Timberlogs CLI to search and filter logs without leaving your terminal:

npm install -g timberlogs-cli
timberlogs login
timberlogs logs --level error --from 1h

Next Steps

Learn about all configuration options
Explore the SDK reference: TypeScript | Python | Rust
Query logs from the terminal with the CLI
Track user flows with Flow Tracking

Ready to start logging? Sign up free — send your first log in under 5 minutes.

Core Concepts

API Reference

Dashboard

TypeScript SDK

Python SDK

Rust SDK

CLI

Getting Started

Installation

TypeScript / JavaScript

Python

Rust

Example: Express.js

Example: FastAPI

Example: Actix Web

Query Logs from the Terminal

Next Steps

​Installation

​TypeScript / JavaScript

​Python

​Rust

​Example: Express.js

​Example: FastAPI

​Example: Actix Web

​Query Logs from the Terminal

​Next Steps

Installation

TypeScript / JavaScript

Python

Rust

Example: Express.js

Example: FastAPI

Example: Actix Web

Query Logs from the Terminal

Next Steps