Enregistrement

bext génère par défaut des journaux JSON structurés, avec des champs de suivi par requête, des niveaux configurables et une rotation intégrée. Chaque ligne de journal inclut suffisamment de contexte pour corréler les requêtes sur la pile sans instrumentation externe.

Configuration#

toml

# bext.config.toml
[logging]
level = "info"                   # trace | debug | info | warn | error
format = "json"                  # json | pretty (pretty is human-readable, for dev)
output = "stdout"                # stdout | file
file_path = "/var/log/bext/bext.log"
rotate = true                    # enable built-in log rotation
rotate_max_size_mb = 100         # rotate when file exceeds this size
rotate_max_files = 10            # keep this many rotated files
rotate_compress = true           # gzip rotated files

# Filter by module for targeted debugging
[logging.filters]
bext_server = "debug"            # server core at debug level
bext_core = "info"               # core library at info
bext_plugin = "warn"             # suppress noisy plugin logs
hyper = "warn"                   # quiet the HTTP transport layer

Vous pouvez également définir le niveau de journalisation via une variable d'environnement ou un indicateur CLI :

bash

# Environment variable (overrides config file)
BEXT_LOG_LEVEL=debug bext-server run

# CLI flag (overrides both)
bext-server --log-level trace run

Champs de journal structurés#

Chaque requête HTTP produit une entrée de journal structurée avec ces champs :

json

{
  "timestamp": "2026-04-03T14:22:01.847Z",
  "level": "INFO",
  "module": "bext_server::handler",
  "request_id": "01J5K8M2N3P4Q5R6S7T8",
  "method": "GET",
  "path": "/products/widget-pro",
  "status": 200,
  "duration_ms": 12.4,
  "bytes": 28430,
  "encoding": "br",
  "cache": "HIT",
  "tenant_id": "acme-corp",
  "remote_addr": "203.0.113.42",
  "user_agent": "Mozilla/5.0 ...",
  "referer": "https://acme.com/"
}

Champs principaux :

Champ	Description
`request_id`	ULID unique pour chaque demande. Transmis en aval via l'en-tête `X-Request-Id`.
`duration_ms`	Délai total entre la réception de la demande et l'achèvement du corps de la réponse.
`cache`	`HIT`, `MISS`, `STALE` (SWR) ou `BYPASS`.
`tenant_id`	Identifiant multi-tenant résolu à partir du nom d’hôte.
`encoding`	Compression de réponse : `br`, `gzip` ou `identity`.

Niveaux de journalisation#

Niveau	Utiliser
`trace`	Détails au niveau du fil : octets d'en-tête, acquisition/libération du pool V8, calcul de la clé de cache. Très verbeux.
`debug`	Décisions de routage des demandes, invocations de hooks de plugin, opérations de cache, timing de rendu SSR.
`info`	Lignes de journal de demande, démarrage/arrêt du serveur, émission de certificat TLS, événements de déploiement.
`warn`	Options de configuration obsolètes, rendus lents (> 500 ms), tentatives d'opérations, limites de débit proches.
`error`	Échecs SSR, paniques de plugin, erreurs TLS, échecs de connexion à la base de données.

Pour la production, info est recommandé. Passez à debug sur une seule instance lors de l’enquête sur les problèmes.

Transfert vers des systèmes externes#

Loki (Grafana)#

La sortie JSON de bext fonctionne avec Promtail dès la sortie de la boîte :

yaml

# promtail-config.yaml
scrape_configs:
  - job_name: bext
    static_configs:
      - targets: [localhost]
        labels:
          job: bext
          __path__: /var/log/bext/bext.log
    pipeline_stages:
      - json:
          expressions:
            level: level
            request_id: request_id
            status: status
            duration: duration_ms

Pile ELK (Elasticsearch + Logstash + Kibana)#

Dirigez la sortie standard vers Filebeat ou pointez Filebeat vers le fichier journal :

yaml

# filebeat.yml
filebeat.inputs:
  - type: log
    paths:
      - /var/log/bext/bext.log
    json.keys_under_root: true
    json.add_error_key: true

output.elasticsearch:
  hosts: ["https://es.internal:9200"]
  index: "bext-logs-%{+yyyy.MM.dd}"

Chien de données#

Utilisez la collecte de journaux de l'Agent Datadog avec l'analyse automatique JSON :

yaml

# /etc/datadog-agent/conf.d/bext.d/conf.yaml
logs:
  - type: file
    path: /var/log/bext/bext.log
    service: bext
    source: bext
    sourcecategory: web

Docker et sortie standard#

Lors de l'exécution dans Docker, conservez output = "stdout" et laissez le runtime du conteneur gérer la collecte des journaux. Docker capture la sortie standard au format JSON par défaut avec les pilotes json-file ou journald :

bash

# View logs
docker logs -f bext-server

# Follow with jq for readable output
docker logs -f bext-server 2>&1 | jq .

Filtrage des modules bruyants#

Pendant le développement, vous souhaiterez peut-être désactiver les journaux de transport HTTP ou de prise de contact TLS :

bash

BEXT_LOG_LEVEL="info,hyper=warn,rustls=warn,h2=warn" bext-server run

La syntaxe du filtre suit le format RUST_LOG : level définit la valeur par défaut et module=level remplace des modules spécifiques.

Conseil

En production, info est le niveau recommandé. Le niveau trace enregistre les détails au niveau du fil, y compris l'acquisition/la libération du pool V8 et le calcul de la clé de cache - utile pour le débogage approfondi mais très détaillé ; à éviter en production sous charge.

En rapport#

Surveillance — Métriques Prometheus, point de terminaison d’intégrité et règles d’alerte
Dépannage — commandes de diagnostic et correctifs par zone
Performance — cadre budgétaire et porte de régression
Codes d'erreur — Des codes E_ structurés sont apparus dans la sortie du journal
Configuration : variables d'environnement — BEXT_LOG_LEVEL et autres remplacements d'environnement
Configuration : bext.config.toml — référence complète de la section [logging]