@cedtech/logger

Official logger SDK for CedtechLog — structured logs and analytics events with automatic batching, works in Node.js, Bun, and the browser.

Installation

npm install @cedtech/logger
# or
bun add @cedtech/logger

Quick start

Create a project in your CedtechLog dashboard, generate an API key (ctl_…), then initialise the logger:

import { CedtechLogger } from "@cedtech/logger";

const logger = new CedtechLogger({
  endpoint: "https://your-cedtechlog-server.com",
  apiKey: "ctl_…",
});

logger.info("Server started", { port: 3000 });
logger.warn("High memory usage", { mb: 512 });
logger.error("Unhandled exception", { stack: err.stack }, requestId);

// Track analytics events
logger.event("user_signup", { plan: "pro" }, { user_id: "u_123" });

// Flush before process exit
process.on("beforeExit", () => logger.destroy());

The project name is resolved automatically from the API key — no need to specify service.

Log levels

| Method | Level | | -------------- | ------- | | logger.trace | trace | | logger.debug | debug | | logger.info | info | | logger.warn | warn | | logger.error | error | | logger.fatal | fatal |

All log methods share the same signature:

logger.info(message: string, fields?: Record<string, unknown>, traceId?: string)

Event tracking

logger.event(
  name: string,
  properties?: Record<string, unknown>,
  opts?: { user_id?: string; session_id?: string; timestamp?: string },
)

logger.event("page_view", { path: "/dashboard" }, { session_id: "s_abc" });
logger.event("purchase", { amount: 49.99, currency: "USD" }, { user_id: "u_123" });

Configuration

const logger = new CedtechLogger({
  // Required (unless `transport` is provided)
  endpoint: "https://…",
  apiKey: "ctl_…",

  // Optional
  service: "my-service",       // Override project name (resolved from key by default)
  flushInterval: 5_000,        // Auto-flush interval in ms (default: 5 000)
  batchSize: 100,              // Flush when buffer reaches this count (default: 100)
  defaultFields: {             // Merged into every log and event entry
    env: "production",
    region: "us-east-1",
  },
  captureMetadata: true,       // Auto-attach pid, platform, arch, runtime (default: true)
  captureSource: true,         // Auto-capture caller file/line as `source` (default: true)
});

Child loggers

Inherit all settings and merge extra persistent fields without re-initialising:

const requestLogger = logger.child({ requestId: "req_xyz", userId: "u_123" });

requestLogger.info("Request received", { method: "POST", path: "/checkout" });
requestLogger.error("Payment failed", { reason: "insufficient_funds" });

Custom transport

Swap the HTTP transport for a custom implementation — useful for testing or alternative backends:

import { CedtechLogger, type Transport } from "@cedtech/logger";

class ConsoleTransport implements Transport {
  async sendLogs(batch) {
    for (const log of batch) console.log(`[${log.level}] ${log.message}`);
  }
  async sendEvents(batch) {
    for (const evt of batch) console.log(`[event] ${evt.name}`);
  }
}

const logger = new CedtechLogger({ transport: new ConsoleTransport() });

Lifecycle

Logs are buffered and flushed automatically on an interval or when the batch size is reached. Call destroy() before your process exits to flush remaining entries:

// Node / Bun
process.on("beforeExit", () => logger.destroy());

// Alternatively, flush manually at any time
await logger.flush();

License

MIT