@duckledger/usage

Server-side usage metering SDK for DuckLedger. It batches events, retries transient errors and flushes pending events during graceful shutdown.

Registry status: published on npm.

import { DuckLedgerUsage } from '@duckledger/usage';

const usage = new DuckLedgerUsage({
  apiKey: process.env.DUCKLEDGER_USAGE_KEY,
});

await usage.withTrace(
  { id: conversation.id, kind: 'conversation', subject: user.id, tags: { plan: 'pro' } },
  async (trace) => {
    trace.step('retrieveContext');
    usage.track({
      type: 'ai.tokens_spent',
      data: { model: 'gpt-4o', prompt_tokens: 1200, completion_tokens: 400 },
    });
  },
);

await usage.close();

A conversation that lasts several requests should pass the same id with end: false (or continueTrace) and call endTrace({ id, subject }) when it finishes. See docs/USAGE_METERING.md.

Create an ingest key on Usage in DuckLedger. Use one long-lived client per backend process and call close() from the process shutdown hook. Never expose ingest keys in browser or mobile code.