Observagent
Agent integration · Windows · macOS · Linux

Connect Grok Build to Observagent.

Export Grok Build's session logs and metrics over OpenTelemetry, using its own external-OTEL environment variables or the [telemetry] block in ~/.grok/config.toml.

Select OS Review data sent
Grok BuildAgent session events
OTLP over HTTPSHTTP/protobuf
ObservagentLogs + metrics
How it works

Use Grok Build's external OpenTelemetry export

Grok Build is xAI's coding agent, used through its own CLI/TUI (the grok command), scripted headlessly, or embedded in other apps over the Agent Client Protocol. xAI does not publish an official Grok Build desktop app; the desktop GUIs you can find for it are community-built Electron or Tauri wrappers around that same local grok process, so this configuration applies underneath whichever front end launches it.

External OTEL export is a double opt-in, separate from Grok Build's own product-analytics telemetry toggle: set the master switch (GROK_EXTERNAL_OTEL, or otel_enabled under a [telemetry] table in config.toml) plus at least one exporter. Observagent accepts either the environment-variable path or the config-file path over OTLP/HTTP.

  • Grok Build currently ships metrics (token usage, turns, tool calls, errors, and startup timing) and structured log records; it does not export traces.
  • Use the http/protobuf OTLP protocol. gRPC is documented as supported but has been unreliable in some releases.
  • A fresh process briefly holds telemetry closed while it fetches fleet policy from xAI; the wait is bounded and export begins within about 30 seconds.
  • Grok Build is under active development; confirm the current [telemetry] schema and environment-variable names against xAI's documentation and the grok-build configuration reference before a wide rollout.
Before you begin

Minimum required plan

No subscription required with billed xAI API access.

  • Use an xAI API key with billing enabled for local or headless runs. Inference is charged through the API account.
  • For legacy subscription sign-in, the minimum is SuperGrok or X Premium+. We have not verified a minimum CLI subscription tier under The X Subscription.
Observagent accessPrepare an Observagent project with monitoring and the required signals enabled, plus a valid project key with telemetry:write permission.

Requirements reviewed on .

Select OS

Integration steps

Select a platform to see commands and paths for your computer. Project setup and delivery verification are shared across platforms.

WindowsPowerShell
  1. Step 1

    Create a project and project key

    In Observagent, enable Logs and Metrics on a project, turn monitoring on, and generate a project key with telemetry:write permission.

    • Use a separate key for Grok Build so Observagent can attribute this source reliably.
  2. Step 2

    Enable Grok Build's external OTEL export

    Set the master switch and at least one exporter in the shell that launches grok. The ingestion header always comes from OTEL_EXPORTER_OTLP_HEADERS.

    • GROK_EXTERNAL_OTEL (or otel_enabled) is a separate master switch from the product-analytics telemetry toggle; both it and at least one exporter must be set before anything exports.
    • http/protobuf is the reliable protocol; gRPC is documented as supported but has been unreliable in some releases.
    PowerShell
    $env:GROK_EXTERNAL_OTEL = "1"
$env:OTEL_METRICS_EXPORTER = "otlp"
$env:OTEL_LOGS_EXPORTER = "otlp"
$env:OTEL_EXPORTER_OTLP_PROTOCOL = "http/protobuf"
$env:OTEL_EXPORTER_OTLP_ENDPOINT = "https://dashboard.observagent.cloud"
$env:OTEL_EXPORTER_OTLP_HEADERS = "Authorization=Bearer YOUR_PROJECT_KEY"
  3. Step 3

    Or set the same keys in config.toml

    Every non-secret otel_* key can instead live under [telemetry] in ~/.grok/config.toml. You must still set OTEL_EXPORTER_OTLP_HEADERS in the environment that launches grok; the commented reminder below is not a TOML setting.

    • config.toml can hold every non-secret otel_* key, but the ingestion header always comes from OTEL_EXPORTER_OTLP_HEADERS in the environment, never from the file.
    • A requirements.toml or MDM policy can pin these keys for a fleet, overriding a value set in config.toml or the process environment.
    PowerShell
    [telemetry]
otel_enabled = true
otel_metrics_exporter = "otlp"
otel_logs_exporter = "otlp"
otel_endpoint = "https://dashboard.observagent.cloud"
otel_protocol = "http/protobuf"
otel_log_user_prompts = false
otel_log_assistant_responses = false
otel_log_tool_details = false
otel_log_tool_content = false

# Also required in the PowerShell environment that launches grok:
# $env:OTEL_EXPORTER_OTLP_HEADERS = "Authorization=Bearer YOUR_PROJECT_KEY"
  4. Step 4

    Start a new session and verify delivery

    Run a fresh grok session that completes at least one turn with a tool call, then check Logs and Metrics for the project in Observagent. Grok Build does not export traces.

    • Grok Build briefly holds telemetry closed at startup while it fetches fleet policy from xAI; the wait is bounded and export begins within about 30 seconds.
    • There is no official Grok Build desktop app; a community GUI wrapper works the same way as long as it launches grok from an environment or config.toml carrying these settings.
    • Grok Build currently exports metrics and log records only; there is no traces exporter, so leave that project signal aside for this connection.
Troubleshooting

Diagnose export failures

  • Nothing arrives: confirm both the master switch and at least one exporter are set (via environment variables or config.toml) in the exact environment that launches grok, and that the process was started fresh after the change.
  • 401/403 from Observagent: the bearer header is missing, malformed, revoked, or lacks telemetry:write. Remember the header only ever comes from OTEL_EXPORTER_OTLP_HEADERS, never from config.toml.
  • No traces appear: expected. Grok Build does not currently export traces; leave that project signal aside for this connection.
  • Only a startup event arrives: allow up to 30 seconds for the fleet-policy check to complete, and confirm the session actually reached a tool call or model turn.
  • Config keys not recognized: the [telemetry] and otel_* schema is representative; check the current grok-build configuration reference for the exact keys your installed version expects.
  • Prompt or response text appears in logs: explicitly set the content gates (otel_log_user_prompts, otel_log_assistant_responses, otel_log_tool_details, and otel_log_tool_content) to false.
Privacy

Review what gets exported

Treat Grok Build's external OTEL export as operational metrics and log telemetry, including turns, tool calls, errors, and timing, not a guaranteed prompt-free feed unless you explicitly disable the content gates listed above. The OTLP ingestion header is read only from the OTEL_EXPORTER_OTLP_HEADERS environment variable, so it is never written to config.toml alongside the rest of your settings. Review xAI's current documentation for exactly which fields Grok Build includes before enabling this for sessions that touch sensitive repositories or data. Observagent applies its own server-side content controls as an additional boundary.