Node.js SDK

Astralog’s Node.js SDK is designed to work in high-throughput environments like Express, Next.js, and Serverless. It automatically batches events and performs background flushing to prevent Event Loop blocking.

Installation

npm install astralog-node

Initialization

Initialize the client once globally.

// index.ts
import { Client } from "astralog-node";

const client = new Client({ apiKey: "ast_sk_live_xxxxxxxxxxxxx" });

// Optionally wait for background events to finish before shutting down
// await client.close();

Logging API Reference

All logging methods accept a message string and an optional Record<string, any> for structured metadata.

1. client.info()

Use for general system events, successful actions, or checkpoints.

client.info("User registered", {
  user_id: "usr_99283",
  plan: "premium"
});

2. client.warn()

Use for non-fatal issues, retries, or rate limits approaching.

client.warn("Rate limit approaching", {
  tenant_id: "org_123",
  remaining_quota: 5
});

3. client.error()

Use for exceptions, fatal crashes, or 5xx HTTP responses.

try {
  await db.connect();
} catch (err) {
  client.error("Database connection failed", {
    db_host: "10.0.0.5",
    error_msg: err.message
  });
}

4. client.debug()

Use for verbose information that helps during active development or deep troubleshooting.

client.debug("Cache miss, querying DB", {
  cache_key: "user_profile_99283",
  latency_ms: 12.4
});

5. client.event()

The underlying raw method. Allows you to specify custom event levels dynamically.

client.event("critical", "System overheating", {
  temperature: 95
});

Distributed Tracing

Astralog automatically promotes the trace_id property. If you include it in your metadata, ClickHouse will index it for instantaneous multi-service correlation.

client.info("Processing payment", {
  trace_id: "req-8f72-11a9",
  amount: 49.99
});