awesome-bookmarks/goose
3
0
Fork 0
mirror of https://github.com/block/goose.git synced 2026-07-17 12:56:20 +02:00
Code Issues Packages Projects Releases Wiki Activity

docs: otlp observability (#5436)

Browse Source
This commit is contained in:
dianed-square
2025-10-29 10:36:42 -07:00
committed by GitHub
parent 339bcd4562
commit 565dcb879b
3 changed files with 78 additions and 36 deletions
Download Patch File Download Diff File Expand all files Collapse all files
documentation/docs/guides/config-file.md
+15 -9
View File
@@ -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
documentation/docs/guides/environment-variables.md
+47 -20
View File
@@ -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 <pattern> for filenames, or rg <pattern> 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.
documentation/docs/troubleshooting.md
+16 -7
View File
@@ -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).