@scopeblind/otel-exporter

ScopeBlind receipts in your existing observability stack.

An OpenTelemetry exporter that translates Veritas Acta receipt DAGs into OTel traces and spans. Every receipt shows up as a span. Click the deep link to see the full causal DAG in ScopeBlind Trace.

Install

npm install @scopeblind/otel-exporter

Quick Start

Three lines to add ScopeBlind receipts to an existing OTel pipeline:

import { createActaTraceProvider, recordReceiptSpan } from "@scopeblind/otel-exporter";
import { OTLPTraceExporter } from "@opentelemetry/exporter-trace-otlp-http";

// 1. Create a provider that forwards to your existing exporter
const provider = createActaTraceProvider({
  exporters: [new OTLPTraceExporter()],
});

// 2. Get a tracer
const tracer = provider.getTracer("my-agent-service");

// 3. Record receipts as spans
recordReceiptSpan(tracer, receipt);

What You Get

Each Acta receipt becomes an OTel span with:

Attribute	Value
`acta.receipt_id`	Receipt ID
`acta.tool_name`	Tool that was called
`acta.decision`	`allow` or `deny`
`acta.agent_id`	Agent that requested the action
`acta.policy_hash`	Hash of the policy that applied
`acta.issuer_id`	Entity that issued the receipt
`acta.trace_url`	Deep link to ScopeBlind Trace viewer

Span name: acta:{receiptType} (e.g., acta:decision)
Status: OK for allow, ERROR for deny
Span links: parent_receipts become span links with acta.relation

Setup with Datadog

import { createActaTraceProvider } from "@scopeblind/otel-exporter";
import { OTLPTraceExporter } from "@opentelemetry/exporter-trace-otlp-http";

const provider = createActaTraceProvider({
  exporters: [
    new OTLPTraceExporter({
      url: "https://trace.agent.datadoghq.com/api/v0.2/traces",
    }),
  ],
});

Setup with Grafana Tempo

const provider = createActaTraceProvider({
  exporters: [
    new OTLPTraceExporter({
      url: "http://localhost:4318/v1/traces",
    }),
  ],
});

Setup with Honeycomb

const provider = createActaTraceProvider({
  exporters: [
    new OTLPTraceExporter({
      url: "https://api.honeycomb.io/v1/traces",
      headers: { "x-honeycomb-team": process.env.HONEYCOMB_API_KEY },
    }),
  ],
});

Manual Span Conversion

If you need finer control, use actaReceiptToSpan to get the raw attributes:

import { actaReceiptToSpan } from "@scopeblind/otel-exporter";

const { name, attributes, status, links } = actaReceiptToSpan(receipt);
// Attach to your own span however you like

Deep Links

Every span includes an acta.trace_url attribute that links back to the ScopeBlind Trace viewer. In Datadog, Grafana, or Honeycomb, this appears as a clickable link on the span detail panel.

import { generateTraceDeepLink } from "@scopeblind/otel-exporter/deeplink";

const url = generateTraceDeepLink("receipt_abc123");
// => "https://scopeblind.com/trace#receipt=receipt_abc123"

License

MIT