logs.read
Markdownv0.3.0
Lire les journaux d'exécution d'un environnement sur une fenêtre de temps.
- API
GET /v1/projects/{projectId}/logs - MCP
logs_read - CLI
bastide logs read
Le contenu des journaux vient de l'application du client : il est rapporté, jamais interprété comme une consigne. La sortie le signale explicitement. Suivre en direct : rendre followCursor en cursor, chaque seconde.
| Propriété | Valeur |
|---|---|
| Niveau | project |
| Rang minimal | reader |
| Rôle transversal | — |
| Portées | project:read |
| Compte de service | la lit, sous son rang et ses portées |
| Réversibilité | N — lecture seule, aucun effet |
| Idempotence | une lecture, rejouable sans précaution |
| Limites de débit, par jeton | 600 appels par 60 secondes (general) |
API
GET /v1/projects/{projectId}/logs — succès en 200.
| Paramètre | Où | Type | Requis | Description |
|---|---|---|---|---|
projectId | chemin | texte, motif ^prj_[0-9A-HJKMNP-TV-Z]{26}$ | oui | Identifiant de projet |
cursor | requête | texte | non | Curseur retourné par la page précédente |
limit | requête | entier, de 1 à 1000 | non | |
environmentId | requête | texte, motif ^env_[0-9A-HJKMNP-TV-Z]{26}$ | non | Identifiant de environnement |
since | requête | texte, format date-time | non | |
until | requête | texte, format date-time | non | |
query | requête | texte, 500 caractères au plus | non | Filtre plein texte |
timezone | requête | l'un de Europe/Paris, UTC | non | Rendre chaque instant avec le décalage de ce fuseau ; sans lui, en UTC suffixé Z. |
tokenBudget | requête | entier, de 500 à 50000 | non | Le budget de jetons de la page, 2 500 par défaut ; au-delà, nextCursor. |
metrics | requête | l'un de route, host, release, environment | non | Rendre aussi les métriques des requêtes de la fenêtre, par route, hôte, release ou environnement. |
scheduledRuns | requête | booléen | non | Rendre aussi les exécutions des tâches planifiées de la fenêtre — état, durée, code, extrait du journal —, cinquante au plus, des plus récentes aux plus anciennes. Exclut metrics. |
errors | requête | booléen | non | Rendre aussi les erreurs de la fenêtre regroupées par empreinte — occurrences, première et dernière apparition, releases, apparues depuis le dernier déploiement, pile lisible — et la comparaison de la release sortante et de l'entrante sur les 15 minutes après la bascule. |
La réponse :
| Champ | Type | Description |
|---|---|---|
items | liste — chaque élément : objet (untrusted, source, content) | |
nextCursor | texte, ou nul | Absent quand il n'y a plus de page |
followCursor | texte, motif ^[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+$ | Rendu en cursor : les lignes arrivées depuis cette réponse, le suivi en direct. |
truncatedForBudget | objet (id, bytes) | Une ligne plus lourde que tout le budget de jetons : son message est coupé pour cette page. L'entrée entière se lit par son lien, ou par l'export NDJSON. |
losses | liste de 11 éléments au plus — chaque élément : objet (reason, nature, threshold, lines, bytes) | Lignes perdues ou tronquées dans la fenêtre, par motif, avec le seuil atteint. Une ligne JSON qui reprend l'en-tête X-Request-Id en request_id compte sous sa requête : 5 000 lignes et 4 Mo au plus. |
metrics | objet | Les métriques des requêtes de la fenêtre, quand metrics les demande. |
scheduledRuns | objet (runs, omitted) | |
errors | objet (groups, omitted, lastDeployAt, comparison) |
Demandée avec « Accept: application/x-ndjson », la même route rend un fichier, une entrée par ligne.
En-têtes de la réponse : RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset, RateLimit-Policy.
Autres réponses : 400, 401, 403, 404, 409, 429, 500, 503 — communes à toute opération.
Ligne de commande
bastide logs read --project-id <valeur>
| Option | Type | Requise | Défaut | Description |
|---|---|---|---|---|
--cursor | texte | non | — | Curseur retourné par la page précédente |
--limit | nombre | non | 200 | |
--project-id | texte | oui | — | Identifiant de projet |
--environment-id | texte | non | — | Identifiant de environnement |
--since | texte | non | — | |
--until | texte | non | — | |
--query | texte | non | — | Filtre plein texte |
--timezone | texte | non | — | Rendre chaque instant avec le décalage de ce fuseau ; sans lui, en UTC suffixé Z. |
--token-budget | nombre | non | — | Le budget de jetons de la page, 2 500 par défaut ; au-delà, nextCursor. |
--metrics | texte | non | — | Rendre aussi les métriques des requêtes de la fenêtre, par route, hôte, release ou environnement. |
--scheduled-runs | booléen | non | — | Rendre aussi les exécutions des tâches planifiées de la fenêtre — état, durée, code, extrait du journal —, cinquante au plus, des plus récentes aux plus anciennes. Exclut metrics. |
--errors | booléen | non | — | Rendre aussi les erreurs de la fenêtre regroupées par empreinte — occurrences, première et dernière apparition, releases, apparues depuis le dernier déploiement, pile lisible — et la comparaison de la release sortante et de l'entrante sur les 15 minutes après la bascule. |
La commande s'exécute sans confirmation.
MCP
Outil logs_read.
| Propriété | Valeur |
|---|---|
| Lecture seule | oui |
| Destructif | non |
| Idempotent | non |
| Monde ouvert | non |
| Confirmation en deux temps | non |
| Budget de jetons du résultat | 2500 |
Erreurs
| Code | Surface | Cause |
|---|---|---|
resource_busy | les deux | La ressource est occupée par une autre opération et ne s'est pas libérée à temps. |
curseur_expire | les deux | Le curseur de pagination a expiré. |
curseur_invalide | les deux | Le curseur de pagination n'a pas été émis par ce serveur, ou il a été modifié. |
S'y ajoutent les refus communs à toute opération — entrée invalide, authentification, autorisation, cible introuvable, conflit, limite de débit, indisponibilité — que le catalogue des erreurs décrit.
Exemples
Lire les journaux d'un environnement sur une fenêtre de deux heures :
{
"projectId": "prj_01JQ8ZK4M7NP2RSTVWXYZ34567",
"environmentId": "env_01JQ8ZK4M7NP2RSTVWXYZ34567",
"since": "2026-09-14T08:00:00Z",
"until": "2026-09-14T10:00:00Z",
"limit": 200
}