Telemetry¶
Envoy can export a record of every command it runs -- for your own
diagnostics, or aggregated fleet-wide into one shared, studio-hosted
Grafana dashboard. Disabled by default, and best-effort: a misconfigured
or unreachable destination is visible under --diagnose but never
affects a command's own behavior or exit code.
Enabling it¶
Set ENVOY_TELEMETRY_ENDPOINT -- either in your own shell/session, or
(more commonly) baked into your studio's own stack global_env.json so
it applies fleet-wide automatically:
- A value starting with
http://orhttps://selects direct OTLP/HTTP export to an always-on Collector. - Any other value (a UNC path, mapped drive, or mount point) selects file-drop export: each record is serialized as an OTLP-JSON payload and written atomically under that path -- no listening service required there.
- Standard
OTEL_EXPORTER_OTLP_TRACES_ENDPOINT/OTEL_EXPORTER_OTLP_ENDPOINTare honored as an endpoint fallback, used only whenENVOY_TELEMETRY_ENDPOINTitself is unset. OTEL_EXPORTER_OTLP_HEADERS/OTEL_EXPORTER_OTLP_TIMEOUT/OTEL_SERVICE_NAME/OTEL_RESOURCE_ATTRIBUTES, by contrast, always apply whenever they're set -- regardless of whetherENVOY_TELEMETRY_ENDPOINTor the endpoint fallback resolved the destination. In particular,OTEL_EXPORTER_OTLP_HEADERSis how a shared Collector bearer token reaches the exporter even whenENVOY_TELEMETRY_ENDPOINT(not anOTEL_*var) is what selected the destination.ENVOY_TELEMETRY_ENABLED=falsealways disables collection, regardless of any other setting -- your own opt-out always wins over a studio-wide default.
Resolution checks envoy-cli's own process environment first, then the selected stack's merged bundle environment -- so a personal override always beats a fleet-wide default.
Check the current state any time with envoy --diagnose (see the
CLI reference).
Per-run controls¶
Two flags apply regardless of how telemetry is otherwise configured:
--incognitodisables telemetry for that single invocation only, overridingENVOY_TELEMETRY_ENDPOINT/ENVOY_TELEMETRY_ENABLEDfor just that run -- nothing is even resolved or attempted, let alone sent.--tag TAGattaches a free-text tag (envoy.tag) to the invocation's record, if one is recorded. Useful for marking ad hoc or one-off runs (a specific test, an investigation) apart from routine usage in the shared dashboard. Has no effect when telemetry isn't enabled or is suppressed by--incognito. Applies uniformly across every kind of invocation envoy records -- built-ins like--list/--docsincluded, not just managed-command runs. Truncated to 200 characters (Unicode scalar values, not bytes) if longer -- silently capped rather than rejected, so an overlong tag can never fail an otherwise-successful command; this also keeps payload size bounded and avoids exceeding attribute-value limits some OTLP backends enforce.
What gets recorded¶
One envoy.command.run record per invocation -- built-ins (--list,
--diagnose, --which, --trace, --docs, config commands, help),
resolution failures, and the managed-command path all get their own
record, not just successful command runs. Each includes real start/end
timestamps (not just a duration attribute), stack/team/bundle context,
envoy version, a pseudonymous per-workstation installation ID (never a
username or hostname), the complete argv (both as originally typed and
alias-expanded), success/exit code, and which transport delivered it.
Redaction¶
Secret-looking values are redacted before a record is ever constructed -- nothing sensitive is written to disk or sent anywhere, in two independent, always-on layers (neither can be disabled by a bundle):
- Flag-name-based:
--token value,--api-key=value, and other sensitive-looking flag names (extend the built-in list viaENVOY_TELEMETRY_REDACT_ARGS). - Pattern-based: every value is also scanned regardless of which flag (if any) it followed -- JWT-shaped strings, bearer-token headers, embedded URL/connection-string credentials, and long high-entropy tokens. Tuned to leave ordinary long identifiers (bundle IDs, UUIDs, content hashes) alone.
Delivery resilience¶
If delivery fails (share unreachable, collector unreachable), the
already-redacted record is queued in a small local spool under
~/.envoy/telemetry/spool/ (bounded by both count and size, oldest-first
eviction) and retried -- one bounded, time-limited attempt per subsequent
invocation -- until it succeeds. A command is never blocked on network or
file I/O.
Version compatibility¶
The client (every workstation's envoy binary) and the shared server
bundle (Collector/Tempo/Grafana, in the separate
telemetry bundle) are
released and updated independently -- the client is expected to update far
more often than the server. This is safe by design:
- Record attributes are additive by default: an older Collector/Tempo/dashboard simply stores or ignores attributes it doesn't recognize, and a newer dashboard tolerates older clients missing newer attributes.
- The schema-version attribute (
envoy.schema_version, seeenvoy-core::telemetry::schema) is bumped only on a breaking change (an attribute rename, removal, or semantic change) -- never for additive changes.
| envoy release line | minimum telemetry-bundle schema version |
|---|---|
| current | 1 |
(Table intentionally starts at one row -- extend it if/when a future breaking change ships, on either side.)
The shared studio dashboard¶
Aggregating usage across every user's workstation into one dashboard is a
studio policy decision, not just a technical one -- confirm with whoever
owns employee-monitoring/privacy policy before a fleet-wide rollout. Once
approved, see the telemetry bundle's own
README for server setup,
authentication, retention, and a tour of the provisioned "Envoy Command
Telemetry" dashboard.