npm package: @scopeblind/otel-exporter
Description: OpenTelemetry exporter that translates Veritas Acta receipt DAGs into OTel traces/spans
Latest version: 0.1.2

# @scopeblind/otel-exporter

**ScopeBlind receipts in your existing observability stack.**

An OpenTelemetry exporter that translates [Veritas Acta](https://veritasacta.com) 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

```bash
npm install @scopeblind/otel-exporter
```

## Quick Start

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

```ts
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

```ts
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

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

## Setup with Honeycomb

```ts
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:

```ts
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.

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

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

## License

MIT