Observability

Engram provides state and event surfaces you can wire into your own logs, metrics, and alerting.

Runtime State You Can Poll

From EngramSDK:

• runningSpendUSDFC
• maxSpendUSDFC
• activeCids
• storageProviderName
• network
• isAttestOnChain

Typical polling loop:

setInterval(() => {
  console.log({
    spend: sdk.runningSpendUSDFC,
    cap: sdk.maxSpendUSDFC,
    activeCidCount: sdk.activeCids.length,
    provider: sdk.storageProviderName
  })
}, 30_000)

Structured Operation Logs

SDK operations emit logs through the internal logger path (logPath).

Recommended log shipping fields:

• event_type
• cid
• outcome
• spend_usdfc
• running_total_usdfc
• erc8004_attestation_tx (when present)
• error (on failure)

Typical entry shape:

{
  "timestamp": "2026-03-20T06:05:11.000Z",
  "event_type": "STORE",
  "input": { "dataSize": 2048, "priority": "standard" },
  "decision": { "replication": 3, "ttlDays": 90, "encrypt": false },
  "tool_calls": ["synapse.deal"],
  "retries": 0,
  "outcome": "SUCCESS",
  "cid": "bafy...",
  "spend_usdfc": 0.0718,
  "running_total_usdfc": 0.3681
}

Common event_type values include:

• STORE, RETRIEVE, RENEW, PRUNE
• BUDGET_EXCEEDED
• BALANCE_LOW, BALANCE_TOPPED_UP, FUNDING_ROUTE
• ENCRYPT, DECRYPT
• IDENTITY_REGISTERED, ATTESTATION_WRITTEN
• RESTORE, DELEGATE_ISSUED, DELEGATION_VERIFIED

MCP Health and Tool Surface

MCP server exposes:

• /health endpoint
• tool list in health response
• operational errors through MCP tool responses

Health probe:

curl http://localhost:3456/health

Suggested Metrics

Track at minimum:

• store success rate
• retrieve latency p95
• renew success rate
• prune volume
• delegation verification failure rate
• spend-to-cap ratio (runningSpendUSDFC / maxSpendUSDFC)

Alerts

Set warning and critical thresholds:

• spend ratio > 0.80 (warning), > 0.95 (critical)
• renew failure burst over 5 minutes
• retrieval failure spikes
• MCP health failing for > 1 minute

Correlation IDs

Attach your own request/correlation id to application logs before each SDK call so cross-system traces stay joinable during incidents.