Integration · OpenTelemetry · Live

Sgraal verdicts as spans in your APM.

You already have an observability stack. Sgraal exports its memory-governance decisions in Zipkin and Jaeger formats, so a memory BLOCK shows up next to your latency and error spans — on the pane of glass your team already watches. No new console to learn; governance is just another span.

The endpoints

Two export endpoints return your recent preflight decisions as spans, each tagged with the omega risk score and the four-band decision:

# Zipkin v2 span format
curl -sS https://api.sgraal.com/v1/traces/export/zipkin \
  -H "Authorization: Bearer $SGRAAL_API_KEY"

# Jaeger format
curl -sS https://api.sgraal.com/v1/traces/export/jaeger \
  -H "Authorization: Bearer $SGRAAL_API_KEY"

A Zipkin response is a list of spans, each a sgraal.preflight operation with omega and decision tags:

{
  "format": "zipkin",
  "spans": [
    {
      "traceId": "6f3c1a...e1ab",
      "id": "9b8d77c2",
      "name": "sgraal.preflight",
      "localEndpoint": { "serviceName": "sgraal-api" },
      "tags": { "omega": "18", "decision": "USE_MEMORY" }
    }
  ]
}

These are export endpoints: you pull the recent spans and forward them into your collector or your provider's trace intake. The pattern below is a small scheduled forwarder — the same shape for any backend that ingests Zipkin or Jaeger.

Datadog

Datadog's Agent accepts Zipkin spans on its trace intake port. Run a small forwarder (cron, Lambda, or a sidecar) that pulls the Sgraal export and posts it to the Agent:

# Pull Sgraal spans → forward to the Datadog Agent (Zipkin intake)
curl -sS https://api.sgraal.com/v1/traces/export/zipkin \
  -H "Authorization: Bearer $SGRAAL_API_KEY" \
| curl -sS -X POST "http://localhost:8126/v0.4/traces" \
  -H "Content-Type: application/json" --data-binary @-

In Datadog: the spans appear under service sgraal-api, operation sgraal.preflight. Facet on the decision tag to build a monitor that pages when decision:BLOCK appears, or a top-list of agents by omega.

Grafana Tempo

Tempo ingests via the OpenTelemetry Collector. Add a pipeline that reads the Sgraal Jaeger export and exports to Tempo's OTLP endpoint:

# otel-collector-config.yaml (sketch)
receivers:
  jaeger:
    protocols: { thrift_http: { endpoint: 0.0.0.0:14268 } }
exporters:
  otlp/tempo:
    endpoint: tempo:4317
service:
  pipelines:
    traces:
      receivers: [jaeger]
      exporters: [otlp/tempo]

In Grafana: query Tempo for service.name = "sgraal-api", then drive a panel off the decision and omega span tags. Pairs naturally with the Insights fields if you also scrape those.

Honeycomb

Honeycomb ingests OTLP. Point the same OpenTelemetry Collector pipeline at Honeycomb's endpoint with your API key:

exporters:
  otlp/honeycomb:
    endpoint: api.honeycomb.io:443
    headers: { "x-honeycomb-team": "${HONEYCOMB_API_KEY}" }
service:
  pipelines:
    traces:
      receivers: [jaeger]
      exporters: [otlp/honeycomb]

In Honeycomb: the sgraal.preflight spans become queryable events — BREAKDOWN by decision, or HEATMAP the omega tag to see risk distribution over time.

Why it lands well

Memory governance and observability are complementary, not competing: observability tells you what happened after an agent acted; Sgraal's verdict tells you whether the memory was safe to act on beforehand. Exporting the verdict as a span puts both on the same timeline — a BLOCK span sitting right before the latency spike it prevented.

What this does not do

Live OTLP push

These are pull-based export endpoints returning recent spans in Zipkin / Jaeger format. A real-time OTLP push transport is not part of this endpoint — the forwarder pattern above is the supported integration. For near-real-time, run the forwarder on a short interval.

Sampling / retention config

The export returns recent decisions; long-term retention and sampling are governed by your APM, not Sgraal. Configure them in the collector or provider as you would for any trace source.

Versioning

Last reviewed: 2026-05-24. Status: Live · doc-only (export endpoints in production).

Related: /docs/insights · /compatibility · /docs/api