timberlogs-client 1.2.0

Official Timberlogs SDK for Python - structured logging made simple

Timberlogs Python SDK

The official Timberlogs SDK for Python applications. Send structured logs to Timberlogs with automatic batching, retry logic, and flow tracking.

Installation

pip install timberlogs-client

Quick Start

from timberlogs import create_timberlogs

timber = create_timberlogs(
    source="my-app",
    environment="production",
    api_key="tb_live_xxxxxxxxxxxxx",
)

timber.info("Hello, Timberlogs!")

Features

• Structured logging - Log with arbitrary JSON data
• Automatic batching - Efficiently batch logs before sending
• Retry with backoff - Automatic retry on failures
• Flow tracking - Group related logs together
• Level filtering - Filter logs by severity
• Async support - Full async/await support
• Context manager - Automatic cleanup with with statement

Basic Usage

Log Levels

timber.debug("Detailed diagnostic info", {"key": "value"})
timber.info("General information", {"user_id": "123"})
timber.warn("Warning condition", {"threshold": 90})
timber.error("Error occurred", {"code": "E001"})

Logging with Data

timber.info("User signed in", {
    "user_id": "user_123",
    "method": "oauth",
    "provider": "google",
})

Error Logging

# With Exception object (extracts name, message, stack)
try:
    risky_operation()
except Exception as e:
    timber.error("Operation failed", e)

# With data object
timber.error("Validation failed", {
    "field": "email",
    "reason": "invalid format",
})

Tags

from timberlogs import LogOptions

timber.info("Payment processed", {"amount": 99.99}, LogOptions(tags=["payments", "success"]))

Setting User/Session IDs

# Set defaults for all subsequent logs
timber.set_user_id("user_123")
timber.set_session_id("sess_abc")

# Clear on logout
timber.set_user_id(None)
timber.set_session_id(None)

Method Chaining

timber.set_user_id("user_123").set_session_id("sess_abc").info("User action")

Flow Tracking

Flows group related logs together with automatic step indexing:

# Synchronous flow (local ID generation)
flow = timber.flow("checkout")
flow.info("Started checkout", {"items": 3})
flow.info("Payment processed", {"amount": 99.99})
flow.info("Order confirmed", {"order_id": "ord_123"})

Async Flow (Server-Generated ID)

import asyncio

async def process_checkout():
    flow = await timber.flow_async("checkout")
    flow.info("Started checkout")
    flow.info("Payment processed")
    flow.info("Order confirmed")

asyncio.run(process_checkout())

Flow Properties

flow = timber.flow("user-onboarding")
print(flow.id)    # "user-onboarding-a1b2c3d4"
print(flow.name)  # "user-onboarding"

Configuration

All Options

from timberlogs import create_timberlogs

timber = create_timberlogs(
    # Required
    source="my-app",                    # Your app/service name
    environment="production",           # development, staging, production

    # Authentication
    api_key="tb_live_xxx",              # Your Timberlogs API key

    # Optional
    version="1.2.3",                    # Your app version
    user_id="user_123",                 # Default user ID
    session_id="sess_abc",              # Default session ID
    batch_size=10,                      # Logs to batch before sending
    flush_interval=5.0,                 # Auto-flush interval (seconds)
    min_level="info",                   # Minimum level to send
    on_error=lambda e: print(e),        # Error callback

    # Retry configuration
    max_retries=3,                      # Retry attempts
    initial_delay_ms=1000,              # Initial retry delay
    max_delay_ms=30000,                 # Maximum retry delay
)

Environment Variables

import os
from timberlogs import create_timberlogs

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

Level Filtering

timber = create_timberlogs(
    source="my-app",
    environment="production",
    api_key="tb_live_xxx",
    min_level="warn",  # Only send warn and error
)

timber.debug("Not sent")  # Filtered
timber.info("Not sent")   # Filtered
timber.warn("Sent")       # Sent
timber.error("Sent")      # Sent

Async Usage

import asyncio
from timberlogs import create_timberlogs

async def main():
    timber = create_timberlogs(
        source="my-app",
        environment="production",
        api_key="tb_live_xxx",
    )

    timber.info("Starting async operation")

    # Create async flow with server-generated ID
    flow = await timber.flow_async("async-job")
    flow.info("Step 1")
    flow.info("Step 2")

    # Async flush
    await timber.flush_async()

    # Async disconnect
    await timber.disconnect_async()

asyncio.run(main())

Async Context Manager

async def main():
    async with create_timberlogs(
        source="my-app",
        environment="production",
        api_key="tb_live_xxx",
    ) as timber:
        timber.info("Auto-flushed on exit")

Context Manager

with create_timberlogs(
    source="my-app",
    environment="production",
    api_key="tb_live_xxx",
) as timber:
    timber.info("Logs are auto-flushed on exit")

Low-Level Logging

For full control over log entries:

from timberlogs import LogEntry

timber.log(LogEntry(
    level="info",
    message="Custom log entry",
    data={"custom": "data"},
    user_id="user_123",
    session_id="sess_abc",
    request_id="req_xyz",
    tags=["important", "billing"],
))

API Reference

TimberlogsClient Methods

Method	Description
debug(message, data?, options?)	Log debug message
info(message, data?, options?)	Log info message
warn(message, data?, options?)	Log warning message
error(message, error_or_data?, options?)	Log error message
log(entry)	Log with full control
flow(name)	Create flow (local ID)
flow_async(name)	Create flow (server ID)
set_user_id(user_id)	Set default user ID
set_session_id(session_id)	Set default session ID
flush()	Send queued logs immediately
flush_async()	Async send queued logs
disconnect()	Flush and stop client
disconnect_async()	Async flush and stop
should_log(level)	Check if level passes filter

Flow Methods

Method	Description
debug(message, data?, options?)	Log debug message
info(message, data?, options?)	Log info message
warn(message, data?, options?)	Log warning message
error(message, error_or_data?, options?)	Log error message
id	Property: flow ID
name	Property: flow name

Releasing

1. Bump the version in pyproject.toml and timberlogs/__init__.py
2. Commit and push to master
3. Create a GitHub release with tag vX.Y.Z (e.g., v1.1.1)
4. The publish.yml workflow automatically builds and publishes to PyPI via OIDC trusted publishing

Requirements

• Python 3.8+
• httpx >= 0.24.0

License

MIT License - see LICENSE for details.

Links

• Documentation
• Dashboard
• GitHub