radar-client

Client SDK for pushing logs and metrics to a Radar server over its access-key-authenticated ingestion socket (/socket/api/v1).

Install

npm install @ali39/radar-client

Usage

import { RadarClient } from "radar-client";

const radar = new RadarClient({
    url: "https://radar.example.com",
    accessKey: "<plaintext access key>",
});

radar.info("server started", { pid: process.pid });
radar.error("payment failed", { orderId: "abc123" });

radar.metric("cpu.usage", 42.5, { host: "web-1" });
radar.metric("requests.count", 1);

radar.on("error", (err) => console.error("radar error:", err));

// on shutdown
await radar.close();

Behavior

• Entries are queued in memory and flushed in batches (default every 2s, up to 500 entries per push - matching the server's own cap).
• Reconnection is handled by socket.io itself, retried forever by default with exponential backoff (tunable via reconnectionDelay, reconnectionDelayMax, reconnectionAttempts). On every successful (re)connect, whatever piled up while offline is drained automatically.
• Nothing is lost on disconnect. Entries keep queuing while offline (bounded by maxQueueSize per queue; beyond that the oldest entries are dropped and a "drop" event fires). If a batch is in flight when the socket drops, or the server never acknowledges it within ackTimeout, it is put back on the front of the queue and retried later - it is not lost.
• Only a batch the server explicitly rejects (e.g. malformed entries) is dropped rather than retried, since retrying identical bad data would fail forever. An "error" event fires either way so you can observe it.
• close() flushes any remaining queued entries (best-effort, bounded by a timeout) before disconnecting.

Options

| Option | Default | Description | | ------------------------ | -------------------- | ----------------------------------------------------- | | url | required | Radar server base URL | | accessKey | required | Plaintext access key | | path | /socket/api/v1 | Ingestion socket.io path | | flushInterval | 2000 | Flush interval in ms | | maxBatchSize | 500 | Max entries per push (capped at 500) | | maxQueueSize | 10000 | Max entries held per queue while disconnected | | minLevel | debug | Discard logs below this level before queuing | | autoConnect | true | Connect immediately on construction | | reconnection | true | Auto-reconnect on disconnect | | reconnectionDelay | 1000 | Delay before the first reconnection attempt (ms) | | reconnectionDelayMax | 5000 | Upper bound for reconnection backoff (ms) | | reconnectionAttempts | Infinity | Max reconnection attempts before giving up | | ackTimeout | 10000 | How long to wait for a push ack before requeuing (ms) | | rejectUnauthorized | true | Set false to accept self-signed TLS certificates |

Events

• "connect" - socket connected (fires again after every reconnect)
• "disconnect" (reason) - socket disconnected
• "reconnect_attempt" (attempt) - a reconnection attempt is starting
• "reconnect_failed" - reconnectionAttempts was exhausted; giving up
• "error" (Error) - connection error, an ack timeout/disconnect mid-push, or a rejected push batch
• "flush" ({ kind, inserted }) - a batch was accepted by the server
• "drop" (count) - entries dropped because the queue was full