Logging for LLM Agents

Why this logging format works for agents

Most agent debugging fails because the model gets a huge raw log dump and loses the thread. Raysurfer logging is designed for the opposite pattern:

Start with a compact summary for one exact line hash
Expand only when needed by curling related hashes
Keep context small while preserving deterministic drill-down paths

1) Instrument the exact line

Use a stable hash for each instrumentation point so the agent can request that exact log stream later.

result = run_refill_check(payload)
raysurfer.log(result, "4b1f7f31a2c9d8e6")

const result = await runRefillCheck(payload);
raysurfer.log(result, "4b1f7f31a2c9d8e6");

Hash generation policy (and collisions)

LLMs should not invent random hashes on each run. Use a deterministic hash derived from source location, for example:

hash = sha256("<normalized_repo_relative_path>:<line_number>").hexdigest()[:16]

This gives stable addressing for the same line across runs. SHA-1 outputs 40 hex characters (160 bits), and SHA-256 outputs 64 hex characters (256 bits), so truncating to 16+ hex characters keeps IDs compact while materially lowering collision risk. Collision behavior should be strict:

Same hash + same source location: append to the same log stream
Same hash + different source location: hard error

The hard error should include:

the conflicting hash
the original file:line
the new file:line
a fix hint (regenerate hash from source location)

This prevents two unrelated log points from being merged into one log area.

2) Fetch the summary with API key auth

curl -H "Authorization: Bearer $RAYSURFER_API_KEY" \
  https://api.mywebsite.com/logs/4b1f7f31a2c9d8e6.md

By default, .md returns a summary page, not a full raw run dump.

3) Expand only when needed

When the summary indicates an issue, the agent can curl deeper links:

Raw logs for the same hash
Related hashes for nearby lines/functions
Additional diagnostics for trend or slowness analysis

This avoids broad timestamp-to-timestamp log searches unless absolutely required.

Example summary shape

# Log Summary
timestamp: 2026-02-28T17:05:19Z
hash: 4b1f7f31a2c9d8e6
source: app/refills/service.py:184

## Recent values
- 17:04:53Z status=queued latency_ms=112
- 17:05:12Z status=queued latency_ms=117
- 17:05:19Z status=error_timeout latency_ms=842

## Auto insights
- trend: error rate +6.2% in last 30m
- slowness: p95 latency 2.4x baseline
- user_satisfaction: 0.71 -> 0.58
# based on thumbs_up/down, resolution, and repeat issue patterns

## Links
raw: raysurfer.com/logs/4b1f7f31a2c9d8e6.raw.md
related: raysurfer.com/logs/d22ac11b9f6e4c2a.md

What `user_satisfaction` means

user_satisfaction is an outcome signal, not a model guess. It is derived from:

thumbs_up / thumbs_down feedback
whether the issue was resolved after the run
whether similar issues repeated shortly after

Practical agent loop

curl summary -> detect issue -> curl related hash/raw -> act -> recheck summary

This gives agents deterministic debugging paths with low context overhead.

​Why this logging format works for agents

​1) Instrument the exact line

​Hash generation policy (and collisions)

​2) Fetch the summary with API key auth

​3) Expand only when needed

​Example summary shape

​What user_satisfaction means

​Practical agent loop