Documentation
¶
Overview ¶
Package trace is an opt-in, content-level debug tracer. When enabled (the server runs at the `trace` log level) it dumps the raw bytes flowing through the system (LLM prompt/response chains, raw HTTP feed-fetch bodies, and solimen-scraped HTML) to discrete files on disk so issues like non-UTF-8 feed responses or a misbehaving prompt chain can be inspected directly.
It is stdlib-only on purpose: keeping it free of project imports lets every layer (llmgateway, scrapers, manager) call into it without import cycles.
Every exported writer is a no-op when tracing is disabled and never returns an error to its caller; a failed trace write is logged and ignored so the debug facility can never break the main flow.
Index ¶
- func Content(articleID, rawURL, reason, content string)
- func Enabled() bool
- func HTTP(method, rawURL string, status int, contentType string, body []byte, ...)
- func Init(dir string, on bool) error
- func LLM(label, prompt, response string, dur time.Duration, callErr error, ...)
- func SaveDiagnostic(host string, status int, contentType string, body []byte) string
- func Scrape(articleID, rawURL, state, html string)
- func SolimenRequest(articleID, rawURL string, payload []byte)
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func Content ¶
func Content(articleID, rawURL, reason, content string)
Content records article content that was rejected/notable for a given reason (e.g. "invalid-utf8") as its own byte-exact file plus a metadata sidecar, so the offending bytes, which would otherwise be dropped, stay inspectable.
func Enabled ¶
func Enabled() bool
Enabled reports whether tracing is active. Call sites that must build a payload (e.g. read an HTTP body) should guard that work with this.
func HTTP ¶
HTTP records a raw HTTP response body as its own file (exact bytes, so non-UTF-8 payloads stay inspectable) alongside a small metadata sidecar.
func Init ¶
Init resolves the trace root and, when enabled, creates it and records its location. dir overrides the location; when empty a dedicated per-run folder under the OS temp dir is used (e.g. /tmp/downlink-trace-<timestamp>). When enabled is false this is a no-op and Enabled() stays false.
func SaveDiagnostic ¶ added in v0.2.0
SaveDiagnostic writes a raw feed body to disk regardless of whether tracing is enabled, and returns the absolute path it wrote (empty on failure). It backs the on-demand `feeds diagnose` command and the parse-failure breadcrumb: those need the offending bytes even when the server is not running at trace log level.
When tracing is on the file lands under the active trace dir's fetch/ folder so it sits alongside the rest of the run; otherwise it goes to a stable, lazily created os.TempDir()/downlink-diagnose folder. Like every other writer here it never returns an error to its caller.
func Scrape ¶
func Scrape(articleID, rawURL, state, html string)
Scrape records the raw HTML returned by a browser scrape (solimen) plus a metadata sidecar.
func SolimenRequest ¶
SolimenRequest records the JSON query body POSTed to the solimen scrape service, so the exact request can be compared against its result.
Types ¶
This section is empty.
Source Files