Documentation
¶
Overview ¶
Package trace provides the two observers an operator wants while a run executes: aligned lines for a terminal and JSON Lines for a collector. Both are safe for concurrent use, because the runtime delivers events from whichever goroutine committed them. WriteRecheck renders a re-check report (agentrt.Recheck) for the same terminal.
Index ¶
- func JSONL(w io.Writer) agentrt.Observer
- func JSONLWithErr(w io.Writer) (obs agentrt.Observer, errFn func() error)
- func Sanitize(s string) string
- func WriteRecheck(w io.Writer, rep agentrt.RecheckReport) error
- func Writer(w io.Writer) agentrt.Observer
- func WriterWithErr(w io.Writer) (obs agentrt.Observer, errFn func() error)
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func JSONL ¶
JSONL returns an observer writing one JSON object per event. The payload is passed through as recorded: the encoder's HTML escaping is off, so a payload containing <, >, or & is not rewritten on its way out. An event whose payload will not encode as JSON is not dropped: it is emitted with the payload as a JSON string and invalid_payload set to true.
func JSONLWithErr ¶ added in v0.3.0
JSONLWithErr is JSONL plus a way to learn whether a write to w failed. Err returns the first write error, if any; call it after the run whose events are being traced has finished.
func Sanitize ¶ added in v0.3.0
Sanitize makes a string that may originate from a model or a remote server safe to print to a terminal. Invalid UTF-8 becomes the replacement character. C0 controls, DEL, and C1 controls (U+0080-U+009F) become a visible \xHH escape, because left alone they can clear the screen, move the cursor, set the window title, or forge output such as a fake "APPROVAL WAITING" block. Bidirectional overrides and isolates, zero-width and other invisible formatting characters, the line and paragraph separators, and the Unicode tag block become a visible \u{XXXX} escape, because none of them execute anything but all of them change how the surrounding text is displayed without changing what it is: a bidi override can make "rm -rf ~" read as something else, and an invisible character can hide inside what looks like a short, safe argument. A run of more than maxCombining combining marks on one base character is cut, leaving the first maxCombining and a marker for how many were dropped, so a base character cannot be turned into a multi-line block of glyphs. Ordinary non-Latin text, emoji, and legitimate combining sequences are left exactly as given. A newline becomes a space instead of an escape, so a field stays one line rather than growing a control-code footprint. JSON output is never passed through Sanitize: it escapes C0 already and a consumer parsing JSON is not a terminal.
func WriteRecheck ¶ added in v0.5.0
func WriteRecheck(w io.Writer, rep agentrt.RecheckReport) error
WriteRecheck writes a re-check report as text for a terminal: a header line with the run, its status, how many of the evaluations re-checked differ, what is known of the policy's identity, and which specs the requests carried; then one line per evaluation, the ones that differ first, each marked DIFFERENT, same, or skipped, with the step, the event's seq, the tool, and what the evaluation came to; then the report's notes. Every value the record or a policy chose is sanitized and cut at 240 bytes, so each evaluation is one line however it was recorded. The JSON form is the report's own MarshalJSON.
func Writer ¶
Writer returns an observer printing one line per event: the local date, time, and zone, two spaces, the event type padded to 22 columns, and the payload. This is the format both consumers print to stderr with -trace. The payload is JSON and already escapes C0 controls, but not C1 controls or DEL, so it is sanitized before it reaches the terminal.
Types ¶
This section is empty.
Source Files