Observagent
Intégration d'agent · Windows · macOS · Linux

Connectez Grok Build à Observagent.

Exportez les journaux et métriques de session de Grok Build via OpenTelemetry, en utilisant ses propres variables d'environnement OTEL externes ou le bloc [telemetry] de ~/.grok/config.toml.

Choisir le système Voir les données envoyées
Grok BuildÉvénements de session de l'agent
OTLP via HTTPSHTTP/protobuf
ObservagentJournaux + métriques
Comment ça marche

Utiliser l'export OpenTelemetry externe de Grok Build

Grok Build est l'agent de codage de xAI, utilisé via son propre CLI/TUI (la commande grok), scripté sans interface, ou intégré dans d'autres applications via l'Agent Client Protocol. xAI ne publie pas d'application de bureau officielle pour Grok Build ; les interfaces de bureau que vous pouvez trouver sont des enveloppes communautaires Electron ou Tauri autour de ce même processus local grok, si bien que cette configuration s'applique quelle que soit l'interface qui le lance.

L'export OTEL externe est un double opt-in, distinct du réglage de télémétrie produit propre à Grok Build : définissez l'interrupteur principal (GROK_EXTERNAL_OTEL, ou otel_enabled sous une table [telemetry] dans config.toml) ainsi qu'au moins un exportateur. Observagent accepte aussi bien le chemin par variables d'environnement que le chemin par fichier de configuration, via OTLP/HTTP.

  • Grok Build fournit actuellement des métriques (usage de jetons, tours, appels d'outils, erreurs et temps de démarrage) et des journaux structurés ; il n'exporte pas de traces.
  • Utilisez le protocole OTLP http/protobuf. gRPC est documenté comme pris en charge mais s'est montré instable dans certaines versions.
  • Un processus fraîchement démarré garde brièvement la télémétrie fermée le temps de récupérer la politique de flotte auprès de xAI ; l'attente est bornée et l'export démarre en environ 30 secondes.
  • Grok Build est en développement actif ; vérifiez le schéma [telemetry] actuel et les noms de variables d'environnement dans la documentation de xAI et la référence de configuration de grok-build avant un déploiement large.
Avant de commencer

Offre minimum requise

Aucun abonnement requis avec un accès API xAI facturé.

  • Utilisez une clé API xAI avec facturation activée pour les tâches locales ou sans interface. L’inférence est facturée au compte API.
  • Pour les anciens abonnements, le minimum est SuperGrok ou X Premium+. Nous n’avons pas vérifié l’abonnement CLI minimum dans The X Subscription.
Accès ObservagentPréparez un projet Observagent avec la surveillance et les signaux nécessaires activés, ainsi qu’une clé de projet valide avec la permission telemetry:write.

Conditions examinées le .

Choisir le système

Étapes d'intégration

Sélectionnez une plateforme pour voir les commandes et chemins propres à votre ordinateur. La configuration du projet et la vérification de la livraison sont communes à toutes les plateformes.

WindowsPowerShell
  1. Étape 1

    Créer un projet et une clé de projet

    Dans Observagent, activez Journaux et Métriques sur un projet, activez la surveillance et générez une clé de projet avec la permission telemetry:write.

    • Utilisez une clé distincte pour Grok Build afin que Observagent puisse attribuer cette source de manière fiable.
  2. Étape 2

    Activer l'export OTEL externe de Grok Build

    Définissez l'interrupteur principal et au moins un exportateur dans le shell qui lance grok. L'en-tête d'ingestion provient toujours de OTEL_EXPORTER_OTLP_HEADERS.

    • GROK_EXTERNAL_OTEL (ou otel_enabled) est un interrupteur principal distinct du réglage de télémétrie produit ; lui et au moins un exportateur doivent être définis avant toute exportation.
    • http/protobuf est le protocole fiable ; gRPC est documenté comme pris en charge mais s'est montré instable dans certaines versions.
    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. Étape 3

    Ou définissez les mêmes clés dans config.toml

    Chaque clé otel_* non secrète peut à la place vivre sous [telemetry] dans ~/.grok/config.toml. Vous devez toujours définir OTEL_EXPORTER_OTLP_HEADERS dans l'environnement qui lance grok ; le rappel commenté ci-dessous n'est pas un réglage TOML.

    • config.toml peut contenir chaque clé otel_* non secrète, mais l'en-tête d'ingestion provient toujours de OTEL_EXPORTER_OTLP_HEADERS dans l'environnement, jamais du fichier.
    • Une politique requirements.toml ou MDM peut fixer ces clés pour une flotte, en priorité sur une valeur définie dans config.toml ou l’environnement du processus.
    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

# Également requis dans l’environnement PowerShell qui lance grok :
# $env:OTEL_EXPORTER_OTLP_HEADERS = "Authorization=Bearer YOUR_PROJECT_KEY"
  4. Étape 4

    Démarrer une nouvelle session et vérifier la livraison

    Exécutez une nouvelle session grok qui termine au moins un tour avec un appel d'outil, puis vérifiez les journaux et métriques du projet dans Observagent. Grok Build n'exporte pas de traces.

    • Grok Build garde brièvement la télémétrie fermée au démarrage le temps de récupérer la politique de flotte auprès de xAI ; l’attente est bornée et l’export démarre en environ 30 secondes.
    • Il n'existe pas d'application de bureau officielle Grok Build ; une interface graphique communautaire fonctionne de la même façon tant qu'elle lance grok depuis un environnement ou un config.toml portant ces réglages.
    • Grok Build n'exporte actuellement que des métriques et des journaux ; il n'y a pas d'exportateur de traces, donc laissez ce signal de projet de côté pour cette connexion.
Dépannage

Diagnostiquer les échecs d'export

  • Rien n'arrive : confirmez que l'interrupteur principal et au moins un exportateur sont définis (via variables d'environnement ou config.toml) dans l'environnement exact qui lance grok, et que le processus a été redémarré après le changement.
  • 401/403 d'Observagent : l'en-tête bearer est manquant, malformé, révoqué, ou manque de telemetry:write. Rappel : cet en-tête ne provient jamais que de OTEL_EXPORTER_OTLP_HEADERS, jamais de config.toml.
  • Aucune trace n'apparaît : c'est normal. Grok Build n'exporte actuellement pas de traces ; laissez ce signal de projet de côté pour cette connexion.
  • Seul un événement de démarrage arrive : laissez jusqu'à 30 secondes pour que la vérification de la politique de flotte se termine, et confirmez que la session a bien atteint un appel d'outil ou un tour de modèle.
  • Clés de configuration non reconnues : le schéma [telemetry] et otel_* est représentatif ; vérifiez la référence de configuration actuelle de grok-build pour les clés exactes attendues par votre version installée.
  • Du texte d'invite ou de réponse apparaît dans les journaux : définissez explicitement les verrous de contenu (otel_log_user_prompts, otel_log_assistant_responses, otel_log_tool_details et otel_log_tool_content) sur false.
Confidentialité

Vérifier ce qui est exporté

Traitez l'export OTEL externe de Grok Build comme de la télémétrie opérationnelle de métriques et de journaux, notamment les tours, appels d'outils, erreurs et mesures de durée, pas comme un flux garanti sans invite, sauf si vous désactivez explicitement les verrous de contenu listés ci-dessus. L'en-tête d'ingestion OTLP n'est lu que depuis la variable d'environnement OTEL_EXPORTER_OTLP_HEADERS, il n'est donc jamais écrit dans config.toml avec le reste de vos réglages. Consultez la documentation actuelle de xAI pour savoir exactement quels champs Grok Build inclut avant d'activer ceci pour des sessions touchant des dépôts ou données sensibles. Observagent applique ses propres contrôles de contenu côté serveur comme limite supplémentaire.