Runtime Logs

Runtime logs are diagnostic signals emitted by Pavri SDK plugins running inside your agent processes. They are not backend service logs — they capture what the SDK and its framework plugins observe at runtime, such as policy evaluations, hook executions, enforcement decisions, and plugin lifecycle events.

How Log Forwarding Works

The forwarding pipeline moves logs from the plugin to the Pavri backend without blocking agent execution:

plugin logger -> SDK buffer -> batched/compressed envelope -> gateway -> ingest -> ClickHouse

1. Plugin emits a log record — each framework plugin writes structured log records during hook execution, enforcement, and lifecycle events.
2. SDK buffers locally — records accumulate in a bounded in-memory ring buffer inside the SDK process.
3. Batched envelope — the SDK periodically drains the buffer into a compressed batch envelope and sends it to the Pavri gateway.
4. Ingest and storage — the gateway forwards the envelope through the ingest pipeline to a dedicated runtime-log subject, which is consumed and written to ClickHouse.

Runtime log forwarding is asynchronous and never blocks agent execution. If the buffer is full, the SDK evicts the lowest-severity records first and counts the drops.

Backend-Controlled Policy

The Pavri backend controls what gets forwarded through a RuntimeLogPolicy delivered via the same policy/bootstrap channel used for other runtime configuration. This means the backend can remotely tune log verbosity without redeploying the agent.

Policy knobs include:

Knob	Description
Minimum forwarded level	Only records at or above this severity are forwarded
Per-plugin overrides	Different levels for different framework plugins
Sampling rate	Fraction of debug/trace records to forward
Max records per minute	Rate limit on forwarded records
Max bytes per minute	Byte-rate limit on forwarded payload
Max batch size	Maximum records per batch envelope
Flush interval	How often the SDK drains the buffer
Redaction mode	Whether to strip sensitive fields before forwarding
Retention tier	How long the backend stores forwarded logs
Policy TTL	When the forwarding policy expires and reverts to defaults

SDK-Local Defaults

The SDK ships with conservative defaults that keep forwarding low-noise:

Setting	Default	Description
Forwarding enabled	true	Log forwarding is on by default
Default minimum level	warn	Only warn and error are forwarded by default
Max buffer size	256	Maximum records held in the local ring buffer
Compression	enabled	Batch envelopes are compressed before sending
info forwarding	off	Must be explicitly enabled
debug forwarding	off	Must be explicitly enabled
trace forwarding	off	Must be explicitly enabled

These defaults mean a typical agent forwards only warnings and errors — a small, high-signal stream.

Tuning Noise

Adjusting the minimum level

To see more detail during an investigation, the backend can push a policy update that lowers the minimum level:

• Set default_min_level to info to include informational records.
• Set default_min_level to debug for deep plugin debugging.
• Set default_min_level to trace for maximum detail (use sparingly).

Prefer time-bounded overrides: lower the level for a specific agent or session, investigate, then revert.

Adjusting buffer size

The max_buffer_size controls how many records the SDK holds before the oldest low-severity records are evicted. Increase it if you are losing records during burst activity. Decrease it if the agent is memory-constrained.

Drop-on-overflow behavior

When the buffer is full, the SDK uses a lowest-severity-first eviction strategy:

1. If a new record arrives and the buffer is at capacity, the SDK drops the record with the lowest severity.
2. If the new record is lower severity than everything in the buffer, the new record is dropped.
3. Drop counts are tracked and reported in the next batch envelope.

This ensures error and warn records survive even when the agent generates a burst of debug or trace output.

Viewing Logs in the Dashboard

Runtime logs for a session are visible at:

/sessions/[sessionId]/logs

The log viewer shows timestamped records with severity, plugin source, message, and any structured fields. You can filter by severity level and search by message content.

Retention

Runtime logs have a 14-day default retention period. This is shorter than core product telemetry (30-90 days) because runtime logs are a diagnostic signal, not a forensic record. The backend policy can override the retention tier per org or agent.

Best Practices

• Keep defaults low-noise. The warn/error default is intentionally conservative. Most agents should not need info-level log forwarding in steady state.
• Use backend policy for debug/trace. When investigating an issue, push a policy update to lower the level for the specific agent or session. Revert when done.
• Monitor drop counts. If the batch envelope consistently reports dropped records, consider increasing the buffer size or raising the minimum level to reduce volume.
• Do not forward trace-level logs cluster-wide. Scope trace to individual agents or sessions to avoid overwhelming the ingest pipeline.

What's Deferred

• TypeScript SDK log forwarding parity (Phase 2).
• Ingest-side redaction (logs are currently redacted at the SDK level only).
• Advanced log analytics and aggregation beyond the per-session log viewer.