@attestry/otel-agent-compliance

OpenTelemetry SpanProcessor that emits Attestry ABDR (Agent-Based Decision Record) entries for every AI tool call, LLM completion, retrieval, or policy evaluation that flows through your tracer. Every recorded decision becomes part of a hash-chained, cryptographically-verifiable compliance ledger you can replay against EU AI Act, NIST AI RMF, and ISO 42001 audits.

Install

npm install @attestry/otel-agent-compliance @opentelemetry/sdk-node

@opentelemetry/sdk-node is a peer dependency. Install it alongside if you don't have it already.

Quick start

import { NodeSDK } from "@opentelemetry/sdk-node";
import { AttestryDecisionExporter } from "@attestry/otel-agent-compliance";

const sdk = new NodeSDK({
  spanProcessors: [
    new AttestryDecisionExporter({
      apiUrl: "https://attestry.app/api/v1/decisions/bulk",
      apiKey: process.env.ATTESTRY_API_KEY!,
      systemId: process.env.ATTESTRY_SYSTEM_ID!,
    }),
  ],
});

sdk.start();

process.on("SIGTERM", async () => {
  await sdk.shutdown(); // flushes the in-memory queue
});

What gets recorded

By default, the exporter records a span as a decision when ANY of the following is true:

| Signal | Source | |---|---| | ai.operation attribute set | OpenInference / OpenTelemetry semantic conventions | | gen_ai.operation.name attribute set | OTel GenAI semantic conventions | | tool.name attribute set | LangChain / LlamaIndex tool spans | | policy.outcome or decision.outcome attribute set | Customer policy engines | | Span name contains tool, llm, completion, or policy | Heuristic on framework span names |

Spans that don't match are dropped without making a network call. Override with shouldRecordAsDecision.

What lands on the wire

Each decision posted to /api/v1/decisions/bulk contains:

• systemId — the Attestry system this exporter is attached to
• inputDigest — sha256: of the canonical-form span input (sorted keys)
• outputDigest — sha256: of the canonical-form span output, when present
• frameworkClaims[] — heuristic mappings to EU AI Act / NIST AI RMF / ISO 42001 articles
• toolInvocations[] — tool.name if set
• policyOutcome — permitted / denied / escalated if recognized
• idempotencyKey — the OTel span ID (replay-safe)

The exporter never sends raw span input or output text. Only digests cross the wire by default. Tools, prompts, and completions stay inside your process.

PII sanitizer

The default sanitizer redacts emails, phone numbers, US SSNs, credit card numbers, and IPv4 addresses inside any string-valued span attribute. Override with config.sanitizer to plug in HIPAA / GDPR special-category rules:

new AttestryDecisionExporter({
  // ...
  sanitizer: (attrs) => {
    const out = { ...attrs };
    delete out["http.request.body"]; // never ship request bodies
    return out;
  },
});

Framework tagger

Heuristic mapping from span context to frameworkClaims[]. Customers with curated taxonomies override it:

new AttestryDecisionExporter({
  // ...
  frameworkTagger: ({ name, attributes }) => {
    if (attributes["custom.tag"] === "loan-decision") {
      return [
        {
          framework: "EU AI Act",
          article: "Annex III §5(b)",
          claim: "Creditworthiness evaluation for natural persons.",
        },
      ];
    }
    return [];
  },
});

Configuration reference

| Option | Default | Description | |---|---|---| | apiUrl | (required) | Full URL of the bulk ingest endpoint | | apiKey | (required) | API key with write:assessments permission | | systemId | (required) | Attestry system UUID | | batchSize | 20 | Flush trigger — records per batch | | batchInterval | 5000ms | Flush trigger — max delay before partial flush | | fetchTimeoutMs | 10_000 | Per-request abort timeout | | sanitizer | regex stripper | Override PII sanitization | | frameworkTagger | heuristic mapping | Override claim generation | | shouldRecordAsDecision | heuristic | Override decision detection | | logger | console (stderr) | Wire pino/winston/etc. via warn/error |

Failure mode

The exporter never throws to your application. Network errors, 5xx responses, and timeouts go through three retries with capped exponential backoff (250ms → 750ms → 2_250ms + jitter), then log via the configured logger and drop the batch. 4xx responses (other than 429) are treated as permanent — no retry, log + drop.

Integration examples

LangChain

LangChain emits OTel spans automatically when LANGCHAIN_TRACING_V2=true and an OTel SDK is initialized in the process. Wire the exporter and every chain step shows up in Attestry.

LlamaIndex

LlamaIndex's OpenInference instrumentation tags spans with openinference.span.kind. The default decider catches them via the ai.operation / gen_ai.operation.name keys.

OpenAI / Anthropic SDK

Wrap the SDK call in a manual span and set ai.operation to "completion":

import { trace } from "@opentelemetry/api";

const tracer = trace.getTracer("my-app");
await tracer.startActiveSpan("openai.completion", async (span) => {
  span.setAttribute("ai.operation", "completion");
  span.setAttribute("input", prompt);
  const result = await openai.chat.completions.create({ ... });
  span.setAttribute("output", result.choices[0].message.content);
  span.end();
});

License

Apache-2.0