Documentation

Référence `vectron.toml`

Référence exhaustive du fichier principal de configuration Vectron, avec défauts et règles d'héritage.

Cette page est la référence normative de vectron.toml.

Quand un champ est optionnel, le tableau indique si son comportement vient:

d’une valeur par défaut fixe
d’un héritage depuis un champ parent
d’une règle runtime dérivée

Règles de résolution

Les chemins relatifs sont résolus depuis le dossier contenant vectron.toml.
Les champs de processus peuvent surcharger les champs globaux.
Certains champs ont une valeur effective par défaut au runtime même si le champ TOML est absent.
Au moins une entrée [[process]] doit exister pour que la configuration soit valide.

Sections de premier niveau

Champ	Type	Requis	Défaut / Héritage / Dérivation	Notes
`global`	table	Non	Table optionnelle	Défauts globaux appliqués aux processus
`process`	tableau de tables	Oui	Aucun	Au moins une entrée `[[process]]` est requise
`log_templates`	table	Non	Défaut: table vide	Presets de rendu nommés

`[global]`

Champ	Type	Requis	Défaut / Héritage / Dérivation	Notes
`log_dir`	chemin	Non	Défaut: `.vectron/logs`	Dossier des logs fichiers
`before`	string ou tableau de strings	Non	Défaut: aucun	Commande(s) de preflight exécutées avant le démarrage
`show_timestamps`	booléen	Non	Valeur effective par défaut: `true`	Hérite vers les processus
`log_mode`	enum	Non	Défaut: `console`	Valeurs: `console`, `files`, `both`
`log_format`	enum	Non	Défaut: `text`	Valeurs: `text`, `logfmt`, `json`, `json_pretty`
`lifecycle`	enum	Non	Défaut: `fail-fast`	Politique de lifecycle actuelle
`readiness`	table	Non	Défaut: aucun	Modèle de readiness global
`color`	couleur	Non	Défaut: aucun	Couleur par défaut des processus ; accepte des couleurs CSS-like comme `red` ou `#808080`
`log_template`	table	Non	Défaut: aucun	Binding par défaut d’un preset de rendu
`disable_color_env`	booléen	Non	Défaut: `false`	Désactive les variables ANSI des processus enfants
`disabled_groups`	tableau de strings	Non	Défaut: `[]`	Groupes désactivés sauf réactivation explicite
`disabled_labels`	tableau de strings	Non	Défaut: `[]`	Labels désactivés sauf réactivation explicite
`cleanup_logs`	booléen	Non	Défaut: `true`	Recrée `log_dir` au démarrage
`env`	map de strings	Non	Défaut: `{}`	Variables d’environnement de base
`env_file`	chemin	Non	Défaut: aucun	Charge après `global.env`
`instance_env_suffix`	string	Non	Défaut: aucun	Doit contenir `{index}`
`port_start`	entier	Non	Défaut: `5000`	Base d’allocation des ports ; alias legacy: `port_base`
`port_step`	entier	Non	Défaut: `100`	Ecart de ports entre processus
`formation_port_step`	entier	Non	Défaut: `1`	Ecart de ports entre instances
`shutdown_timeout_secs`	entier	Non	Défaut: `90`	Fenêtre d’arrêt gracieux avant escalation
`working_dir`	chemin	Non	Défaut: aucun	Comportement effectif: racine du workspace / de la config si absent
`tui`	table	Non	Défaut: table vide avec seuils par défaut	Réglages spécifiques à la TUI

`[global.readiness]`

Readiness basée sur les logs

Champ	Type	Requis	Défaut / Héritage / Dérivation	Notes
`type`	string	Oui	Valeur requise: `log`	Sélectionne la readiness par logs
`ready`	table	Non	Défaut: aucun	Motif de succès
`error`	table	Non	Défaut: aucun	Motif d’erreur
`ready.pattern`	string	Oui, si `ready` existe	Aucun	Motif regex
`ready.stream`	enum	Non	Défaut: `stdout`	Valeurs: `stdout`, `stderr`
`error.pattern`	string	Oui, si `error` existe	Aucun	Motif regex
`error.stream`	enum	Non	Défaut: `stdout`	Valeurs: `stdout`, `stderr`

Au moins un de ready ou error doit être présent.

Readiness TCP

Champ	Type	Requis	Défaut / Héritage / Dérivation	Notes
`type`	string	Oui	Valeur requise: `tcp`	Sélectionne la readiness TCP
`host`	string	Non	Défaut: `127.0.0.1`	Hôte de probe
`port`	string ou entier	Non	Défaut: `auto`	`auto` suit le port alloué à l’instance
`interval_ms`	entier	Non	Défaut: `500`	Intervalle de polling

`[global.log_template]`

Champ	Type	Requis	Défaut / Héritage / Dérivation	Notes
`preset`	string	Non	Défaut: aucun	Applique aux deux flux sauf surcharge
`stdout_preset`	string	Non	Défaut: aucun	Surcharge spécifique stdout
`stderr_preset`	string	Non	Défaut: aucun	Surcharge spécifique stderr

`[global.tui.metrics.thresholds]`

Champ	Type	Requis	Défaut / Héritage / Dérivation	Notes
`cpu_warn`	float	Non	Défaut: `60.0`	Seuil warning CPU par instance
`cpu_crit`	float	Non	Défaut: `85.0`	Seuil critique CPU par instance
`rss_warn`	bytes ou string IEC	Non	Défaut: `256MiB`	Seuil warning RSS par instance
`rss_crit`	bytes ou string IEC	Non	Défaut: `1GiB`	Seuil critique RSS par instance
`total_cpu_warn`	float	Non	Défaut: aucun ; dérivé si absent	Seuil total pour la barre de statut
`total_cpu_crit`	float	Non	Défaut: aucun ; dérivé si absent	Seuil total pour la barre de statut
`total_rss_warn`	bytes ou string IEC	Non	Défaut: aucun ; dérivé si absent	Seuil total pour la barre de statut
`total_rss_crit`	bytes ou string IEC	Non	Défaut: aucun ; dérivé si absent	Seuil total pour la barre de statut

Quand les seuils totaux sont absents, la TUI dérive les totaux à partir des seuils par instance.

`[[process]]`

Champ	Type	Requis	Défaut / Héritage / Dérivation	Notes
`name`	string	Oui	Aucun	Identifiant stable du processus
`command`	string	Oui	Aucun	Ligne de commande du processus enfant
`instances`	entier	Non	Défaut: `1`	Nombre de copies à lancer
`working_dir`	chemin	Non	Hérite de `global.working_dir` ; valeur effective par défaut: racine du workspace / de la config	Dossier de lancement
`log_mode`	enum	Non	Hérite de `global.log_mode` ; valeur effective par défaut: `console`	Valeurs: `console`, `files`, `both`
`log_format`	enum	Non	Hérite de `global.log_format` ; valeur effective par défaut: `text`	Valeurs: `text`, `logfmt`, `json`, `json_pretty`
`group`	string	Non	Défaut: aucun	Groupe unique utilisé par la TUI et les filtres de groupes
`labels`	tableau de strings	Non	Défaut: `[]`	Labels utilisés uniquement par les filtres de démarrage
`show_timestamps`	booléen	Non	Hérite de `global.show_timestamps` ; valeur effective par défaut: `true`	Affichage des timestamps en console/TUI
`lifecycle`	enum	Non	Hérite de `global.lifecycle` ; valeur effective par défaut: `fail-fast`	Politique de lifecycle
`readiness`	table	Non	Hérite de `global.readiness`	Surcharge de readiness par processus
`color`	couleur	Non	Défaut: aucun	Couleur du processus ; accepte des couleurs CSS-like comme `red` ou `#808080`
`instance_colors`	tableau de couleurs	Non	Défaut: `[]`	Couleurs CSS-like optionnelles par instance
`log_template`	table	Non	Hérite de `global.log_template`	Surcharge de preset de rendu
`disable_color_env`	booléen	Non	Hérite de `global.disable_color_env` ; valeur effective par défaut: `false`	Surcharge du comportement ANSI enfant
`env`	map de strings	Non	Défaut: `{}`	Variables d’environnement du processus
`env_file`	chemin	Non	Défaut: aucun	Charge après l’env du processus
`instance_env_suffix`	string	Non	Hérite de `global.instance_env_suffix`	Doit contenir `{index}`
`port_env`	string	Non	Défaut du champ: aucun ; variable effective: `PORT`	Surcharge la variable d’environnement qui reçoit le port alloué
`port_start`	entier	Non	Dérivé du curseur courant d’allocation	Pas de valeur constante fixe
`port_step`	entier	Non	Hérite de `global.port_step` ; valeur effective par défaut: `100`	Écart de ports pour ce processus
`formation_port_step`	entier	Non	Hérite de `global.formation_port_step` ; valeur effective par défaut: `1`	Écart pour la prochaine base d’allocation
`log_dir`	chemin	Non	Hérite de `global.log_dir`	Dossier de logs fichiers du processus
`tui.metrics.thresholds.cpu_warn`	float	Non	Hérite du seuil global ; valeur effective par défaut: `60.0`	Surcharge par processus
`tui.metrics.thresholds.cpu_crit`	float	Non	Hérite du seuil global ; valeur effective par défaut: `85.0`	Surcharge par processus
`tui.metrics.thresholds.rss_warn`	bytes ou string IEC	Non	Hérite du seuil global ; valeur effective par défaut: `256MiB`	Surcharge par processus
`tui.metrics.thresholds.rss_crit`	bytes ou string IEC	Non	Hérite du seuil global ; valeur effective par défaut: `1GiB`	Surcharge par processus

`[log_templates.<name>]`

Champ	Type	Requis	Défaut / Héritage / Dérivation	Notes
`extends`	string	Non	Défaut: aucun	Hérite d’un autre preset
`fields`	table	Non	Défaut: aucun	Layout commun stdout et stderr
`stdout_fields`	table	Non	Défaut: aucun	Layout spécifique stdout
`stderr_fields`	table	Non	Défaut: aucun	Layout spécifique stderr

`[log_templates.<name>.*_fields]`

Champ	Type	Requis	Défaut / Héritage / Dérivation	Notes
`separator`	string	Non	Valeur effective par défaut: `" "`	Insère entre les champs rendus
`missing`	string	Non	Défaut: aucun	Texte de remplacement pour les clés absentes
`fields`	tableau de tables	Non	Défaut: `[]`	Rendu dans l’ordre

`[[log_templates.<name>.*_fields.fields]]`

Champ	Type	Requis	Défaut / Héritage / Dérivation	Notes
`key`	string	Oui	Aucun	Clé extraite
`prefix`	string	Non	Défaut: aucun	Ajoute avant la valeur
`suffix`	string	Non	Défaut: aucun	Ajoute après la valeur
`default`	string	Non	Défaut: aucun	Valeur fallback si la cle est absente
`map`	map de strings	Non	Défaut: `{}`	Remapping des valeurs
`format`	enum	Non	Valeur effective par défaut: `none`	Valeurs: `none`, `lowercase`, `uppercase`, `number`, `duration_ms`
`visible_if`	enum	Non	Valeur effective par défaut: `always`	Valeurs: `always`, `present`, `non_empty`
`color`	couleur	Non	Défaut: aucun	Couleur de la valeur
`color_rules`	tableau de tables	Non	Défaut: `[]`	Surcharges couleur basées sur regex

Les couleurs sont parsées comme des strings CSS-like. Exemples courants: couleurs nommées comme red et couleurs hex comme #808080 ou #112233.

`[[log_templates.<name>.*_fields.fields.color_rules]]`

Champ	Type	Requis	Défaut / Héritage / Dérivation	Notes
`regex`	string	Oui	Aucun	Regex matchée contre la valeur du champ
`color`	couleur	Oui	Aucun	Couleur CSS-like appliquée quand `regex` matche

Exemple:

[log_templates.api.fields]
fields = [
  { key = "level", color_rules = [
    { regex = "WARN|ERROR", color = "red" },
  ] },
]

Regles de validation

La validation inclut notamment:

au moins un processus
des commandes non vides
des noms, groupes et labels de processus valides
des labels valides pour disabled_groups et disabled_labels
des valeurs valides pour port_step et formation_port_step
l’absence de débordement dans l’allocation de ports
l’existence des env_file référencés
des configurations de readiness valides
des références de log templates valides
des instance_env_suffix valides contenant {index}

Source de vérité

Utilisez vectron.example.toml comme exemple complet et commenté de démarrage. Utilisez cette page quand vous avez besoin du comportement exact d’un champ.