> ## Documentation Index
> Fetch the complete documentation index at: https://docs.raysurfer.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Logging for LLM Agents

> Summary-first hashed logs that agents can expand incrementally with authenticated curl

## 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:

1. Start with a compact summary for one exact line hash
2. Expand only when needed by curling related hashes
3. 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.

<CodeGroup>
  ```python Python theme={null}
  result = run_refill_check(payload)
  raysurfer.log(result, "4b1f7f31a2c9d8e6")
  ```

  ```typescript TypeScript theme={null}
  const result = await runRefillCheck(payload);
  raysurfer.log(result, "4b1f7f31a2c9d8e6");
  ```
</CodeGroup>

## Hash generation policy (and collisions)

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

```text theme={null}
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

```bash theme={null}
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

```md theme={null}
# 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

```text theme={null}
curl summary -> detect issue -> curl related hash/raw -> act -> recheck summary
```

This gives agents deterministic debugging paths with low context overhead.