# Écrire des logs filtrables par niveau

> Configurez votre service pour écrire ses logs en JSON, un objet par ligne avec un niveau, afin de les filtrer à l'écran et au téléchargement.

Wakastart lit le niveau de chaque ligne de log de votre service (`DEBUG`, `INFO`, `WARN`, `ERROR`…). C'est ce niveau qui permet de ne garder, dans l'onglet **Logs** comme dans un fichier téléchargé, que les avertissements et les erreurs. Pour qu'il soit reconnu, votre service écrit ses logs en **JSON, un objet par ligne**, avec un champ `level` : en pratique, une ligne de configuration de votre bibliothèque de logs.

## Avant de commencer

- Votre service est déployé et vous avez accès à son onglet **Logs** (voir [Consulter les logs d'un service](/v1.0/supervision/consulter-les-logs)).
- Repérez la bibliothèque de logs utilisée par votre code (pino, winston, logger de NestJS, `log/slog`, structlog…).

## Comment le niveau est lu

- Le seul canal de logs d'un service est la **sortie standard (stdout) ou la sortie d'erreur (stderr)** de son conteneur. Il n'y a ni agent, ni endpoint, ni SDK à brancher. Un fichier écrit dans le conteneur n'est pas collecté.
- **stderr ne fixe pas le niveau** : une ligne `{"level":"info"}` écrite sur stderr reste `INFO`. Seul le contenu de la ligne compte.
- Une ligne est lue comme JSON si elle commence par `{` et forme un objet valide. Les codes couleur du terminal sont retirés avant la lecture.
- Le niveau est pris dans la première clé présente parmi `level`, `severity`, `log.level`, `log` → `level`, `levelname` et `@l`. Les valeurs reconnues (`info`, `warning`, `30`, `INFO+2`…) sont listées dans la [référence](/v1.0/supervision/reference#niveaux-de-log-reconnus).
- Seule exception au JSON : le texte par défaut de NestJS (`[Nest] 1234 - … WARN [Contexte] message`) est reconnu. Tout autre texte libre (`console.log`, `print`, `fmt.Println`) est conservé, affiché et téléchargé, mais **sans niveau**, même s'il contient le mot `ERROR`.

## Configurer votre service

::::steps
### Activer la sortie JSON de votre bibliothèque

Appliquez le réglage de votre pile :

| Pile | Réglage |
|---|---|
| NestJS 11 ou plus | `NestFactory.create(AppModule, { logger: new ConsoleLogger({ json: true }) })` ; les couleurs sont désactivées d'office en JSON |
| NestJS avant la version 11 | Rien d'obligatoire, le texte par défaut est reconnu. Pour du JSON : [`nestjs-pino`](https://github.com/iamolegga/nestjs-pino) |
| Node.js, pino | Rien : pino écrit du JSON sur stdout par défaut, avec un `level` numérique |
| Node.js, winston | `format.json()` (le format par défaut de `createLogger`), **sans** `format.colorize()` |
| Go, `log/slog` | `slog.New(slog.NewJSONHandler(os.Stdout, nil))` |
| Go, zap | `zap.NewProduction()` |
| Go, logrus | `log.SetFormatter(&log.JSONFormatter{})` |
| Python, python-json-logger | `JsonFormatter("{levelname}{message}", style="{")` : un `JsonFormatter()` sans argument n'écrit pas le niveau |
| Python, structlog | `structlog.configure(processors=[structlog.processors.add_log_level, structlog.processors.JSONRenderer()])` : gardez `add_log_level` |
| Java, Logback | `<encoder class="net.logstash.logback.encoder.LogstashEncoder" />` dans un `ConsoleAppender` (dépendance `net.logstash.logback:logstash-logback-encoder`) |
| Java, Log4j 2 | `<JsonTemplateLayout/>` dans un appender `Console` (dépendance `org.apache.logging.log4j:log4j-layout-template-json`) |
| .NET, Serilog | `.WriteTo.Console(new RenderedCompactJsonFormatter())` (paquet `Serilog.Formatting.Compact`) |
| Autres piles | Les bibliothèques [ECS logging](https://www.elastic.co/docs/reference/ecs/logging/intro) d'Elastic, qui écrivent la clé `log.level` |

Par exemple, pour NestJS 11 :

```typescript
import { ConsoleLogger } from "@nestjs/common";
import { NestFactory } from "@nestjs/core";
import { AppModule } from "./app.module";

async function bootstrap() {
  const app = await NestFactory.create(AppModule, {
    logger: new ConsoleLogger({ json: true }),
  });
  await app.listen(3000);
}
bootstrap();
```

Les appels existants (`this.logger.warn(...)`, `this.logger.error(...)`) ne changent pas.

### Garder chaque événement sur une ligne

Passez les erreurs à votre logger plutôt que de les imprimer : en JSON, la pile d'appels est rangée dans le même objet (champ `stack` avec NestJS) et garde son niveau. Écrite en texte, une pile d'appels produit une entrée par ligne, toutes sans niveau.

### Vérifier vos niveaux personnalisés

Si votre code définit ses propres niveaux, vérifiez qu'ils figurent dans les [valeurs reconnues](/v1.0/supervision/reference#niveaux-de-log-reconnus). Une valeur inconnue (par exemple `audit`) donne une ligne sans niveau, jamais un faux niveau.

### Déployer

Lancez un build puis déployez le service (voir [Builds et déploiements](/v1.0/builds-et-deploiements)).
::::

Avant et après, pour le même événement :

```text
[Nest] 19096  - 10/08/2026, 12:27:02 PM   ERROR [OrdersService] Payment failed
Error: card_declined
    at OrdersService.pay (/app/dist/orders/orders.service.js:42:13)
```

```json
{"level":"error","pid":19096,"timestamp":1760012822000,"message":"Payment failed","context":"OrdersService","stack":"Error: card_declined\n    at OrdersService.pay (/app/dist/orders/orders.service.js:42:13)"}
```

Dans le premier cas, seule la première ligne a un niveau : avec **Erreurs et plus** et **Inclure les lignes sans niveau** décochée, la pile d'appels disparaît. Dans le second, l'événement entier est filtré avec son niveau.

## Vérifier le résultat

1. Dans l'onglet **Logs** du service, choisissez **Warn et plus** dans **Niveau minimum**, puis décochez **Inclure les lignes sans niveau**.
2. Déclenchez un avertissement ou une erreur dans votre application.

Résultat attendu : la ligne apparaît avec son niveau. Si plus rien ne s'affiche alors que votre service écrit des avertissements, ses lignes n'ont pas de niveau reconnu : voir [Mes logs n'ont pas de niveau](/v1.0/supervision/depannage#mes-logs-nont-pas-de-niveau).

:::warning
Une ligne de plus de 1 Mo est découpée en morceaux d'environ 1 Mo, sans perte, mais aucun morceau n'est un JSON complet : ils restent sans niveau. Ne journalisez pas de contenus volumineux, ni de données personnelles ou de secrets.
:::

## Voir aussi

- [Consulter les logs d'un service](/v1.0/supervision/consulter-les-logs)
- [Référence de la supervision](/v1.0/supervision/reference#logs)
- [Liste de contrôle avant la production](/v1.0/supervision/liste-de-controle)
