Skip to content

docs(telemetry): align config and docs semantics for target, outfile, and CLI flags #4066

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
wenshao merged 3 commits into from
May 13, 2026
Merged

docs(telemetry): align config and docs semantics for target, outfile, and CLI flags #4066

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
aa1e8dd
docs(telemetry): align config and docs semantics for target, outfile,…
doudouOUC May 11, 2026
80425ba
docs(telemetry): address Copilot review comments on outfile and targe…
doudouOUC May 12, 2026
ddb5e8e
docs(telemetry): update QWEN_TELEMETRY_TARGET env var description and…
doudouOUC May 12, 2026
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
36 changes: 18 additions & 18 deletions docs/developers/development/telemetry.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -51,25 +51,21 @@ observability framework — Qwen Code's observability system provides:

## Configuration

> [!note]
>
> **⚠️ Special Note: This feature requires corresponding code changes. This documentation is provided in advance; please refer to future code updates for actual functionality.**

All telemetry behavior is controlled through your `.qwen/settings.json` file.
These settings can be overridden by environment variables or CLI flags.

| Setting | Environment Variable | CLI Flag | Description | Values | Default |
| -------------------------------- | -------------------------------------------------- | -------------------------------------------------------- | -------------------------------------------------------- | ----------------- | ----------------------- |
| `enabled` | `QWEN_TELEMETRY_ENABLED` | `--telemetry` / `--no-telemetry` | Enable or disable telemetry | `true`/`false` | `false` |
| `target` | `QWEN_TELEMETRY_TARGET` | `--telemetry-target <local\|gcp>` | Where to send telemetry data | `"gcp"`/`"local"` | `"local"` |
| `otlpEndpoint` | `QWEN_TELEMETRY_OTLP_ENDPOINT` | `--telemetry-otlp-endpoint <URL>` | OTLP collector endpoint | URL string | `http://localhost:4317` |
| `otlpProtocol` | `QWEN_TELEMETRY_OTLP_PROTOCOL` | `--telemetry-otlp-protocol <grpc\|http>` | OTLP transport protocol | `"grpc"`/`"http"` | `"grpc"` |
| `otlpTracesEndpoint` | `QWEN_TELEMETRY_OTLP_TRACES_ENDPOINT` | - | Per-signal endpoint override for traces (HTTP only) | URL string | - |
| `otlpLogsEndpoint` | `QWEN_TELEMETRY_OTLP_LOGS_ENDPOINT` | - | Per-signal endpoint override for logs (HTTP only) | URL string | - |
| `otlpMetricsEndpoint` | `QWEN_TELEMETRY_OTLP_METRICS_ENDPOINT` | - | Per-signal endpoint override for metrics (HTTP only) | URL string | - |
| `outfile` | `QWEN_TELEMETRY_OUTFILE` | `--telemetry-outfile <path>` | Save telemetry to file (overrides `otlpEndpoint`) | file path | - |
| `logPrompts` | `QWEN_TELEMETRY_LOG_PROMPTS` | `--telemetry-log-prompts` / `--no-telemetry-log-prompts` | Include prompts in telemetry logs | `true`/`false` | `true` |
| `includeSensitiveSpanAttributes` | `QWEN_TELEMETRY_INCLUDE_SENSITIVE_SPAN_ATTRIBUTES` | - | Include sensitive attributes in log-to-span bridge spans | `true`/`false` | `false` |
| Setting | Environment Variable | CLI Flag | Description | Values | Default |
| -------------------------------- | -------------------------------------------------- | -------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ | ----------------- | ----------------------- |
| `enabled` | `QWEN_TELEMETRY_ENABLED` | `--telemetry` / `--no-telemetry` | Enable or disable telemetry | `true`/`false` | `false` |
Comment thread
doudouOUC marked this conversation as resolved.
| `target` | `QWEN_TELEMETRY_TARGET` | `--telemetry-target <local\|gcp>` _(deprecated)_ | Informational destination label; does not control exporter routing — set `otlpEndpoint` or `outfile` to configure where data is sent | `"gcp"`/`"local"` | `"local"` |
Comment thread
doudouOUC marked this conversation as resolved.
| `otlpEndpoint` | `QWEN_TELEMETRY_OTLP_ENDPOINT` | `--telemetry-otlp-endpoint <URL>` | OTLP collector endpoint | URL string | `http://localhost:4317` |
Comment thread
doudouOUC marked this conversation as resolved.
Comment thread
doudouOUC marked this conversation as resolved.
| `otlpProtocol` | `QWEN_TELEMETRY_OTLP_PROTOCOL` | `--telemetry-otlp-protocol <grpc\|http>` | OTLP transport protocol | `"grpc"`/`"http"` | `"grpc"` |
| `otlpTracesEndpoint` | `QWEN_TELEMETRY_OTLP_TRACES_ENDPOINT` | - | Per-signal endpoint override for traces (HTTP only) | URL string | - |
| `otlpLogsEndpoint` | `QWEN_TELEMETRY_OTLP_LOGS_ENDPOINT` | - | Per-signal endpoint override for logs (HTTP only) | URL string | - |
| `otlpMetricsEndpoint` | `QWEN_TELEMETRY_OTLP_METRICS_ENDPOINT` | - | Per-signal endpoint override for metrics (HTTP only) | URL string | - |
| `outfile` | `QWEN_TELEMETRY_OUTFILE` | `--telemetry-outfile <path>` | Save telemetry to file (overrides OTLP export) | file path | - |
| `logPrompts` | `QWEN_TELEMETRY_LOG_PROMPTS` | `--telemetry-log-prompts` / `--no-telemetry-log-prompts` | Include prompts in telemetry logs | `true`/`false` | `true` |
| `includeSensitiveSpanAttributes` | `QWEN_TELEMETRY_INCLUDE_SENSITIVE_SPAN_ATTRIBUTES` | - | Include sensitive attributes in log-to-span bridge spans | `true`/`false` | `false` |

**Note on boolean environment variables:** For the boolean settings (`enabled`,
`logPrompts`, `includeSensitiveSpanAttributes`), setting the
Expand Down Expand Up @@ -187,16 +183,20 @@ For local development and debugging, you can capture telemetry data locally:
### File-based Output (Recommended)

1. Enable telemetry in your `.qwen/settings.json`:

```json
{
"telemetry": {
"enabled": true,
"target": "local",
"otlpEndpoint": "",
"outfile": ".qwen/telemetry.log"
Comment thread
doudouOUC marked this conversation as resolved.
}
}
```

> **Note:** When `outfile` is set, OTLP export is automatically disabled.

@wenshao wenshao May 13, 2026

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

[Suggestion] The Note explains the outfile vs OTLP semantics for users reading settings.json, but skips the override path that produces the most painful silent failure: env vars and CLI flags also feed outfile resolution.

Looking at packages/core/src/telemetry/config.ts:109-110:

const outfile =
  argv.telemetryOutfile ?? env['QWEN_TELEMETRY_OUTFILE'] ?? settings.outfile;

Two concrete scenarios this Note doesn't help with:

  1. Shadowed settings.json. A user has QWEN_TELEMETRY_OUTFILE=/old/path.log in their shell rc from a previous experiment. They follow this example, write "outfile": ".qwen/telemetry.log" to settings.json, see nothing in .qwen/telemetry.log, and have no hint to check env | grep QWEN_TELEMETRY_OUTFILE. The new minimal example actively reduces the surface area in settings.json that would prompt them to look.
  2. OTEL_EXPORTER_OTLP_ENDPOINT re-route. The standard OTel env var is read as a fallback at config.ts:79, but the env-var table in this doc doesn't list it (only the per-signal OTEL_* variants get a passing reference at lines 93-100). A user who omits otlpEndpoint per this Note, with OTEL_EXPORTER_OTLP_ENDPOINT set system-wide, is still safe today (the !telemetryOutfile gate at sdk.ts:171 holds), but they don't know that's their last line of defense.
Suggested change
> **Note:** When `outfile` is set, OTLP export is automatically disabled.
> **Note:** When `outfile` is set, OTLP export is automatically disabled.
> The `target` and `otlpEndpoint` settings are not needed for file-only
> output and can be safely omitted from your config. `QWEN_TELEMETRY_OUTFILE`
> and `--telemetry-outfile` take precedence over `settings.json` — if
> telemetry doesn't appear in the expected file, check those overrides
> first.

— claude-opus-4-7[1m] via Qwen Code /qreview

> The `target` and `otlpEndpoint` settings are not needed for file-only
> output and can be safely omitted from your config.

2. Run Qwen Code and send prompts.
3. View logs and metrics in the specified file (e.g., `.qwen/telemetry.log`).

Expand Down
Loading
Loading