API de télémétrie : requêtes, réponses et codes d’erreur

L’API de télémétrie échange du JSON en HTTP sur https://api.logbrew.co. Les SDK publics envoient leurs lots gérés à POST /v1/events. Les clients natifs personnalisés envoient des enveloppes natives à POST /api/telemetry/ingest. Les deux routes d’ingestion exigent un jeton bearer d’ingestion limité au projet. Les lectures et les modifications qui appartiennent au compte utilisent un jeton bearer de compte. N’utilisez jamais un jeton bearer de compte ni une session de navigateur comme configuration du SDK ou de l’ingestion. N’envoyez jamais un jeton bearer d’ingestion à une route de lecture.

Envoyer une requête bien délimitée

Suivez cette liste avant qu’un client envoie une requête :

Choisissez la route et la méthode HTTP dans le tableau des points de terminaison.
Utilisez le bon jeton bearer : un jeton bearer d’ingestion pour l’ingestion, un jeton bearer de compte pour tout le reste.
Sélectionnez le périmètre de projet que la route prend en charge. N’élargissez pas le périmètre après une réponse vide.
N’ajoutez que les paramètres de requête que la route accepte. Consultez Filtres de requête.
Envoyez Content-Type: application/json quand la route a un corps JSON.
Lisez le statut HTTP et le corps de la réponse avant de réessayer.
Gardez les jetons bearer, les tickets de flux et les corps de réponse complets hors des logs et des prompts des agents.

Points de terminaison

Ingestion

Méthode	Chemin	Rôle
`POST`	`/v1/events`	Ingérer les lots que les SDK LogBrew publics construisent et envoient.
`POST`	`/api/telemetry/ingest`	Ingérer les enveloppes de télémétrie natives d’un client personnalisé.

Laissez le SDK construire les lots /v1/events. Ne les construisez pas à la main. Pour l’enveloppe native, consultez Intégration du SDK.

Lectures de télémétrie

Méthode	Chemin	Rôle
`GET`	`/api/logs`	Lister les logs structurés.
`GET`	`/api/logs/{log_id}`	Lire un log.
`GET`	`/api/logs/attributes`	Lister les chemins et les types d’attributs de logs qu’un filtre peut rechercher.
`GET`	`/api/telemetry/issues`	Lister les problèmes groupés.
`GET`	`/api/telemetry/issues/{issue_id}`	Lire un problème groupé.
`GET`	`/api/telemetry/issues/{issue_id}/events`	Lister les occurrences d’un problème groupé.
`PATCH`	`/api/telemetry/issues/{issue_id}`	Mettre à jour le statut, la priorité ou le responsable d’un problème.
`POST`	`/api/telemetry/issues/bulk`	Mettre à jour le statut, la priorité ou le responsable de 1 à 100 problèmes d’un projet.
`GET`	`/api/telemetry/issues/assignees`	Lister les comptes et les équipes auxquels des problèmes peuvent être attribués dans un projet.
`GET`	`/api/telemetry/issues/{issue_id}/owners`	Lister les propriétaires suggérés d’un problème.
`GET`, `PUT`	`/api/telemetry/issues/ownership`	Lire ou définir les règles de propriété et le texte CODEOWNERS d’un projet.
`GET`	`/api/telemetry/issues/{issue_id}/activity`	Lire l’historique des changements d’un problème.
`GET`	`/api/telemetry/issues/notifications`	Lister les problèmes que d’autres personnes vous ont attribués, à vous ou à vos équipes.
`POST`	`/api/telemetry/issues/notifications/read`	Marquer vos notifications de problèmes comme lues.
`PUT`	`/api/telemetry/issues/{issue_id}/triage-rule`	Définir la règle de gravité d’un problème.
`PUT`	`/api/logs/{log_id}/triage-rule`	Définir la règle de gravité et l’état ignoré des logs qui correspondent à un log.
`GET`	`/api/telemetry/traces`	Découvrir les traces dans le périmètre d’un projet.
`GET`	`/api/telemetry/traces/{trace_id}`	Lister les spans d’une trace.
`GET`	`/api/telemetry/traces/{trace_id}/summary`	Lire un résumé limité d’une trace.
`GET`	`/api/telemetry/actions`	Lister les actions produit.
`GET`	`/api/telemetry/metrics`	Lister les échantillons de métriques.
`GET`	`/api/telemetry/metrics/series`	Lire une métrique par intervalles de temps.
`GET`	`/api/telemetry/releases`	Lister les résumés de versions.
`GET`	`/api/telemetry/summary/volume`	Lire le nombre de signaux d’un projet par intervalles de temps.

Déploiements

Méthode	Chemin	Commande CLI
`PUT`	`/api/telemetry/deployments/{deployment_id}`	`logbrew deploy`
`GET`	`/api/telemetry/deployments/{deployment_id}?project_id=<project-uuid>`	Aucune
`GET`	`/api/telemetry/deployments?project_id=<project-uuid>`	Aucune

Enregistrez un déploiement depuis votre automatisation de livraison, après sa réussite ou son échec. Le corps de PUT contient project_id, release, environment, service_name, status (succeeded ou failed), started_at, finished_at et un commit_sha facultatif. Utilisez les mêmes valeurs de release, environment et service_name que votre SDK. Le compte doit posséder le projet. deployment_id est votre propre ID du déploiement. Une nouvelle tentative avec le même ID et le même corps renvoie le déploiement enregistré. Le même ID avec un corps différent échoue avec 409 et idempotency_conflict. Utilisez un nouvel ID pour un autre déploiement.

Investigations

Chaque route d’investigation renvoie un dossier de preuves borné sur un seul objet. La commande logbrew explain de la CLI lit ces routes et valide la réponse.

Méthode	Chemin	Commande CLI
`GET`	`/api/logs/{log_id}/investigation`	`logbrew explain log`
`GET`	`/api/telemetry/issues/{issue_id}/investigation`	`logbrew explain issue`
`GET`	`/api/telemetry/issues/{issue_id}/correction-verification`	`logbrew investigate issue <issue_id> verify`
`GET`	`/api/telemetry/traces/{trace_id}/investigation`	`logbrew explain trace`
`GET`	`/api/telemetry/traces/{trace_id}/spans/{span_id}/investigation`	`logbrew explain span`
`GET`	`/api/telemetry/actions/{action_id}/investigation`	`logbrew explain action`
`GET`	`/api/telemetry/metrics/investigation`	`logbrew explain metric`
`GET`	`/api/telemetry/releases/investigation`	`logbrew explain release`

Analyses produit

Méthode	Chemin	Commande CLI
`GET`	`/api/telemetry/analytics/overview`	`logbrew analytics overview`
`GET`	`/api/telemetry/analytics/properties`	`logbrew analytics properties`
`POST`	`/api/telemetry/analytics/funnel`	`logbrew analytics funnel`
`POST`	`/api/telemetry/analytics/retention`	`logbrew analytics retention`
`POST`	`/api/telemetry/analytics/lifecycle`	`logbrew analytics lifecycle`
`POST`	`/api/telemetry/analytics/paths`	`logbrew analytics paths`
`POST`	`/api/telemetry/analytics/segments/compare`	`logbrew analytics compare`

Les routes d’analyse POST acceptent un corps JSON, pas des paramètres de requête. Consultez Analyses produit.

Flux en direct

Méthode	Chemin	Rôle
`POST`	`/api/feed/ticket`	Créer un ticket de flux en direct de courte durée avec un jeton bearer de compte.
`GET`	`/api/feed/live?ticket=<ticket>`	Ouvrir une connexion WebSocket avec ce ticket.

Compte et connexion

Les routes d’utilisation, de quota, d’abonnement et de déconnexion se trouvent dans l’API de compte.

Codes de statut de succès

Opération	Statut de succès
Ingestion, lectures, mises à jour de problèmes, règles, déploiements, analyses et tickets de flux	`200 OK`
Connexion au flux en direct	`101 Switching Protocols`, puis des messages WebSocket

Une réponse 200 ne prouve pas que les preuves sont complètes. Lisez les champs de couverture, de troncature et de statut de la réponse.

Filtres de requête et pagination

Chaque route de lecture accepte ses propres paramètres de requête. Les alias pratiques comme project, trace et user ne sont pas des paramètres de requête. Par défaut, les routes de liste renvoient un tableau simple. Avec pagination=cursor, elles renvoient une enveloppe avec curseur. La liste des déploiements renvoie toujours un objet de page. Consultez Filtres de requête.

Réponses et erreurs

Formats de réponse montre un exemple pour chaque famille de réponses.
Erreurs de l’API liste les codes d’erreur et les actions de correction.

Lisez code avant le message destiné aux humains. Utilisez next_action pour le comportement du programme et next pour guider une personne. N’analysez pas le texte de error ni de next.

Mettre à jour les problèmes

Ces requêtes utilisent un jeton bearer de compte. Il est volontairement différent de LOGBREW_INGEST_BEARER. Le compte doit avoir l’autorisation de gérer les problèmes du projet concerné. Sinon, la requête échoue avec 403 et forbidden. La même autorisation couvre les modifications du statut, de la priorité et du responsable, ainsi que les règles des problèmes et des logs. Chaque requête définit un ou plusieurs de ces champs :

Champ	Valeurs
`status`	`unresolved`, `resolved` ou `archived`. `ignored` est un ancien nom de `archived`.
`priority`	`high`, `medium` ou `low`.
`assignee`	Un ID d’utilisateur, `me` pour le compte connecté, `team:<team_id>` pour une équipe, ou `none` pour retirer l’attribution.

Une requête sans aucun de ces champs échoue avec 422 et validation_failed. Un problème a au plus un responsable : un compte ou une équipe. Un compte doit pouvoir lire le projet, et une équipe doit appartenir à l’organisation du projet. Sinon, la requête échoue avec 422 et validation_failed, et LogBrew ne modifie rien. Pour obtenir les comptes que vous pouvez désigner, utilisez Lister les responsables. Toute autre valeur de assignee échoue aussi avec 422 et validation_failed. Une priorité que vous définissez reste fixe. Sans priorité définie à la main, la priorité suit la gravité du problème : error et critical donnent high, warning donne medium et info donne low. Un champ qui a déjà la valeur demandée ne change pas. Vous pouvez renvoyer la même requête après un délai d’attente dépassé. Un délai dépassé ne prouve pas que la modification n’a pas eu lieu. Relisez le problème avant d’envoyer une modification différente.

Mettre à jour un problème

Ajoutez response_version=4 pour obtenir archived, la priorité et le responsable dans la réponse. En version 4, assignee vaut { "type": "user", "user_id", "name", "email" }, { "type": "team", "team_id", "slug", "name" } ou null. La version 3 affiche une équipe responsable comme null.

curl -X PATCH "$LOGBREW_API_URL/api/telemetry/issues/$ISSUE_ID?response_version=4" \
  -H "Authorization: Bearer $LOGBREW_ACCOUNT_BEARER" \
  -H "Content-Type: application/json" \
  --data '{ "status": "archived", "priority": "low", "assignee": "me" }'

La réponse est le problème mis à jour. Consultez les exemples de réponses de statut de problème.

Mettre à jour des problèmes en masse

Envoyez project_id et 1 à 100 ID de problèmes différents de ce projet :

curl -X POST "$LOGBREW_API_URL/api/telemetry/issues/bulk" \
  -H "Authorization: Bearer $LOGBREW_ACCOUNT_BEARER" \
  -H "Content-Type: application/json" \
  --data '{
    "project_id": "<project-uuid>",
    "issue_ids": ["<issue-uuid-1>", "<issue-uuid-2>"],
    "assignee": "<user-uuid>"
  }'

La requête applique la même modification à chaque problème. La réponse contient project_id et results, avec un résultat par ID de problème, dans l’ordre de la requête. Chaque résultat contient issue_id, outcome et issue. issue est le problème actuel dans la version 3 de la réponse, ou null pour not_found. Ajoutez "response_version": 2 au corps de la requête pour obtenir chaque problème dans la version 4 de la réponse.

`outcome`	Signification
`updated`	LogBrew a appliqué la modification.
`unchanged`	Le problème avait déjà les valeurs demandées.
`not_found`	Le projet n’a aucun problème avec cet ID. LogBrew n’a rien modifié pour lui.

Une liste vide, plus de 100 ID ou un ID répété échouent avec 422 et validation_failed. Répartissez un ensemble plus grand sur plusieurs requêtes. Si le compte ne peut pas lire le projet, la requête échoue avec 404 et not_found.

Lister les responsables

Envoyez l’ID du projet pour obtenir tous les comptes auxquels des problèmes peuvent être attribués dans ce projet :

curl "$LOGBREW_API_URL/api/telemetry/issues/assignees?project_id=$PROJECT_ID" \
  -H "Authorization: Bearer $LOGBREW_ACCOUNT_BEARER"

La liste contient tous les comptes qui peuvent lire le projet. Chaque entrée contient user_id, name et email. name vaut null quand le compte n’a pas de nom. Ajoutez response_version=2 pour obtenir aussi teams : toutes les équipes de l’organisation du projet, avec team_id, slug et name. Consultez la réponse de la liste des responsables. Tout compte qui peut lire le projet peut obtenir cette liste. Si le compte ne peut pas lire le projet, la requête échoue avec 404 et not_found. Quand un membre perd l’accès au projet, les problèmes qui lui sont attribués n’affichent plus de responsable. Si le membre retrouve l’accès, les problèmes l’affichent de nouveau, sauf si quelqu’un a modifié ou retiré le responsable entre-temps.

Propriété et propriétaires suggérés

GET /api/telemetry/issues/ownership?project_id=<project-uuid> renvoie rules, codeowners, updated_at et unresolved_owners. Tout compte qui peut lire le projet peut le lire. PUT avec project_id et rules, codeowners ou les deux remplace ce texte et demande l’autorisation de gérer les problèmes. Un champ absent garde son texte, et une chaîne vide l’efface. Chaque texte fait 128 Kio au plus. Un texte non valide échoue avec 422 et indique la ligne en cause. GET /api/telemetry/issues/{issue_id}/owners?response_version=2 renvoie suggested_assignee, owners et inputs. Chaque propriétaire a un type (user ou team), une source (ownership_rule, codeowners ou recent_activity), ainsi que rule, line et matched. La version 1, par défaut, ne liste que des comptes.

Historique d’un problème

GET /api/telemetry/issues/{issue_id}/activity?response_version=2 renvoie activity, du plus récent au plus ancien, et next_cursor. Chaque entrée contient type (status, priority, assigned, unassigned, severity_rule ou first_seen), value, actor_id, actor, assignee_id, assignee, team et at. limit va de 1 à 200, avec 50 par défaut. Envoyez cursor_time et cursor_id issus de next_cursor pour la page suivante.

Notifications

GET /api/telemetry/issues/notifications renvoie notifications, unread, read_at et next_cursor. Chaque notification est l’attribution d’un problème, à vous ou à votre équipe, par un autre compte. POST /api/telemetry/issues/notifications/read avec un objet JSON vide, ou avec read_at, déplace votre marque de lecture. La marque ne recule jamais.

Définir des règles pour les problèmes et les logs

Une règle change la façon dont LogBrew affiche les signaux correspondants. Elle ne supprime pas de données. La severity capturée reste inchangée, et la réponse affiche la règle dans triage.

Requête	Corps JSON
`PUT /api/telemetry/issues/{issue_id}/triage-rule`	`{ "severity": "<value>" }`
`PUT /api/logs/{log_id}/triage-rule`	`{ "severity": "<value>", "ignored": true }`

severity vaut info, warning, error, critical ou source. source annule le remplacement et affiche de nouveau la gravité capturée. Pour une règle de log, ignored: true masque les logs correspondants dans la liste de logs par défaut. Lisez-les avec status=ignored ou status=all. La règle s’applique aux signaux correspondants déjà conservés et futurs. Une autre valeur échoue avec 422 et validation_failed.

N’envoyez pas de versions vides. LogBrew les refuse pour que le suivi des versions reste fiable.

​Envoyer une requête bien délimitée

​Points de terminaison

​Ingestion

​Lectures de télémétrie

​Déploiements

​Investigations

​Analyses produit

​Flux en direct

​Compte et connexion

​Codes de statut de succès

​Filtres de requête et pagination

​Réponses et erreurs

​Mettre à jour les problèmes

​Mettre à jour un problème

​Mettre à jour des problèmes en masse

​Lister les responsables

​Propriété et propriétaires suggérés

​Historique d’un problème

​Notifications

​Définir des règles pour les problèmes et les logs

Envoyer une requête bien délimitée

Points de terminaison

Ingestion

Lectures de télémétrie

Déploiements

Investigations

Analyses produit

Flux en direct

Compte et connexion

Codes de statut de succès

Filtres de requête et pagination

Réponses et erreurs

Mettre à jour les problèmes

Mettre à jour un problème

Mettre à jour des problèmes en masse

Lister les responsables

Propriété et propriétaires suggérés

Historique d’un problème

Notifications

Définir des règles pour les problèmes et les logs