debuglog

Documentation

Overview

Package debuglog provides a lightweight, opt-in NDJSON event logger for auditing how anchored is actually being used by the host AI tool.

The goal is observability, not telemetry: when the user wants to understand why memory tools fired (or didn't), they enable Debug.Enabled in ~/.anchored/config.yaml (or set ANCHORED_DEBUG=1) and get an append-only NDJSON file they can grep, jq, or replay.

Design rules:

• Never fail the caller. Open/Write errors are swallowed; the worst case is a missing log line, never a broken hook or MCP call.
• One JSON object per line ({ts, event, ...fields}) so the file is trivially parsable with jq -c or Python's json.loads per line.
• Append-only with O_APPEND so concurrent processes (multiple hook invocations + the MCP server) don't clobber each other; we still take a mutex per *Logger to keep individual writes intact.

Index

• func Snippet(s string, n int) string
• type Logger
  • func Open(cfg *config.Config) *Logger
  • func (l *Logger) Close() error
  • func (l *Logger) Enabled() bool
  • func (l *Logger) Event(name string, fields map[string]any)
  • func (l *Logger) Path() string

Functions

func Snippet

func Snippet(s string, n int) string

Snippet truncates s to n runes, appending an ellipsis when trimmed. Use this on user-facing strings (prompt bodies, tool args) so the log doesn't balloon with multi-KB payloads.

Rune-aware (not byte-aware) on purpose: PT-BR / multilingual prompts would otherwise be cut mid-codepoint, producing invalid UTF-8 that json.Marshal silently replaces with U+FFFD — corrupting the very evidence the debug log exists to capture.

Types

type Logger

type Logger struct {
	// contains filtered or unexported fields
}

Logger is a single-file NDJSON appender. The zero value is a valid no-op Logger; callers can safely call Event on a nil receiver.

func Open

func Open(cfg *config.Config) *Logger

Open returns a Logger configured from cfg, with environment overrides.

Env overrides (highest precedence):

• ANCHORED_DEBUG=1|true|on → force enable
• ANCHORED_DEBUG=0|false|off → force disable
• ANCHORED_DEBUG_PATH=/path → override log file path

When disabled, Open returns a zero-value Logger that no-ops on Event so call sites stay branch-free.

func (*Logger) Close

func (l *Logger) Close() error

Close flushes and releases the underlying file handle. Safe on nil.

func (*Logger) Enabled

func (l *Logger) Enabled() bool

Enabled reports whether this logger will actually write.

func (*Logger) Event

func (l *Logger) Event(name string, fields map[string]any)

Event appends an NDJSON line. fields are merged with built-in {ts, event} keys; collisions are won by built-ins to keep the schema predictable.

func (*Logger) Path

func (l *Logger) Path() string

Path returns the resolved log path, or "" when disabled.