@rankigi/otel

OpenTelemetry SpanProcessor that adds cryptographic receipts to your AI agent spans.

The processor runs alongside your existing OTel exporters — it does not replace them. Keep Datadog, Honeycomb, Jaeger, or whatever you have. RANKIGI just adds a tamper-evident proof layer for the spans that matter for governance.

Install

npm install @rankigi/otel @rankigi/sdk

Setup

First, enroll a connector passport in your RANKIGI dashboard (Agents → New, type "connector"). Copy the credentials into your environment:

RANKIGI_API_KEY=rnk_...
RANKIGI_AGENT_ID=<uuid>
RANKIGI_PASSPORT_ID=<uuid>
RANKIGI_SIGNING_KEY=<base64 ed25519 seed>

Then add the processor to your existing OTel pipeline:

import { createRankigiProcessor } from "@rankigi/otel";
import { NodeSDK } from "@opentelemetry/sdk-node";

const sdk = new NodeSDK({
  spanProcessors: [
    createRankigiProcessor(),
    // your existing exporters stay here -- Datadog, Honeycomb, etc.
  ],
});
sdk.start();

That's it. Every AI span now gets a cryptographic receipt.

If you'd rather construct the client explicitly (e.g. you're sharing one Rankigi instance across multiple subsystems), pass client:

import { Rankigi } from "@rankigi/sdk";
import { createRankigiProcessor } from "@rankigi/otel";

const rankigi = Rankigi.fromEnv();
const processor = createRankigiProcessor({ client: rankigi });

What gets hashed (never leaves your process in raw form)

These OpenTelemetry GenAI attributes are SHA-256-hashed locally before any network call:

• gen_ai.input.messages (prompts)
• gen_ai.output.messages (completions)
• gen_ai.system_instructions
• gen_ai.tool.call.arguments
• gen_ai.tool.call.result
• gen_ai.tool.definitions
• llm.input_messages, llm.output_messages
• llm.prompts, llm.completions

What gets sent to RANKIGI

• Span name, duration, status
• Trace ID, span ID, parent span ID (for chain linking and incident replay)
• Model name (gen_ai.request.model), token counts (gen_ai.usage.*)
• All other non-sensitive span attributes
• SHA-256 hashes of the sensitive fields above

Filtering

Only spans whose names start with gen_ai., llm., langchain., openai., anthropic., tool., or agent. are processed. Everything else is silently ignored so your HTTP and database spans don't end up on the audit chain.

Override with spanNamePrefixes:

createRankigiProcessor({
  spanNamePrefixes: ["gen_ai.", "my.custom.prefix."],
});

Backpressure

• In-memory queue cap: maxQueueSize (default 2048). When exceeded, new spans are dropped silently. Set logDropped: true to surface drops.
• Auto-flush cadence: flushTimeoutMs (default 5000ms).
• await processor.forceFlush() drains immediately.
• await processor.shutdown() flushes and stops accepting new spans.

The processor will never throw into the OTel pipeline. If RANKIGI is unreachable the events are absorbed and dropped on the floor — the AI agent keeps running normally.

Verify receipts offline

python3 verify.py --receipt receipt.json --rekor

License

MIT