darkhunt-telemetry

Darkhunt telemetry for JS/TS

TypeScript SDK for sending LLM traces, generations, and observations to the Darkhunt platform for persistence and security data enrichment. Built on OpenTelemetry primitives, with built-in client-side data masking that redacts secrets and PII before payloads leave the process.

🤖 Skip the manual wiring — if you use Claude Code, install the Darkhunt plugin once:

/plugin marketplace add darkhunt-security/darkhunt-telemetry-ts
/plugin install darkhunt-telemetry@darkhunt

Then tell Claude "add Darkhunt telemetry to this service" and the darkhunt-telemetry-integration skill auto-invokes and does steps 1–5 below for you.

Get started

Prerequisite — set up your project in Darkhunt. Open the Get started page in the Darkhunt dashboard to copy your tenantId, workspaceId, and applicationId, then create an API key (dh-...) by following Creating an API key. Set them in the environment as DARKHUNT_TENANT_ID, DARKHUNT_WORKSPACE_ID, DARKHUNT_APPLICATION_ID, and DARKHUNT_API_KEY — the SDK reads them automatically.

1. Install

npm install @darkhunt-security/telemetry

Requires Node ^18.19.0 || >=20.6.0 and an ESM project ("type": "module" in package.json). For CommonJS consumers, use dynamic import() or migrate to ESM.

2. Create a singleton module

The SDK holds a global TracerProvider, so instantiate it exactly once per process. Put it in a dedicated module that the rest of your app imports.

// src/telemetry.ts
import { DarkhuntTelemetry } from '@darkhunt-security/telemetry';

// Reads DARKHUNT_API_KEY, DARKHUNT_TENANT_ID, DARKHUNT_WORKSPACE_ID,
// and DARKHUNT_APPLICATION_ID from the environment.
export const dh = new DarkhuntTelemetry();

Pass options explicitly if you need to override any of these (e.g. multi-tenant routing where tenantId varies per request — see Common patterns).

Import dh wherever you need to open a trace. Don't new DarkhuntTelemetry() again — a second provider will silently shadow the first.

3. Wrap your LLM calls

The SDK has two concepts you'll use:

• trace — one user-facing operation (a request, a chat session, a job). Open it at the entry point.
• generation — one LLM call inside a trace. Records model, input, output, token usage, cost.

// src/handlers/chat.ts
import { dh } from '../telemetry.js';

export async function handleChat(req, res) {
  const trace = dh.trace({
    name: 'chat',
    sessionId: req.sessionId,
    userId: req.user.email,
  });

  const gen = trace.generation('answer', {
    model: 'claude-opus-4',
    input: [{ role: 'user', content: req.body.message }],
  });

  try {
    const reply = await yourLlmCall(req.body.message); // your existing client
    gen.end({ output: reply.content, usage: reply.usage });
    res.json({ reply: reply.content });
  } catch (err) {
    gen.end({ level: 'ERROR', statusMessage: String(err) });
    throw err;
  } finally {
    trace.end();
  }
}

The three routing fields — tenantId, workspaceId, applicationId — are how the platform partitions data. They're set once on the client in step 2 and inherited by every trace. If any is missing when dh.trace() is called, it throws — fail-fast is the design.