httplog

package
v0.0.57 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Aug 9, 2026 License: MIT Imports: 12 Imported by: 0

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

View Source
const (
	DirectionRequest  = "request"
	DirectionResponse = "response"
)

Direction distinguishes the two halves of an exchange.

View Source
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

func Emit(ctx context.Context, e Entry)

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 MaxBody

func MaxBody() int

MaxBody returns the current JSONL body cap.

func NextExchange

func NextExchange() uint64

NextExchange returns a fresh correlation ID for a request/response pair.

func Redact

func Redact(h http.Header) map[string][]string

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.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL