diff --git a/documentation/docs/guides/config-file.md b/documentation/docs/guides/config-file.md index fb8f953a320d..73ebb688ae42 100644 --- a/documentation/docs/guides/config-file.md +++ b/documentation/docs/guides/config-file.md @@ -6,7 +6,7 @@ sidebar_label: Configuration File # Configuration File -Goose uses a YAML configuration file to manage settings and extensions. This file is located at: +goose uses a YAML configuration file to manage settings and extensions. This file is located at: * macOS/Linux: `~/.config/goose/config.yaml` * Windows: `%APPDATA%\Block\goose\config\config.yaml` @@ -35,7 +35,9 @@ The following settings can be configured at the root level of your config.yaml f | `GOOSE_CLI_SHOW_COST` | Show estimated cost for token use in the CLI | true/false | false | No | | `GOOSE_ALLOWLIST` | URL for allowed extensions | Valid URL | None | No | | `GOOSE_RECIPE_GITHUB_REPO` | GitHub repository for recipes | Format: "org/repo" | None | No | -| `GOOSE_AUTO_COMPACT_THRESHOLD` | Set the percentage threshold at which Goose [automatically summarizes your session](/docs/guides/sessions/smart-context-management#automatic-compaction). | Float between 0.0 and 1.0 (disabled at 0.0)| 0.8 | No | +| `GOOSE_AUTO_COMPACT_THRESHOLD` | Set the percentage threshold at which goose [automatically summarizes your session](/docs/guides/sessions/smart-context-management#automatic-compaction). | Float between 0.0 and 1.0 (disabled at 0.0)| 0.8 | No | +| `otel_exporter_otlp_endpoint` | OTLP endpoint URL for [observability](/docs/guides/environment-variables#opentelemetry-protocol-otlp) | URL (e.g., `http://localhost:4318`) | None | No | +| `otel_exporter_otlp_timeout` | Export timeout in milliseconds for [observability](/docs/guides/environment-variables#opentelemetry-protocol-otlp) | Integer (ms) | 10000 | No | | `security_prompt_enabled` | Enable [prompt injection detection](/docs/guides/security/prompt-injection-detection) to identify potentially harmful commands | true/false | false | No | | `security_prompt_threshold` | Sensitivity threshold for [prompt injection detection](/docs/guides/security/prompt-injection-detection) (higher = stricter) | Float between 0.01 and 1.0 | 0.7 | No | @@ -75,6 +77,10 @@ GOOSE_CLI_MIN_PRIORITY: 0.2 # Recipe Configuration GOOSE_RECIPE_GITHUB_REPO: "block/goose-recipes" +# Observability (OpenTelemetry) +otel_exporter_otlp_endpoint: "http://localhost:4318" +otel_exporter_otlp_timeout: 20000 + # Security Configuration security_prompt_enabled: true @@ -102,10 +108,10 @@ Extensions are configured under the `extensions` key. Each extension can have th ```yaml extensions: extension_name: - bundled: true/false # Whether it's included with Goose - display_name: "Name" # Human-readable name (optional) - enabled: true/false # Whether the extension is active - name: "extension_name" # Internal name + bundled: true/false # Whether it's included with goose + display_name: "Name" # Human-readable name (optional) + enabled: true/false # Whether the extension is active + name: "extension_name" # Internal name timeout: 300 # Operation timeout in seconds type: "builtin"/"stdio" # Extension type @@ -113,8 +119,8 @@ extensions: cmd: "command" # Command to execute args: ["arg1", "arg2"] # Command arguments description: "text" # Extension description - env_keys: [] # Required environment variables - envs: {} # Environment values + env_keys: [] # Required environment variables + envs: {} # Environment values ``` ## Configuration Priority @@ -133,7 +139,7 @@ Settings are applied in the following order of precedence: ## Updating Configuration -Changes to the config file require restarting Goose to take effect. You can verify your current configuration using: +Changes to the config file require restarting goose to take effect. You can verify your current configuration using: ```bash goose info -v diff --git a/documentation/docs/guides/environment-variables.md b/documentation/docs/guides/environment-variables.md index 2ae552a1ba19..7f6dc0f2888f 100644 --- a/documentation/docs/guides/environment-variables.md +++ b/documentation/docs/guides/environment-variables.md @@ -4,7 +4,7 @@ title: Environment Variables sidebar_label: Environment Variables --- -Goose supports various environment variables that allow you to customize its behavior. This guide provides a comprehensive list of available environment variables grouped by their functionality. +goose supports various environment variables that allow you to customize its behavior. This guide provides a comprehensive list of available environment variables grouped by their functionality. ## Model Configuration @@ -12,7 +12,7 @@ These variables control the [language models](/docs/getting-started/providers) a ### Basic Provider Configuration -These are the minimum required variables to get started with Goose. +These are the minimum required variables to get started with goose. | Variable | Purpose | Values | Default | |----------|---------|---------|---------| @@ -70,7 +70,7 @@ A _turn_ is one complete prompt-response interaction. Here's how it works with t - Fallback to the lead model if the worker model struggles for 2 consecutive turns - Use the lead model for 2 turns and then switch back to the worker model -The lead model and worker model names are displayed at the start of the Goose CLI session. If you don't export a `GOOSE_MODEL` for your session, the worker model defaults to the `GOOSE_MODEL` in your [configuration file](/docs/guides/config-file). +The lead model and worker model names are displayed at the start of the goose CLI session. If you don't export a `GOOSE_MODEL` for your session, the worker model defaults to the `GOOSE_MODEL` in your [configuration file](/docs/guides/config-file). **Examples** @@ -88,7 +88,7 @@ export GOOSE_LEAD_FALLBACK_TURNS=2 ### Planning Mode Configuration -These variables control Goose's [planning functionality](/docs/guides/multi-model/creating-plans). +These variables control goose's [planning functionality](/docs/guides/multi-model/creating-plans). | Variable | Purpose | Values | Default | |----------|---------|---------|---------| @@ -146,17 +146,17 @@ export DATABRICKS_MAX_RETRY_INTERVAL_MS=60000 # cap the maximum retry del ## Session Management -These variables control how Goose manages conversation sessions and context. +These variables control how goose manages conversation sessions and context. | Variable | Purpose | Values | Default | |----------|---------|---------|---------| -| `GOOSE_CONTEXT_STRATEGY` | Controls how Goose handles context limit exceeded situations | "summarize", "truncate", "clear", "prompt" | "prompt" (interactive), "summarize" (headless) | +| `GOOSE_CONTEXT_STRATEGY` | Controls how goose handles context limit exceeded situations | "summarize", "truncate", "clear", "prompt" | "prompt" (interactive), "summarize" (headless) | | `GOOSE_MAX_TURNS` | [Maximum number of turns](/docs/guides/sessions/smart-context-management#maximum-turns) allowed without user input | Integer (e.g., 10, 50, 100) | 1000 | | `CONTEXT_FILE_NAMES` | Specifies custom filenames for [hint/context files](/docs/guides/using-goosehints#custom-context-files) | JSON array of strings (e.g., `["CLAUDE.md", ".goosehints"]`) | `[".goosehints"]` | | `GOOSE_CLI_THEME` | [Theme](/docs/guides/goose-cli-commands#themes) for CLI response markdown | "light", "dark", "ansi" | "dark" | | `GOOSE_RANDOM_THINKING_MESSAGES` | Controls whether to show amusing random messages during processing | "true", "false" | "true" | | `GOOSE_CLI_SHOW_COST` | Toggles display of model cost estimates in CLI output | "true", "1" (case insensitive) to enable | false | -| `GOOSE_AUTO_COMPACT_THRESHOLD` | Set the percentage threshold at which Goose [automatically summarizes your session](/docs/guides/sessions/smart-context-management#automatic-compaction). | Float between 0.0 and 1.0 (disabled at 0.0) | 0.8 | +| `GOOSE_AUTO_COMPACT_THRESHOLD` | Set the percentage threshold at which goose [automatically summarizes your session](/docs/guides/sessions/smart-context-management#automatic-compaction). | Float between 0.0 and 1.0 (disabled at 0.0) | 0.8 | **Examples** @@ -194,7 +194,7 @@ export GOOSE_AUTO_COMPACT_THRESHOLD=0.6 ### Model Context Limit Overrides -These variables allow you to override the default context window size (token limit) for your models. This is particularly useful when using [LiteLLM proxies](https://docs.litellm.ai/docs/providers/litellm_proxy) or custom models that don't match Goose's predefined model patterns. +These variables allow you to override the default context window size (token limit) for your models. This is particularly useful when using [LiteLLM proxies](https://docs.litellm.ai/docs/providers/litellm_proxy) or custom models that don't match goose's predefined model patterns. | Variable | Purpose | Values | Default | |----------|---------|---------|---------| @@ -221,11 +221,11 @@ For more details and examples, see [Model Context Limit Overrides](/docs/guides/ ## Tool Configuration -These variables control how Goose handles [tool execution](/docs/guides/goose-permissions) and [tool management](/docs/guides/managing-tools/). +These variables control how goose handles [tool execution](/docs/guides/goose-permissions) and [tool management](/docs/guides/managing-tools/). | Variable | Purpose | Values | Default | |----------|---------|---------|---------| -| `GOOSE_MODE` | Controls how Goose handles tool execution | "auto", "approve", "chat", "smart_approve" | "smart_approve" | +| `GOOSE_MODE` | Controls how goose handles tool execution | "auto", "approve", "chat", "smart_approve" | "smart_approve" | | `GOOSE_ENABLE_ROUTER` | Enables [intelligent tool selection strategy](/docs/guides/managing-tools/tool-router) | "true", "false" | "false" | | `GOOSE_TOOLSHIM` | Enables/disables tool call interpretation | "1", "true" (case insensitive) to enable | false | | `GOOSE_TOOLSHIM_OLLAMA_MODEL` | Specifies the model for [tool call interpretation](/docs/experimental/ollama) | Model name (e.g. llama3.2, qwen2.5) | System default | @@ -294,7 +294,34 @@ When the keyring is disabled, secrets are stored here: * Windows: `%APPDATA%\Block\goose\config\secrets.yaml` ::: -## Langfuse Integration +## Observability + +Beyond Goose's built-in [logging system](/docs/guides/logs), you can export telemetry to external observability platforms for advanced monitoring, performance analysis, and production insights. + +### OpenTelemetry Protocol (OTLP) + +Configure goose to export traces and metrics to any OTLP-compatible observability platform. +OTLP is the standard protocol for sending telemetry collected by [OpenTelemetry](https://opentelemetry.io/docs/). When configured, goose exports telemetry asynchronously and flushes on exit. + +| Variable | Purpose | Values | Default | +|----------|---------|--------|---------| +| `OTEL_EXPORTER_OTLP_ENDPOINT` | OTLP endpoint URL | URL (e.g., `http://localhost:4318`) | None | +| `OTEL_EXPORTER_OTLP_TIMEOUT` | Export timeout in milliseconds | Integer (ms) | `10000` | + +**When to use OTLP:** +- Diagnosing slow tool execution or LLM response times when goose +- Understanding intermittent failures across multiple sessions +- Monitoring goose performance in production or CI/CD environments +- Tracking usage patterns, costs, and resource consumption over time +- Setting up alerts for performance degradation or high error rates + +**Example:** +```bash +export OTEL_EXPORTER_OTLP_ENDPOINT="http://localhost:4318" +export OTEL_EXPORTER_OTLP_TIMEOUT=10000 +``` + +### Langfuse Integration These variables configure the [Langfuse integration for observability](/docs/tutorials/langfuse). @@ -349,28 +376,28 @@ export ALPHA_FEATURES=true ALPHA_FEATURES=true goose session ``` -## Variables Controlled by Goose +## Variables Controlled by goose -These variables are automatically set by Goose during command execution. +These variables are automatically set by goose during command execution. | Variable | Purpose | Values | Default | |----------|---------|---------|---------| -| `GOOSE_TERMINAL` | Indicates that a command is being executed by Goose, enables customizing shell behavior | "1" when set | Unset | +| `GOOSE_TERMINAL` | Indicates that a command is being executed by goose, enables customizing shell behavior | "1" when set | Unset | ### Customizing Shell Behavior -Sometimes you want Goose to use different commands or have different shell behavior than your normal terminal usage. For example, you might want Goose to use a different tool, or prevent Goose from running long-running development servers that could hang the AI agent. This is most useful when using Goose CLI, where shell commands are executed directly in your terminal environment. +Sometimes you want goose to use different commands or have different shell behavior than your normal terminal usage. For example, you might want goose to use a different tool, or prevent goose from running long-running development servers that could hang the AI agent. This is most useful when using goose CLI, where shell commands are executed directly in your terminal environment. **How it works:** -1. When Goose runs commands, `GOOSE_TERMINAL` is automatically set to "1" -2. Your shell configuration can detect this and direct Goose to change its default behavior while keeping your normal terminal usage unchanged +1. When goose runs commands, `GOOSE_TERMINAL` is automatically set to "1" +2. Your shell configuration can detect this and direct goose to change its default behavior while keeping your normal terminal usage unchanged **Example:** ```bash # In your ~/.bashrc or ~/.zshrc -# Guide Goose toward better tool choices +# Guide goose toward better tool choices if [[ -n "$GOOSE_TERMINAL" ]]; then alias find="echo 'Use rg instead: rg --files | rg for filenames, or rg for content search'" fi @@ -380,6 +407,6 @@ fi - Environment variables take precedence over configuration files. - For security-sensitive variables (like API keys), consider using the system keyring instead of environment variables. -- Some variables may require restarting Goose to take effect. -- When using the planning mode, if planner-specific variables are not set, Goose will fall back to the main model configuration. +- Some variables may require restarting goose to take effect. +- When using the planning mode, if planner-specific variables are not set, goose will fall back to the main model configuration. diff --git a/documentation/docs/troubleshooting.md b/documentation/docs/troubleshooting.md index 78feb8f3dc48..104b0e2d17a4 100644 --- a/documentation/docs/troubleshooting.md +++ b/documentation/docs/troubleshooting.md @@ -11,7 +11,7 @@ goose can and will edit files as part of its workflow. To avoid losing personal --- -### Interrupting Goose +### Interrupting goose If goose is heading in the wrong direction or gets stuck, you can [interrupt it](/docs/guides/sessions/in-session-actions#interrupt-task) to correct its actions or provide additional information. --- @@ -32,15 +32,24 @@ For particularly large or complex tasks, consider breaking them into smaller ses ### Preventing Long-Running Commands -If you use goose CLI and work with web development projects, you may encounter commands that cause Goose to hang indefinitely. Commands like `npm run dev`, `python -m http.server`, or `webpack serve` start development servers that never exit on their own. +If you use goose CLI and work with web development projects, you may encounter commands that cause goose to hang indefinitely. Commands like `npm run dev`, `python -m http.server`, or `webpack serve` start development servers that never exit on their own. You can prevent these issues by customizing your shell to handle these commands differently when goose runs them. See [Customizing Shell Behavior](/docs/guides/environment-variables#customizing-shell-behavior) for details on using the `GOOSE_TERMINAL` environment variable. --- +### Debugging and Diagnostics + +To help with troubleshooting issues, you can: + +- View [session and system logs](/docs/guides/logs) for debugging individual sessions +- Configure [telemetry export](/docs/guides/environment-variables#observability) for performance analysis, trend monitoring, or production/CI debugging + +--- + ### Context Length Exceeded Error -This error occurs when the input provided to Goose exceeds the maximum token limit of the LLM being used. To resolve this, try breaking down your input into smaller parts. You can also use [`.goosehints`][goosehints] as a way to provide goose with detailed context and use [message queues](/docs/guides/sessions/in-session-actions#queue-messages) in goose Desktop. +This error occurs when the input provided to goose exceeds the maximum token limit of the LLM being used. To resolve this, try breaking down your input into smaller parts. You can also use [`.goosehints`][goosehints] as a way to provide goose with detailed context and use [message queues](/docs/guides/sessions/in-session-actions#queue-messages) in goose Desktop. --- @@ -136,7 +145,7 @@ goose tries to use the system keyring (which requires DBus and X11) to securely To resolve: -Use the `GOOSE_DISABLE_KEYRING` environment variable to tell Goose to store secrets in files instead. This example sets the variable only while executing the `goose configure` command: +Use the `GOOSE_DISABLE_KEYRING` environment variable to tell goose to store secrets in files instead. This example sets the variable only while executing the `goose configure` command: ```bash GOOSE_DISABLE_KEYRING=1 goose configure @@ -296,7 +305,7 @@ If you encounter the error `Node.js installer script not found` when trying to a - Error occurs specifically when activating Node.js extensions #### Solution: -This issue typically occurs when Node.js is installed in a non-standard location. Goose expects to find Node.js in `C:\Program Files\nodejs\`, but it may be installed elsewhere (e.g., `D:\Program Files\nodejs\`). +This issue typically occurs when Node.js is installed in a non-standard location. goose expects to find Node.js in `C:\Program Files\nodejs\`, but it may be installed elsewhere (e.g., `D:\Program Files\nodejs\`). 1. **Check your Node.js installation path:** ```powershell @@ -305,7 +314,7 @@ This issue typically occurs when Node.js is installed in a non-standard location 2. **If Node.js is not in `C:\Program Files\nodejs\`, create a symbolic link:** - Open PowerShell as Administrator - - Create a symbolic link to redirect Goose to your actual Node.js installation: + - Create a symbolic link to redirect goose to your actual Node.js installation: ```powershell mklink /D "C:\Program Files\nodejs" "D:\Program Files\nodejs" ``` @@ -451,7 +460,7 @@ goose Desktop uses **"shims"** (packaged versions of `npx` and `uvx`) that autom args: [mcp-server-example] ``` -3. **Why this works:** Goose only replaces known command names (`npx`, `uvx`, `jbang`, etc.) with its packaged shims. Custom names are passed through unchanged to your system's actual executables. +3. **Why this works:** goose only replaces known command names (`npx`, `uvx`, `jbang`, etc.) with its packaged shims. Custom names are passed through unchanged to your system's actual executables. 4. **Require more changes**: In a corporate proxy environment or airgapped environment where the above doesn't work, it is recommended that you customize and package up goose desktop with shims/config that will work given the network constraints you have (for example, TLS certificate limitations, proxies, inability to download required content etc).