Documentation
¶
Overview ¶
Package httplog carries raw HTTP request/response traces from the provider transports to whichever sinks are active — the JSONL session log, OpenTelemetry span events, or both.
It exists as its own package to break an ownership cycle. The provider transports are built during startup, before the session logger exists (internal/cli/cli.go builds the LLM at ~:251 and the logger at ~:568), so a transport cannot hold a logger reference at construction time. Instead the transport emits into this package unconditionally and the CLI installs a sink once the logger is ready — the same late-binding idiom as auth.SetDebugLogger.
Nothing is captured unless SetEnabled(true) has been called: Enabled() is checked before a body is ever buffered, so the disabled path costs one atomic load per request.
Index ¶
- Constants
- func CaptureBody(rc io.ReadCloser, done func(body string, truncated bool)) io.ReadCloser
- func Emit(ctx context.Context, e Entry)
- func Enabled() bool
- func MaxBody() int
- func NextExchange() uint64
- func Redact(h http.Header) map[string][]string
- func SetEnabled(v bool)
- func SetMaxBody(n int)
- func SetOTelMaxBody(n int)
- func SetSink(fn func(Entry))
- type Entry
Constants ¶
const ( DirectionRequest = "request" DirectionResponse = "response" )
Direction distinguishes the two halves of an exchange.
const ( DefaultMaxBody = 1 << 20 // 1 MiB, JSONL sink DefaultOTelMaxBody = 8 << 10 // 8 KiB, span-event attributes )
Default body caps. Requests carry the full conversation history, so a cap is not optional — a single turn late in a long session runs to hundreds of kilobytes, and the log is written on every request.
The OTel cap is deliberately much smaller than the JSONL one. Span attributes travel through the OTLP exporter, which batches in memory and is bounded by the collector's own message-size limit; a megabyte-scale attribute silently drops the whole span at the collector rather than truncating it. The file sink has no such ceiling, so it keeps the larger cap.
Variables ¶
This section is empty.
Functions ¶
func CaptureBody ¶
func CaptureBody(rc io.ReadCloser, done func(body string, truncated bool)) io.ReadCloser
CaptureBody buffers up to MaxBody bytes of rc as it is read by the real consumer, then calls done exactly once when the stream ends — at EOF, at a read error, or at Close, whichever comes first.
It exists because a streaming response cannot be logged the way an ordinary one can. io.ReadAll on an SSE body blocks until the model finishes its turn, which for a long completion means the SDK sees no tokens for minutes and the TUI renders nothing; for a body that never terminates it deadlocks outright. Buffering alongside the consumer keeps the stream flowing at its own pace and defers the log entry to the point where there is something complete to write.
func Emit ¶
Emit delivers e to the installed sink and, when ctx carries a recording span, records it as a span event. It is safe to call with capture disabled or no sink installed.
ctx is the request's context, so the span picked up is the agent turn the call belongs to (see internal/tui/agent_loop.go, which starts it).
func Enabled ¶
func Enabled() bool
Enabled reports whether capture is on. Transports must check this before buffering anything.
func NextExchange ¶
func NextExchange() uint64
NextExchange returns a fresh correlation ID for a request/response pair.
func Redact ¶
Redact copies h, replacing credential values with a prefix and a length so the entry stays diagnostically useful without carrying the secret.
The copy matters: http.Header is a live map owned by the request, and redacting in place would strip the caller's own credentials.
func SetEnabled ¶
func SetEnabled(v bool)
SetEnabled turns capture on or off. Off by default; the CLI sets it from --debug.
func SetMaxBody ¶
func SetMaxBody(n int)
SetMaxBody overrides the JSONL body cap. A value <= 0 restores the default.
func SetOTelMaxBody ¶
func SetOTelMaxBody(n int)
SetOTelMaxBody overrides the span-attribute body cap. A value <= 0 restores the default.
func SetSink ¶
func SetSink(fn func(Entry))
SetSink installs the destination for captured entries, replacing any previous one. Passing nil detaches the sink, which is what tests and shutdown want — entries emitted with no sink are dropped, not buffered.
OTel span events are emitted independently of the sink, so tracing works even when no session log exists.
Types ¶
type Entry ¶
type Entry struct {
// Exchange correlates the request with its response. Monotonic per process.
Exchange uint64
// Direction is DirectionRequest or DirectionResponse.
Direction string
// Method and URL are set on both directions so a response entry is
// readable on its own.
Method string
URL string
// Proto and Status are set on responses only.
Proto string
Status int
// Headers is already redacted; see Redact.
Headers map[string][]string
// Body is the captured payload, truncated to MaxBody. Empty when the
// message had no body.
Body string
// BodyTruncated reports that Body was cut at the cap.
BodyTruncated bool
// Duration is the time from request write to response headers. Set on
// responses only.
Duration time.Duration
// Err is the transport-level failure, if the round trip never produced a
// response. Set on responses only.
Err string
}
Entry is one captured half of an HTTP exchange. Requests and responses are emitted as separate entries rather than one combined record because a streaming response body is not complete until long after its headers arrive — a single record would have to withhold the request until the stream drained. Exchange ties the pair back together.