Skip to content

docs: otlp observability #5436

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
dianed-square merged 2 commits into from
Oct 29, 2025
Merged

docs: otlp observability #5436

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
673e003
doc otlp
dianed-square Oct 29, 2025
c7096b1
Merge branch 'main' into docs/otlp
dianed-square Oct 29, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
24 changes: 15 additions & 9 deletions documentation/docs/guides/config-file.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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`
Expand Down Expand Up @@ -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 |

Expand Down Expand Up @@ -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

Expand Down Expand Up @@ -102,19 +108,19 @@ 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

# Additional settings for stdio 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
Expand All @@ -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
Expand Down
67 changes: 47 additions & 20 deletions documentation/docs/guides/environment-variables.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,15 +4,15 @@ 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

These variables control the [language models](/docs/getting-started/providers) and their behavior.

### 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 |
|----------|---------|---------|---------|
Expand Down Expand Up @@ -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**

Expand All @@ -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 |
|----------|---------|---------|---------|
Expand Down Expand Up @@ -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**

Expand Down Expand Up @@ -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 |
|----------|---------|---------|---------|
Expand All @@ -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 |
Expand Down Expand Up @@ -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).

Expand Down Expand Up @@ -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
Expand All @@ -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.

23 changes: 16 additions & 7 deletions documentation/docs/troubleshooting.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.

---
Expand All @@ -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.

---

Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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
Expand All @@ -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"
```
Expand Down Expand Up @@ -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).

Expand Down