Timberlogs TypeScript SDK

A lightweight, flexible TypeScript SDK for structured logging with Timberlogs.

Installation

npm install timberlogs-client
# or
pnpm add timberlogs-client
# or
yarn add timberlogs-client

Quick Start

import { createTimberlogs } from "timberlogs-client";

const logger = createTimberlogs({
  source: "my-app",
  environment: "production",
  apiKey: "your-api-key",
});

// Log messages at different levels
logger.debug("Debug information", { details: "..." });
logger.info("User logged in", { userId: "123" });
logger.warn("Rate limit approaching", { current: 95, limit: 100 });
logger.error("Payment failed", new Error("Insufficient funds"));

Features

• Multiple log levels: debug, info, warn, error
• Structured logging: Attach arbitrary data to logs
• Tags support: Categorize logs with tags
• Automatic batching: Efficiently send logs in batches
• Retry with backoff: Automatic retries on failure
• User/Session tracking: Track logs by user and session
• Flexible transport: HTTP transport with automatic retries

Configuration

const logger = createTimberlogs({
  // Required
  source: "my-app",           // Your application name
  environment: "production",   // development | staging | production
  apiKey: "your-api-key",     // Your Timberlogs API key

  // Optional
  version: "1.0.0",            // App version
  userId: "user-123",          // Default user ID
  sessionId: "session-abc",    // Default session ID
  batchSize: 10,               // Logs to batch before sending (default: 10)
  flushInterval: 5000,         // Auto-flush interval in ms (default: 5000)
  minLevel: "debug",           // Minimum log level (default: debug)

  // Error handling
  onError: (error) => console.error("Logging error:", error),

  // Retry configuration
  retry: {
    maxRetries: 3,
    initialDelayMs: 1000,
    maxDelayMs: 30000,
  },
});

Usage

Basic Logging

logger.debug("Debug message");
logger.info("Info message", { key: "value" });
logger.warn("Warning message");
logger.error("Error message", new Error("Something went wrong"));

With Tags

logger.info("User action", { action: "click" }, { tags: ["analytics", "ui"] });
logger.error("Auth failed", error, { tags: ["auth", "security"] });

// Or using the log method
logger.log({
  level: "info",
  message: "Feature enabled",
  tags: ["feature-flag", "experiment-a"],
});

User and Session Tracking

// Set for all subsequent logs
logger.setUserId("user-123");
logger.setSessionId("session-abc");

// Now all logs include these IDs
logger.info("Action performed"); // Includes userId and sessionId

// Chainable
logger
  .setUserId("user-456")
  .setSessionId("session-xyz")
  .info("Logged in");

Flow Tracking

Track related logs across multi-step processes. Note: Flow tracking requires an apiKey to be configured, as flow IDs are generated server-side.

// Create a flow (async operation)
const flow = await logger.flow("checkout");

// All flow logs share the same flowId with auto-incrementing stepIndex
flow.info("Started checkout", { userId: "123" });
flow.info("Validated cart", { items: 3 });
flow.info("Payment processed", { amount: 99.99 });
flow.info("Order confirmed", { orderId: "ord_456" });

// Access flow properties
console.log(flow.id);   // "checkout-a1b2c3d4"
console.log(flow.name); // "checkout"

Manual Flush

// Force send all queued logs immediately
await logger.flush();

// Disconnect and flush before shutdown
await logger.disconnect();

API Reference

createTimberlogs(config)

Creates a new Timberlogs client instance.

TimberlogsClient

Methods

| Method | Description | |--------|-------------| | debug(message, data?, options?) | Log a debug message | | info(message, data?, options?) | Log an info message | | warn(message, data?, options?) | Log a warning message | | error(message, error?, options?) | Log an error message | | log(entry) | Log with full control over entry | | flow(name) | Create a flow for tracking related logs (async) | | setUserId(userId) | Set user ID for subsequent logs | | setSessionId(sessionId) | Set session ID for subsequent logs | | flush() | Immediately send all queued logs | | disconnect() | Flush and stop the client |

Types

type LogLevel = "debug" | "info" | "warn" | "error";
type Environment = "development" | "staging" | "production";

interface LogEntry {
  level: LogLevel;
  message: string;
  data?: Record<string, unknown>;
  userId?: string;
  sessionId?: string;
  requestId?: string;
  errorName?: string;
  errorStack?: string;
  tags?: string[];
  flowId?: string;
  stepIndex?: number;
}

Releasing

1. Bump the version in package.json
2. Commit and push to main
3. Create a GitHub release with tag vX.Y.Z (e.g., v1.3.1)
4. The publish.yml workflow automatically runs tests, builds, and publishes to npm via OIDC trusted publishing

Support

Questions or feedback? Email us at [email protected]

License

MIT