diff --git a/documentation/docs/guides/config-files.md b/documentation/docs/guides/config-files.md index deff5e3c54e3..2a25d77e7c35 100644 --- a/documentation/docs/guides/config-files.md +++ b/documentation/docs/guides/config-files.md @@ -49,8 +49,6 @@ The following settings can be configured at the root level of your config.yaml f | `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 | -| `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 (higher = stricter) | Float between 0.01 and 1.0 | 0.8 | No | | `SECURITY_PROMPT_CLASSIFIER_ENABLED` | Enable ML-based prompt injection detection for advanced threat identification | true/false | false | No | @@ -96,10 +94,6 @@ GOOSE_SEARCH_PATHS: - "~/custom/tools" - "/opt/homebrew/bin" -# Observability (OpenTelemetry) -OTEL_EXPORTER_OTLP_ENDPOINT: "http://localhost:4318" -OTEL_EXPORTER_OTLP_TIMEOUT: 20000 - # Security Configuration SECURITY_PROMPT_ENABLED: true @@ -155,6 +149,20 @@ GOOSE_SEARCH_PATHS: These paths are prepended to the system PATH when running extension commands, ensuring your custom tools are found without modifying your global PATH. +## Observability Configuration + +Configure goose to export telemetry to [OpenTelemetry](https://opentelemetry.io/docs/) compatible platforms. Environment variables override these settings and support additional options like per-signal configuration. See the [environment variables guide](/docs/guides/environment-variables#opentelemetry-protocol-otlp) for details. + +| Setting | 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 | + +```yaml +otel_exporter_otlp_endpoint: "http://localhost:4318" +otel_exporter_otlp_timeout: 20000 +``` + ## Recipe Command Configuration You can optionally set up [custom slash commands](/docs/guides/context-engineering/slash-commands) to run recipes that you create. List the command (without the leading `/`) along with the path to the recipe: diff --git a/documentation/docs/guides/environment-variables.md b/documentation/docs/guides/environment-variables.md index af01988955e7..a4205eebea77 100644 --- a/documentation/docs/guides/environment-variables.md +++ b/documentation/docs/guides/environment-variables.md @@ -438,29 +438,50 @@ export NO_PROXY="localhost,127.0.0.1,.internal" 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) +### Observability Configuration -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. +Configure goose to export telemetry to any [OpenTelemetry](https://opentelemetry.io/docs/) compatible platform. + +To enable export, set a collector endpoint: -| 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 -- 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 ``` +You can control each signal (traces, metrics, logs) independently with `OTEL_{SIGNAL}_EXPORTER`: + +| Variable pattern | Purpose | Values | +|---|---|---| +| `OTEL_EXPORTER_OTLP_ENDPOINT` | Base OTLP endpoint (applies `/v1/traces`, etc.) | URL | +| `OTEL_EXPORTER_OTLP_{SIGNAL}_ENDPOINT` | Override endpoint for a specific signal | URL | +| `OTEL_{SIGNAL}_EXPORTER` | Exporter type per signal | `otlp`, `console`, `none` | +| `OTEL_SDK_DISABLED` | Disable all OTel export | `true` | + +Additional variables like `OTEL_SERVICE_NAME`, `OTEL_RESOURCE_ATTRIBUTES`, +and `OTEL_EXPORTER_OTLP_TIMEOUT` are also supported. +See the [OTel environment variable spec][otel-env] for the full list. + +**Examples:** +```bash +# Export everything to a local collector +export OTEL_EXPORTER_OTLP_ENDPOINT="http://localhost:4318" + +# Export only traces, disable metrics and logs +export OTEL_TRACES_EXPORTER="otlp" +export OTEL_METRICS_EXPORTER="none" +export OTEL_LOGS_EXPORTER="none" +export OTEL_EXPORTER_OTLP_ENDPOINT="http://localhost:4318" + +# Debug traces to console (no collector needed) +export OTEL_TRACES_EXPORTER="console" + +# Sample 10% of traces (reduce volume in production) +export OTEL_TRACES_SAMPLER="parentbased_traceidratio" +export OTEL_TRACES_SAMPLER_ARG="0.1" +``` + +[otel-env]: https://opentelemetry.io/docs/specs/otel/configuration/sdk-environment-variables/ + ### Langfuse Integration These variables configure the [Langfuse integration for observability](/docs/tutorials/langfuse).