From c071900022e92af8606690a814fb4782ff674222 Mon Sep 17 00:00:00 2001 From: Angie Jones Date: Tue, 18 Feb 2025 09:57:49 -0600 Subject: [PATCH] docs: logging guide (#1269) --- documentation/docs/guides/file-management.md | 2 +- .../handling-llm-rate-limits-with-goose.md | 2 - documentation/docs/guides/logs.md | 118 ++++++++++++++++++ 3 files changed, 119 insertions(+), 3 deletions(-) create mode 100644 documentation/docs/guides/logs.md diff --git a/documentation/docs/guides/file-management.md b/documentation/docs/guides/file-management.md index 11d1c6e6..622dcca8 100644 --- a/documentation/docs/guides/file-management.md +++ b/documentation/docs/guides/file-management.md @@ -1,5 +1,5 @@ --- -sidebar_position: 5 +sidebar_position: 6 --- # File Management diff --git a/documentation/docs/guides/handling-llm-rate-limits-with-goose.md b/documentation/docs/guides/handling-llm-rate-limits-with-goose.md index e391b338..a75d1a37 100644 --- a/documentation/docs/guides/handling-llm-rate-limits-with-goose.md +++ b/documentation/docs/guides/handling-llm-rate-limits-with-goose.md @@ -18,8 +18,6 @@ OpenRouter provides a unified interface for LLMs that allows you to select and s 1. Go to [openrouter.ai](https://openrouter.ai) and create an account. 2. Once verified, create your [API key](https://openrouter.ai/settings/keys). - - diff --git a/documentation/docs/guides/logs.md b/documentation/docs/guides/logs.md new file mode 100644 index 00000000..eeb859d9 --- /dev/null +++ b/documentation/docs/guides/logs.md @@ -0,0 +1,118 @@ +--- +title: Logging System +sidebar_position: 5 +--- + +# Goose Logging System + +Goose uses a unified storage system for conversations and interactions. All conversations and interactions (both CLI and Desktop) are stored **locally** in the following locations: + +| **Type** | **Unix-like (macOS, Linux)** | **Windows** | +|---------------------|----------------------------------------|---------------------------------------------| +| **Session Records** | `~/.local/share/goose/sessions/` | `%APPDATA%\Block\goose\data\sessions\` | +| **System Logs** | `~/.local/state/goose/logs/` | `%APPDATA%\Block\goose\data\logs\` | + + +:::info Privacy +Goose is a local application and all log files are stored locally. These logs are never sent to external servers or third parties, ensuring that all data remains private and under your control. +::: + + + +## Session Records + +Goose maintains session records in `~/.local/share/goose/sessions/` that track the conversation history and interactions for each session. These files use the `.jsonl` format (JSON Lines), where each line is a valid JSON object representing a message or interaction. + +Session files are named with the pattern `[session-id].jsonl` where the session ID matches the identifier used in the corresponding log files. For example, `ccK9OTmS.jsonl` corresponds to log files like `20250211_133920-ccK9OTmS.log`. + +Each session file contains a chronological record of: +- User messages and commands +- Assistant (Goose) responses +- Tool requests and their results +- Timestamps for all interactions +- Role information (user/assistant) +- Message content and formatting +- Tool call details including: + - Tool IDs + - Arguments passed + - Results returned + - Success/failure status + +Each line in a session file is a JSON object with the following key fields: +- `role`: Identifies the source ("user" or "assistant") +- `created`: Timestamp of the interaction +- `content`: Array of interaction elements, which may include: + - Text messages + - Tool requests + - Tool responses + - Error messages + +## System Logs + +### Main System Log + +The main system log locations: +* Unix-like: `~/.local/state/goose/logs/goose.log` +* Windows: `%APPDATA%\Block\goose\data\logs\goose.log` + +This log contains general application-level logging including: +* Session file locations +* Token usage statistics as well as token counts (input, output, total) +* LLM information (model names, versions) + + +### Desktop Application Log + +The desktop application maintains its own logs: +* macOS: `~/Library/Application Support/Goose/logs/main.log` +* Windows: `%APPDATA%\Block\goose\logs\main.log` + +The Desktop application follows platform conventions for its own operational logs and state data, but uses the standard Goose [session records](#session-records) for actual conversations and interactions. This means your conversation history is consistent regardless of which interface you use to interact with Goose. + +### CLI Logs + +CLI logs are stored in: +* Unix-like: `~/.local/state/goose/logs/cli/` +* Windows: `%APPDATA%\Block\goose\data\logs\cli\` + +CLI session logs contain: +* Tool invocations and responses +* Command execution details +* Session identifiers +* Timestamps + +Extension logs contain: +* Tool initialization +* Tool capabilities and schemas +* Extension-specific operations +* Command execution results +* Error messages and debugging information +* Extension configuration states +* Extension-specific protocol information + +### Server Logs + +Server logs are stored in: +* Unix-like: `~/.local/state/goose/logs/server/` +* Windows: `%APPDATA%\Block\goose\data\logs\server\` + +The Server logs contain information about the Goose daemon (`goosed`), which is a local server process that runs on your computer. This server component manages communication between the CLI, extensions, and LLMs. + +Server logs include: +* Server initialization details +* JSON-RPC communication logs +* Server capabilities +* Protocol version information +* Client-server interactions +* Extension loading and initialization +* Tool definitions and schemas +* Extension instructions and capabilities +* Debug-level transport information +* System capabilities and configurations +* Operating system information +* Working directory information +* Transport layer communication details +* Message parsing and handling information +* Request/response cycles +* Error states and handling +* Extension initialization sequences