Documentation
¶
Overview ¶
Package logger provides structured, append-only event logging for jungi.
Each event is written as a single JSON object followed by a newline (JSON Lines format), making the output both human-readable with standard tools and easy to process programmatically with jq or log aggregators.
A Logger is safe for concurrent use; a mutex serialises writes so events from the TUI goroutine and the API response goroutine never interleave.
Index ¶
- type Event
- type Logger
- func (l *Logger) APIRequestSent(messageCount int)
- func (l *Logger) APIResponseReceived(inputTokens, outputTokens, cacheReadTokens int64, cost float64)
- func (l *Logger) AgentEnd(agentName, agentID string, durationMs int64, errMsg string)
- func (l *Logger) AgentLoadWarning(path, reason string)
- func (l *Logger) AgentStart(agentName, agentID, parentSessionID, model string)
- func (l *Logger) ControlConnected(url, remoteSessionID string)
- func (l *Logger) Error(err error)
- func (l *Logger) ProjectSettingsWarning(path, reason string)
- func (l *Logger) PromptLoadWarning(path, reason string)
- func (l *Logger) SessionStart(sessionID, model string)
- func (l *Logger) SkillLoadWarning(path, reason string)
- func (l *Logger) ToolExecution(command string, outputLen int, isError bool, durationMs int64)
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Event ¶
type Event struct {
Timestamp string `json:"timestamp"`
Type string `json:"type"`
Data map[string]any `json:"data"`
}
Event is a single record in the log file.
Type identifies the kind of event (e.g. "session_start", "api_request_sent") and determines which keys appear in Data. Timestamp is always UTC in RFC 3339 nanosecond precision so log files can be merged across time zones.
type Logger ¶
type Logger struct {
// contains filtered or unexported fields
}
Logger writes structured JSON-Lines events to an underlying io.Writer. The zero value is not usable; construct with New or NewFile.
func New ¶
New creates a Logger that appends events to w.
Useful for testing with a bytes.Buffer or for directing output to stdout. The caller retains ownership of w; Logger never closes it.
func NewFile ¶
NewFile creates a Logger backed by a new file at {logDir}/{sessionID}.jsonl.
It creates logDir (and any missing parents) with mode 0755 before opening the file, so callers do not need to ensure the directory exists in advance. The returned closer flushes and releases the file descriptor; it must be called when the session ends, typically via defer.
func (*Logger) APIRequestSent ¶
APIRequestSent records that a request is about to be dispatched to the provider API. messageCount is the number of messages in the context window at the time of the call, which grows with each turn and resets after compaction.
func (*Logger) APIResponseReceived ¶
func (l *Logger) APIResponseReceived(inputTokens, outputTokens, cacheReadTokens int64, cost float64)
APIResponseReceived records billing and context metadata for a completed API call.
Token fields map to the provider's usage object:
- inputTokens: uncached tokens in the prompt
- outputTokens: tokens generated in the reply
- cacheReadTokens: tokens served from the prompt cache
cost is the dollar figure the provider reported for this single call.
func (*Logger) AgentEnd ¶
AgentEnd records the completion of a subagent. errMsg is empty on success. Without this terminal event the log file just stops writing when Run returns, leaving "stuck vs. finished" ambiguous from logs alone.
func (*Logger) AgentLoadWarning ¶
AgentLoadWarning records a non-fatal problem encountered while loading agents from a directory (e.g. a malformed AGENT.md or a name collision during registry merging).
func (*Logger) AgentStart ¶
AgentStart records the launch of a subagent, capturing enough context to correlate agent log files with the parent session.
func (*Logger) ControlConnected ¶
ControlConnected records a successful jungi control connection, capturing the remote session id so it can be cross-referenced against the control service's own records when diagnosing channel issues.
func (*Logger) Error ¶
Error records a non-fatal failure. The event captures the error message string; callers retain responsibility for deciding whether to abort or continue the session.
func (*Logger) ProjectSettingsWarning ¶
ProjectSettingsWarning records a non-fatal problem encountered while loading the project-level settings file (<repo>/.jungi/settings.toml), such as a parse error. The user-level settings remain in effect unchanged when this fires.
func (*Logger) PromptLoadWarning ¶
PromptLoadWarning records a non-fatal problem encountered while loading prompts from a directory (e.g. a malformed .md file or a name collision during registry merging).
func (*Logger) SessionStart ¶
SessionStart records the opening of a new conversation, capturing which model was selected so log files are self-describing when reviewed later.
func (*Logger) SkillLoadWarning ¶
SkillLoadWarning records a non-fatal problem encountered while loading skills from a directory (e.g. a malformed SKILL.md or a name collision during registry merging).
Source Files
¶
- logger.go