@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