SDK Health

The SDK Health tab shows whether your VeriProof SDK is connected, healthy, and sending the inputs your policies need.

Health indicators: | Indicator | Healthy threshold | |---|---| | Last heartbeat | Within 5 minutes | | Decision latency p50 | < 50 ms | | Decision latency p95 | < 200 ms | | Coverage ratio | > 80% of requests policy-ready | | Error rate | < 0.1% |

Connection modes: The SDK supports two modes:

Sync — the policy decision happens inline; the application waits for the verdict before proceeding. Lower throughput, stronger guarantees.
Async — policy evaluation runs in the background; the application proceeds immediately. Higher throughput, post-hoc enforcement only.

Troubleshooting a degraded SDK:

Check the Last heartbeat value — a stale heartbeat suggests the SDK process has crashed or cannot reach the VeriProof API.
Check the Error log tab for 4xx/5xx errors from the policy API.
Verify your VERIPROOF_API_KEY environment variable is set correctly.
Review the SDK instrumentation guide for your framework.

SDK Health Monitoring

The VeriProof SDK is designed to be resilient: it exports telemetry data asynchronously, queues failures, and includes a circuit breaker that protects your application when the ingest API is unreachable. In normal operation you should not notice any of this. But in production, you want to know when exports start failing so you can investigate before you have gaps in your compliance record.

This guide explains how to monitor SDK health in production.

Built-in health signals

The SDK emits structured log lines and exposes a metrics interface that your observability stack can consume.

SDK debug logging

Enable verbose debug logging to see export success and failure events. The SDK uses standard platform logging, so you can route output through your existing logging stack:

Python


import logging
 
# Route veriproof_sdk log lines to your logging stack
logging.getLogger("veriproof_sdk").setLevel(logging.DEBUG)
 
# Or set the OTel log level environment variable before starting your app:
# OTEL_LOG_LEVEL=debug

TypeScript


// Set the OTel log level environment variable before starting your app:
// OTEL_LOG_LEVEL=debug
//
// Or, in code, configure the DiagAPI before constructing your client:
import { diag, DiagConsoleLogger, DiagLogLevel } from '@opentelemetry/api';
diag.setLogger(new DiagConsoleLogger(), DiagLogLevel.DEBUG);

.NET


// Add Microsoft.Extensions.Logging at Debug level for the Veriproof exporter
builder.Logging.AddFilter("Veriproof", LogLevel.Debug);
 
// Then wire up the exporter as normal:
builder.Services.AddOpenTelemetry()
    .WithTraces(traces => traces
        .AddSource("*")
        .AddVeriproofTracing(options =>
        {
            options.ApiKey = Environment.GetEnvironmentVariable("VERIPROOF_API_KEY")!;
        })
    );

With debug logging enabled, look for these log patterns:

Log pattern	Meaning
`[veriproof] export success`	Session batch exported successfully
`[veriproof] export failed attempt=N`	Export failed; will retry (N = attempt number)
`[veriproof] circuit breaker OPEN`	Consecutive failures exceeded threshold; exports suspended
`[veriproof] circuit breaker HALF_OPEN`	Recovery probe in progress
`[veriproof] circuit breaker CLOSED`	Exports resumed after successful probe
`[veriproof] queue depth=N`	Pending span queue size (N spans waiting to export)

Do not leave debug=True enabled in production indefinitely. Debug logging is verbose and may log session metadata. Use it temporarily for investigation, then disable it.

Circuit breaker behavior

The SDK uses a circuit breaker to prevent export retries from impacting application performance when the ingest API is unavailable:

State	Behavior
Closed (normal)	Exports proceed; failures trigger retries
Open (failing)	Exports are dropped; no retries attempted; queue drains
Half-open (recovering)	One probe export sent; if it succeeds, circuit closes

The circuit opens after 5 consecutive export failures. It attempts to close after 60 seconds.

Sessions exported while the circuit is open are lost — they are not queued for later delivery. If your application requires zero-gap compliance records, monitor for circuit breaker events and alert on them immediately.

Common production issues

Symptom	Likely cause	Resolution
Circuit breaker opens at startup	API key incorrect or ingest API URL misconfigured	Verify `VERIPROOF_API_KEY` and `ingest_endpoint` setting
Intermittent export failures	Network instability between application and ingest API	Check connection to `ingest.veriproof.app` on port 443; verify no egress filtering
Persistent queue growth	Ingest API returning 429 (rate limited)	Review your plan’s rate limits; consider batching more aggressively
Circuit keeps opening after recovery	Application handling requests faster than the circuit can probe	Consider reducing `max_concurrent_exports` in SDK options

Next steps

SDK Troubleshooting — diagnose missing traces and authentication errors
Alert Rules — configure portal alerts triggered by SDK health events
Python SDK Core Reference — full SDK configuration reference