@clawcowork/obs

Easy-install observability for any Node app — drop into your project, get logs, errors, metrics, and HTTP spans flowing into your ClawCowork project's Obs panel.

Install

npm install @clawcowork/obs

Setup (1 line)

require("@clawcowork/obs").init({
  token: process.env.CLAWCOWORK_OBS_TOKEN,
});

That's it. Drop this at the top of your index.js / server.ts / wherever your app starts. From now on, every console.log, every uncaught exception, every unhandled rejection — captured + shipped to your project.

Where do I get the token?

1. Open the project in ClawCowork.
2. Go to the Obs tab.
3. Click Generate ingest token and copy the obs_... value (shown once).
4. Set it as the CLAWCOWORK_OBS_TOKEN env var on the target machine.

Each project has its own tokens. Generate one per environment (production, staging, ci-runner, etc.) so you can revoke independently.

What gets captured

| Source | How | |---------------------------|----------------------------------| | console.log/info | level=info, message=arg join | | console.warn | level=warn | | console.error | level=error | | console.debug | level=debug | | uncaughtException | errors[], kind=uncaughtException | | unhandledRejection | errors[], kind=unhandledRejection | | obs.error(err) | errors[], kind=manual | | obs.log(level, msg, f) | logs[] directly (no console) | | obs.metric(name, value) | metrics[] | | obs.middleware() HTTP | spans[] per request, plus 5xx → errors[] |

Express / Next custom server

const express = require("express");
const obs = require("@clawcowork/obs");
obs.init({ token: process.env.CLAWCOWORK_OBS_TOKEN });

const app = express();
app.use(obs.middleware()); // captures method, url, status, durationMs
app.get("/", (req, res) => res.send("ok"));
app.listen(3000);

Manual API

const obs = require("@clawcowork/obs");

// Custom log line (doesn't show in console).
obs.log("info", "checkout completed", { orderId: "abc", amount: 4900 });

// Custom metric.
obs.metric("checkout.duration_ms", 247, { plan: "pro" });

// Capture an error you handled yourself (won't fire process listeners).
try {
  doRiskyThing();
} catch (err) {
  obs.error(err, { kind: "checkout-flow" });
}

// Stamp every subsequent event with extra context.
obs.setContext({ region: "us-east", build: process.env.GIT_SHA });

// Force flush before shutdown (also fires automatically on SIGINT/SIGTERM).
await obs.flush();

Configuration

obs.init({
  token: "obs_...",                      // required
  endpoint: "https://dev.honeypixel.com.br",// default
  service: "checkout-api",               // default = os.hostname()
  environment: "production",             // default = NODE_ENV
  context: { region: "us-east", podId },
  flushIntervalMs: 5000,                 // default 5s
  flushBatch: 100,                       // default 100 events
  captureConsole: true,                  // default true
  captureErrors: true,                   // default true
});

Or via env vars (set + call init() with no args):

| Env var | Effect | |----------------------------------|------------------------------| | CLAWCOWORK_OBS_TOKEN | sets token | | CLAWCOWORK_OBS_ENDPOINT | overrides endpoint | | CLAWCOWORK_OBS_SERVICE | sets service |

How it works

1. Events are buffered in memory.
2. When the buffer hits 100 events OR every 5 seconds, the SDK POSTs the batch to <endpoint>/api/obs/ingest with Authorization: Bearer <token>.
3. The control plane resolves the token to a project, persists the events, and renders them in the project's Obs panel.

Network failures retry by re-queueing the failed batch (capped at 5k events to avoid OOM in long outages). The SDK never throws into your app.

Privacy

The SDK never reads anything from disk or the network — it only buffers what your code emits via console.* or the manual API. The HTTP middleware only records method, URL, status, and duration — not request bodies.

License

MIT