La Forge - observabilité

Gérer ses erreurs en Rust

2022-08-11T00:00:00+00:00

Bonjour à toutes et tous 😀

Les erreurs en Rust sont un vaste sujet.

Au fur et à mesure que l’application se complexifie, la gestion des erreurs devient cruciale.

Le problème est que chaque bibliothèque expose son propre système d’erreurs.

Si votre projet utilise un certain nombre de bibiliothèques, vous pouvez vous trouver dans la situation où vous devez réaliser des adaptations de code pour permettre aux erreurs d’être compatibles entre-elles.

Avant de se plonger dans la crate eyre que je souhaite vous présenter, nous allons faire un petit tour d’horizon de ce qui existe déjà.

Rétrospective de la gestion d’erreurs

La situation d’urgence : le panic

Il existe en Rust une manière d’interrompre une exécution. Il s’agit du mécanisme de panic.

fn will_fail() {
    panic!("Ce programme meurt ici et maintenant")
}

fn main() {
    will_fail();
    println!("Ne sera jamais affiché");
}

L’idée est simple, si le code arrive dans une instruction de panic, l’exécution se stoppe immédiatement et le programme retourne la stack trace.

thread 'main' panicked at 'Ce programme meurt ici et maintenant', src\main.rs:2:5
stack backtrace:
   2: error_reporting::will_fail
             at .\src\main.rs:2
   3: error_reporting::main
             at .\src\main.rs:6
note: Some details are omitted, run with `RUST_BACKTRACE=full` for a verbose backtrace.
error: process didn't exit successfully: `target\debug\error-reporting.exe` (exit code: 101)

Ce mécanisme permet de préserver un système d’un état qui ne peut pas être géré et qui doit provoquer son extinction pur et simple.

Exemple

Le fichier de configuration n’est pas trouvable et il n’y a pas de valeur par défaut.

Le gros point faible de ce système, est qu’une fois qu’un programme a paniqué, il est difficile (mais pas impossible) de le récupérer.

Information

Si vous voulez effectuer une récupération d’un panic, il existe un méthode catch_unwind, qui permet de faire poursuivre le programme en capturant la panique.
fn main() {
    catch_unwind(will_fail);
    println!("Hello world");
}
Par contre, ce système n’est pas conçu pour vous permettre de faire un mécanisme de try/catch. Il est uniquement là pour assurer la compatibilité avec des libs en C par exemple.

Utilisation d’un booléen comme status de retour

La réponse naïve dans la gestion d’erreur consiste à renvoyer un booléen true/false.

Il indique l’état d’un traitement.

Généralement:

true : tout s’est bien passé
false : une erreur est survenue

fn process() -> bool {
    true
}

fn main() {
    if process() {
        println!("Succès")
    } else {
        println!("Échec")
    }
}

Utilisation d’un code de retour numérique

Ce système marche bien lorsqu’il n’y a que deux états possibles.

Sinon l’on doit faire comme en C où l’on utilise des codes de retour.

0 : tout c’est bien passé
1 : une erreur recouvrable est survenue
autre chose : une erreur impossible à résoudre est survenue

fn process() -> u8 {
    2
}

fn main() {
    match process() {
        0 => println!("Succès"),
        1 => println!("Erreur"),
        _ => panic!("Crash"),
    }
}

Ce système rudimentaire, permet de pouvoir gérer plus finement le déroulé de notre programme. Mais ce n’est pas encore suffisant.

La gestion idiomatique des erreurs en Rust

Rust possède son propre système de gestion d’erreur basé sur une énumération Result.

Celle-ci se compose ainsi:

enum Result<T, E> {
    Ok(T),
    Err(E)
}

Les deux variantes de l’énumération étant génériques. Le type de la valeur de retour et le type de l’erreur ne sont pas contraints.

Nous allons créer notre propre erreur au travers d’une enumération:

enum MyError {
    Error,
    Failure,
}

Nous alors utiliser l’objet Rusult comme retour de notre méthode process.

fn process(input: i8) -> Result<u8, MyError> {

    if input < 0 {
        return Result::Err(MyError::Failure);
    }

    if input > 10 {
        return Result::Err(MyError::Error);
    }

    Result::Ok(input + 1)
}

Puis traiter l’erreur éventuelle, au travers d’un match.

fn main() {

    match process(41) {
        Ok(val) => {
            println!("Succès");
            println!("val : {val}");
        }
        Err(MyError::Error) => {
            println!("Erreur le nombre est supérieur à 10");
        }
        Err(MyError::Failure) => panic!("Le nombre ne peut pas être négatif"),
    };

Utiliser cette énumération nous ouvre certaines possibilitées comme la propagation des erreurs.

Propagation d’erreur

Imaginons qu’une erreur soit levée dans un appel profond de notre programme.

fn deep() -> Result<(), MyError> {
    Err(MyError::Error)
}

fn process(input: u8) -> Result<u8, MyError> {
    let result = deep();
    println!("After deep");
    Ok(input + 1)
}

Si l’on exécute la fonction process, nous allons voir s’afficher :

After deep`

Or, nous ne voulons pas ça.

Nous voulons que l’exécution de process se stoppe si la méthode deep est en erreur.

Pour ce faire, nous devons propager l’erreur venant de la méthode deep.

fn process(input: u8) -> Result<u8, MyError> {
    let result = deep();

    if let Err(error) = result {
        return Err(error);
    }

    println!("After deep");
    Ok(input + 1)
}

Après cette modification nous n’avons plus le After deep dans la console. Nous avons réalisé un early return de notre erreur.

Un ou deux sucre avec votre erreur ?

Le fait d’utiliser un Result de la stdlib nous ouvre aussi la porte à l’utilisation d’une syntaxe particulière qui permet de propager une erreur.

Celle-ci consiste à rajouter un ? à la fin de l’appel d’une fonction retournant un Result.

Ceci provoquera le retour immédiat de l’erreur si celle-ci survient.

fn process(input: u8) -> Result<u8, MyError> {
    deep()?;
    println!("After deep");
    Ok(input + 1)
}

Bien sûr, ce processus peut se réaliser à n’importe quelle profondeur d’exécution.

fn below_deep() -> Result<(), MyError> {
    Err(MyError::Error)
}

fn deep() -> Result<(), MyError> {
    below_deep()?;
    Ok(())
}

fn process(input: u8) -> Result<u8, MyError> {
    deep()?;
    println!("After deep");
    Ok(input + 1)
}

Ce qui permet de se concentrer sur l’essentiel c’est à dire le déroulé du code lorsqu’il y a pas d’échec.

Contexte d’erreur

Savoir que le code est en erreur est une chose, savoir pourquoi il l’est, c’est encore mieux.

Pour cela, nous allons aggrémenter notre erreur d’un contexte qui nous permettra de mieux cerner le souci.

enum MyError {
    Error(String),
    Failure,
}

Au lieu de renvoyer une simple erreur, nous allons également rajouter du contexte sous la forme d’une chaîne de caractères.

fn below_deep() -> Result<(), MyError> {
    Err(MyError::Error(
        "occurs into below_deep function".to_string(),
    ))
}

fn deep() -> Result<(), MyError> {
    below_deep()?;
    Err(MyError::Error("occurs into deep function".to_string()))
}

Puis, nous pouvons alors afficher cette Erreur avec plus de détails.

fn main() {

    let val = match process(old_val) {
        Ok(val) => {
            println!("Succès");
            println!("val : {val}")
        }
        Err(MyError::Error(details)) => {
            println!("Erreur: {details}");
        }
        Err(MyError::Failure) => panic!("Crash"),
    };

    
}

Cela nous donne dans la console:

Erreur: occurs into below_deep function

Nous sommes désormais, dans la capacité de déterminer qu’une erreur s’est produite, et pourquoi elle s’est produite.

Mais, nous ne savons pas où elle s’est produite.

Pour cela nous allons devoir agrémenter un peu notre code.

Capturer la backtrace dans le contexte

Il existe une crate qui se nomme backtrace-rs qui est capable d’effectuer ce travail pour nous.

D’abord, nous installons la crate.

cargo add backtrace

Puis, nous allons ensuite modifier notre structure d’erreur.

Ensuite, nous transformons la variante Error en une structure possédant deux champs:

details qui contient les détails de l’erreur
backtrace la callstack amenant à l’erreur

enum MyError {
    Error {
        backtrace: Backtrace,
        details: String,
    },
    Failure,
}

Pour nous faciliter la vie nous créons un contructeur

impl MyError {
    fn new(details: &str) -> Self {
        let backtrace = Backtrace::new();

        MyError::Error {
            backtrace,
            details: details.to_string(),
        }
    }
}

Que nous utilisons dans la suite du code

fn below_deep() -> Result<(), MyError> {
    Err(MyError::new("occurs into below deep function"))
}

fn deep() -> Result<(), MyError> {
    below_deep()?;
    Err(MyError::new("occurs into deep function"))
}

On modifie également la façon d’afficher les erreurs, pour rajouter la notion de backtrace.

fn main() {

    let val = match process(old_val) {
        Ok(val) => {
            println!("Succès");
            println!("val : {val}");
    
        }
        Err(MyError::Error { details, backtrace }) => {
            println!("Erreur: {details} \n {backtrace:?}");
        }
        Err(MyError::Failure) => panic!("Crash"),
    };

    println!("val : {val}")
}

Ce qui nous donne à l’exécution l’erreur suivante:

Erreur: occurs into below deep function 
   5: enum$<error_reporting::MyError, 1, 18446744073709551615, Error>::new
             at src\main.rs:13
   6: error_reporting::below_deep
             at src\main.rs:32
   7: error_reporting::deep
             at src\main.rs:36
   8: error_reporting::process
             at src\main.rs:41
   9: error_reporting::main
             at src\main.rs:49

Si on décrit cette stacktrace sous la forme d’un graph cela nous donne:

  

flowchart LR
    main --> process --> deep --> below_deep -.-> MyError::new

Sauf que le MyError::new est de trop dans l’histoire, il vient polluer la stacktrace avec une étape inutile.

Pour éviter cet appel à new, nous allons utiliser une macro qui va effectuer le tavail à notre place.

Si vous avez un trou de mémoire ou que ne connaissez pas le principe des macros, j’ai rédiger un article dessus. 😀

macro_rules! raise {
    ($details:expr) => {
        Err(MyError::Error {
            backtrace: Backtrace::new(),
            details: $details.to_string(),
        })
    };
}

Que l’on utilise ainsi:

fn below_deep() -> Result<(), MyError> {
    raise!("occurs into below deep function")
}

fn deep() -> Result<(), MyError> {
    below_deep()?;
    raise!("occurs into deep function")
}

Cette fois-ci la stacktrace devient:

Erreur: occurs into below deep function 
   5: error_reporting::below_deep
             at src\main.rs:21
   6: error_reporting::deep
             at src\main.rs:25
   7: error_reporting::process
             at src\main.rs:30
   8: error_reporting::main
             at src\main.rs:38

Où

  

flowchart LR
    main --> process --> deep --> below_deep

Ce qui est mieux. 😊

Qualifier sa chaîne d’erreurs

Il serait également intéressant de pouvoir qualifier les erreurs tout au long du parcours d’exécution.

Pour cela nous allons rajouter une notion de chaîne d’erreurs.

Celle-ci nous permettra au besoin de pouvoir parcourir les différentes erreurs ayant conduits à l’arrêt de l’exécution du programme.

enum MyError {
    Error {
        backtrace: Backtrace,
        details: String,
        source: Box<Option<MyError>>,
    },
    Failure,
}

Notre chaîne d’erreurs sera contenu dans le champ source.

Expliquons son type.

Option<MyError> : signifie la possibilité d’avoir un maillon inférieur dans notre chaîne d’erreurs
Box<Option<MyError>> : permet de rendre le champ représentable en mémoire, sans cela source aurait une taille infinie.

Nous rajoutons alors à notre macro raise, une autre possibilitée d’être invoquée.

macro_rules! raise {
    ($details:expr) => {
        Err(MyError::Error {
            backtrace: Backtrace::new(),
            details: $details.to_string(),
            source: Box::new(None),
        })
    };
    ($details:expr, $source:expr) => {
        Err(MyError::Error {
            backtrace: Backtrace::new(),
            details: $details.to_string(),
            source: Box::new(Some($source)),
        })
    };
}

Celle-ci prendra en deuxième paramètre une instance de MyError.

Que l’on peut utiliser ainsi:

fn below_deep() -> Result<(), MyError> {
    raise!("occurs into below deep function")
}

fn middle_deep() -> Result<(), MyError> {
    let result = below_deep();
    if let Err(error) = result {
        return raise!("was in middle", error);
    }
    Ok(())
}

fn deep() -> Result<(), MyError> {
    middle_deep()?;
    raise!("occurs into deep function")
}

Dans la méthode middle_deep, au lieu de propager l’erreur directement, nous allons l’aggrémenter d’informations supplémentaires.

Avant de retourner une nouvelle erreur possédant comme source, l’erreur déclenchée par la méthode below_deep.

let result = below_deep();
if let Err(error) = result {
    return raise!("was in middle", error);
}

Nous allons également devoir revoir la manière dont nous affichons nos erreurs.

impl MyError {
    fn format(&self) -> (Vec<String>, Backtrace) {
        let mut outer_details = vec![];
        let outer_backtrace = match self {
            MyError::Error {
                details,
                backtrace,
                source,
            } => {
                let mut backtrace = backtrace.clone();
                outer_details.push(details.to_string());

                if let Some(source) = source.deref() {
                    let (deep_details, result_backtrace) = source.format();
                    backtrace = result_backtrace;
                    outer_details.extend(deep_details.into_iter());
                }
                backtrace
            }
            MyError::Failure => unreachable!(),
        };
        (outer_details, outer_backtrace)
    }
}

L’algorithme est simple: on accumule les détails en traversant les différents maillons de la chaîne d’erreurs et l’on récupère la stacktrace la plus longue et donc celle du maillon le plus profond.

Ce qui nous permet ensuite d’implémenter le trait Debug

impl Debug for MyError {
    fn fmt(&self, f: &mut Formatter<'_>) -> std::fmt::Result {
        let (raw_details, backtrace) = self.format();

        let details = raw_details.join("\n\tError: ");
        write!(f, "Error: {details} \t\n {backtrace:?}")
    }
}

Puis de l’afficher dans notre main

fn main() {

    let val = match process(old_val) {
        Ok(val) => {
            println!("Succès");
            println!("val : {val}");
        }
        Err(error @ MyError::Error { .. }) => {
            println!("{error:?}");
        }
        Err(MyError::Failure) => panic!("Crash"),
    };
}

Cela nous donne:

Error: was in middle
	Error: occurs into below deep function
    
   5: error_reporting::below_deep
             at src\main.rs:66
   6: error_reporting::middle_deep
             at src\main.rs:70
   7: error_reporting::deep
             at src\main.rs:78
   8: error_reporting::process
             at src\main.rs:83
   9: error_reporting::main
             at src\main.rs:91

Vu que cette partie est un peu longue, je vous donne le code complet:

Code Rust

use backtrace::Backtrace;
use std::fmt::{Debug, Formatter};
use std::ops::Deref;

enum MyError {
    Error {
        backtrace: Backtrace,
        details: String,
        source: Box<Option<MyError>>,
    },
    Failure,
}

impl MyError {
    fn format(&self) -> (Vec<String>, Backtrace) {
        let mut outer_details = vec![];
        let outer_backtrace = match self {
            MyError::Error {
                details,
                backtrace,
                source,
            } => {
                let mut backtrace = backtrace.clone();
                outer_details.push(details.to_string());

                if let Some(source) = source.deref() {
                    let (deep_details, result_backtrace) = source.format();
                    backtrace = result_backtrace;
                    outer_details.extend(deep_details.into_iter());
                }
                backtrace
            }
            MyError::Failure => unreachable!(),
        };
        (outer_details, outer_backtrace)
    }
}

impl Debug for MyError {
    fn fmt(&self, f: &mut Formatter<'_>) -> std::fmt::Result {
        let (raw_details, backtrace) = self.format();

        let details = raw_details.join("\n\tError: ");
        write!(f, "Error: {details} \t\n {backtrace:?}")
    }
}

macro_rules! raise {
    ($details:expr) => {
        Err(MyError::Error {
            backtrace: Backtrace::new(),
            details: $details.to_string(),
            source: Box::new(None),
        })
    };
    ($details:expr, $source:expr) => {
        Err(MyError::Error {
            backtrace: Backtrace::new(),
            details: $details.to_string(),
            source: Box::new(Some($source)),
        })
    };
}

fn below_deep() -> Result<(), MyError> {
    raise!("occurs into below deep function")
}

fn middle_deep() -> Result<(), MyError> {
    let result = below_deep();
    if let Err(error) = result {
        return raise!("was in middle", error);
    }
    Ok(())
}

fn deep() -> Result<(), MyError> {
    middle_deep()?;
    raise!("occurs into deep function")
}

fn process(input: u8) -> Result<u8, MyError> {
    deep()?;
    println!("After deep");
    Ok(input + 1)
}

fn main() {

    let val = match process(old_val) {
        Ok(val) => {
            println!("Succès");
            println!("val : {val}");
        }
        Err(error @ MyError::Error { .. }) => {
            println!("{error:?}");
            old_val
        }
        Err(MyError::Failure) => panic!("Crash"),
    };
}

À partir de ce moment on peut commencer à nous amuser avec le système.

Par exemple effectuer le code

fn open_registry(registry_name: String) -> Result<(), MyError> {
    raise!(format!("Unable to open registry \"{registry_name}\""))
}

fn auth(id: u8) -> Result<(), MyError> {
    let result = open_registry(format!("registry_{id}"));
    if let Err(error) = result {
        return raise!(format!("Unable to open registry for user {id}"), error);
    }
    Ok(())
}

fn run() -> Result<(), MyError> {
    auth(42)?;
    raise!("occurs into deep function")
}

fn process(input: u8) -> Result<u8, MyError> {
    run()?;
    Ok(input + 1)
}

Ce qui nous donne comme chaîne d’erreur ceci:

Error: Unable to open registry for user 42
	Error: Unable to open registry "registry_42"

Ces contextes nous permettent de mieux comprendre les erreurs, et ainsi les debugger plus facilement.

Eyre est là pour nous faciliter la vie

Eyre est une crate qui est conçu pour réaliser la totalité des actions que nous avons implémentées plus haut.

La crate présente plusieurs éléments qui permettent de simplifier la vie au développeur.

L’objet Result de eyre

Le premier élément de la lib eyre est un objet eyre::Result<T, eyre::Report>.

Pour bénéficier de l’error reporting de eyre, vous devez remplacer vos Result par des eyre::Result.

Par exemple, si vous aviez une fonction qui retournait une std::result::Result<(), CustomError>

fn my_function() -> std::result::Result<(), CustomError> {...}

Vous allez devoir la remplacer par

fn my_function() -> eyre::Result<()> {...}

Le Report de eyre

Le eyre::Report est l’alternative d’erreur de eyre::Result. Son rôle est d’accumuler la chaîne d’erreur et de fournir le backtrace de la root_cause de l’erreur.

Générer un Report

Afin de faciliter la création d’un Report, la crate eyre fournit une macro eyre! permettant entre autre de générer un Report qui constituera le premier maillon de notre chaîne d’erreurs.

Cette macro est assez souple, elle peut prendre en entré:

soit une chaine de caractères
soit une structure ou une énumération qui implémente les traits Debug et Display

Pour une chaine de caractères cela donnerait:

fn my_function() -> eyre::Result<()> {
    Err(eyre!("Cette fonction va échouer"))
}

De même avec la structure ou l’énumération implémentant Debug et Display.

#[derive(Debug)]
enum CustomError {
    One,
}

impl Display for CustomError {
    fn fmt(&self, f: &mut Formatter<'_>) -> std::fmt::Result {
        write!(f, "{:?}", self)
    }
}

fn my_function() -> Result<()> {
    Err(eyre!(CustomError::One))
}

Wrapper une Erreur dans un Report

Une autre composante très importante de eyre est sa capacité à venir se greffer à n’importe quelle erreur existante (il peut y avoir des exceptions cependant).

Et venir qualifier des erreurs.

Ceci est réalisé au moyen d’une méthode wrap_err.

Par exemple:

fn my_function(path: &str) -> Result<()> {
    let file = File::open(path).wrap_err("Unable to open file {path}")?;
    Ok(())
}

On remarque le Report peut être manipulé comme n’importe quel Result et donc à la capactité d’être propagé au besoin.

Si l’on tente d’afficher le Report

fn my_function(path: &str) -> Result<()> {
    let report = File::open(path)
        .wrap_err(format!("Unable to open file {path}"))
        .unwrap_err();

    println!("{report:?}");

    Ok(())
}

voici ce que l’on obtient:

Unable to open file /tmp

Caused by:
    Le fichier spécifié est introuvable. (os error 2)

Location:
    src\main.rs:18:10

Stack backtrace:
...

Nous avons bien l’erreur primordiale venant de l’OS, et au-dessus le contexte que l’on a utilisé pour wrapper l’erreur système.

Exemple complet

Si l’on prend un exemple complet cela nous donne quelque chose comme ceci.

Code Rust

use eyre::{eyre, Result, WrapErr};
use std::fs::File;

fn open_ledger_internal(path: &str) -> Result<()> {
    File::open(path).wrap_err(format!("Unable to open file {path}"))?;
    Ok(())
}

fn open_ledger(ledger_id: u32) -> Result<()> {
    open_ledger_internal(&format!("/tmp/registry_{ledger_id}"))
        .wrap_err(eyre!("Unable to open ledger #{ledger_id}"))?;
    Ok(())
}

fn open_registry(registry_name: String) -> Result<()> {
    open_ledger(42666).wrap_err(eyre!("Unable to open registry : {registry_name}"))
}

fn auth(id: u8) -> Result<()> {
    open_registry(format!("registry_{id}"))
        .wrap_err(eyre!("Unable to open registry for user {id}"))?;

    Ok(())
}

fn run(id: u8) -> Result<()> {
    auth(id).wrap_err(format!("Trying to authenticate user #{id}"))?;
    Ok(())
}

fn process(user_id: u8) -> Result<()> {
    run(user_id).wrap_err(format!("Running with user #{user_id}"))?;
    Ok(())
}

fn main() {
    if let Err(report) = process(42) {
        println!("{report:?}")
    }
}

Qui se matérialise dans la console, lorsque l’on affiche le Report final en ceci:

Running with user #42

Caused by:
   0: Trying to authenticate user #42
   1: Unable to open registry for user 42
   2: Unable to open registry : registry_42
   3: Unable to open ledger #42666
   4: Unable to open file /tmp/registry_42666
   5: Le chemin d’accès spécifié est introuvable. (os error 3)

Location:
    src\main.rs:5:22

Stack backtrace:

  10: error_reporting::open_ledger_internal
             at .\src\main.rs:5
  11: error_reporting::open_ledger
             at .\src\main.rs:11
  12: error_reporting::open_registry
             at .\src\main.rs:17
  13: error_reporting::auth
             at .\src\main.rs:21
  14: error_reporting::run
             at .\src\main.rs:28
  15: error_reporting::process
             at .\src\main.rs:33
  16: error_reporting::main
             at .\src\main.rs:38

Cette stacktrace ainsi que les détails nous permettent d’avoir une vue complète de l’exécution de notre programme.

Information

Bien sûr, ici nous avons wrappé d’un contexte tous les Result des différents retours, mais nous aurions très bien pu juste propager l’erreur.

Si l’on modifie dans le code ci-dessus la méthode auth pour retirer le contexte.
fn auth(id: u8) -> Result<()> {
    open_registry(format!("registry_{id}")?;

    Ok(())
}
La chaîne de contextes d’erreurs devient:
Running with user #42

Caused by:
   0: Trying to authenticate user #42
   1: Unable to open registry : registry_42
   2: Unable to open ledger #42666
   3: Unable to open file /tmp/registry_42666
   4: Le chemin d’accès spécifié est introuvable. (os error 3)
Ainsi nul besoin, de vouloir absolument wrapper tous ses Report. La crate est suffisamment souple pour nous permettre de rajouter du contexte uniquement là où cela est nécessaire.

Gestion de l’affichage des Reports

un Report possède plusieurs façon de s’afficher:

Debug

S’affiche avec

println!("{report:?}")

Donne la dernière erreur connue, les details de chaque erreur de la chaîne ainsi que la stacktrace conduisant à l’erreur.

Running with user #42

Caused by:
   0: Trying to authenticate user #42
   1: Unable to open registry for user 42
   2: Unable to open registry : registry_42
   3: Unable to open ledger #42666
   4: Unable to open file /tmp/registry_42666
   5: Le chemin d’accès spécifié est introuvable. (os error 3)

Location:
    src\main.rs:5:22

Stack backtrace:
...

Display

S’affiche avec:

println!("{report}")

Donne seulement la dernière erreur connu et cache la raison primordiale.

Running with user #42

Display alternatif

S’affiche avec:

println!("{report:#}")

Donne toutes les raisons de la chaîne d’erreurs sur une seule ligne, cache la stacktrace.

Running with user #42: Trying to authenticate user #42: Unable to open registry : registry_42: Unable to open ledger #42666: Unable to open file /tmp/registry_42666: Le 
chemin d’accès spécifié est introuvable. (os error 3)

Utiliser eyre dans un exemple concret

Dans un précédent article nous avions uilisé un certain nombre de lib pour à la fois effectuer des requêtes sur le web et désérialiser des données.

Ces bibliothèques possèdent des erreurs spécifiques qui sont incompatibles entre-elles.

Ce qui rend compliquée la gestion immédiate des erreurs qui doivent être mappé vers une Erreur commune.

À l’époque nous avions utilisé la crate thiserror pour réaliser cette conversion.

use thiserror::Error;

#[derive(Error, Debug)]
enum CustomError {
    #[error("sqlite errors {0:?}")]
    Sqlite(sqlite::Error),
    #[error("reqwest errors")]
    Reqwest(reqwest::Error),
    #[error("json errors")]
    Json(serde_json::Error),
}

impl From<sqlite::Error> for CustomError {
    fn from(err: sqlite::Error) -> Self {
        CustomError::Sqlite(err)
    }
}

impl From<serde_json::Error> for CustomError {
    fn from(err: serde_json::Error) -> Self {
        CustomError::Json(err)
    }
}

impl From<reqwest::Error> for CustomError {
    fn from(err: reqwest::Error) -> Self {
        CustomError::Reqwest(err)
    }
}

Nous allons réécrire la même gestion d’erreurs mais en gérant cette fois-ci nos erreur dans un eyre::Report.

Pour plus de clarté je ne n’implémenterai pas la partie sqlite

La fonction qui nous intéresse est celle ci:

#[tracing::instrument]
async fn fetch_user(id: u32) -> Result<User> {
    let url = format!("https://jsonplaceholder.typicode.com/users/{}", id);

    let response = reqwest::get(url).await?;
    let response_string = response.text().await?;
    let user = serde_json::from_str(response_string.as_str())?;

    Ok(user)
}

Elle possède à la fois des erreurs de type reqwest et serde_json, grâce à la bibliothèque thiserror et les impl From<Error> cela est plus ou moins transparent.

Mais, cela représente tout de même un certain volume de code de boilerplate.

Voyons comment réécrire cela grâce à eyre.

use eyre::{eyre, Result, WrapErr};
use serde::Deserialize;

#[derive(Deserialize)]
struct User {
    id: u32,
    name: String,
    email: String,
    phone: String,
    website: String,
}

async fn fetch_user(url: &str) -> Result<User> {
    let response = reqwest::get(url).await?;

    let response_string = response.text().await?;
    let user = serde_json::from_str(response_string.as_str())?;

    Ok(user)
}

#[tokio::main]
async fn main() {
    let url = "https://jsonplaceholder.typicode.com/users/1";
    if let Err(report) = fetch_user(url).await {
        println!("{report:?}")
    }
}

Je vous fournis également le Cargo.toml

[dependencies]
eyre = "0.6.8"
reqwest = { version = "0.11.11", features = ["json"] }
serde = { version = "1.0.140", features = ["derive"] }
serde_json = "1.0.82"
thiserror = "1.0.31"
tokio = {version = "1.20.1", features = ["rt-multi-thread", "macros"]}

C’est plus simple non ? 🤩

On essaie la gestion d’erreur

Pas d’erreur

Pour une url=https://jsonplaceholder.typicode.com/users/1: pas de soucis.

Reqwest

Pour une url=https://jsonplaceholder.typicode.com2/users/1, le report renvoit:

error sending request for url (https://jsonplaceholder.typicode.com2/users/1): error trying to connect: dns error: Hôte inconnu. (os error 11001)

Caused by:
   0: error trying to connect: dns error: Hôte inconnu. (os error 11001)
   1: dns error: Hôte inconnu. (os error 11001)
   2: Hôte inconnu. (os error 11001)

Location:
    src\main.rs:14:20

Stack backtrace:
  10: error_reporting::fetch_user::async_fn$0
             at .\src\main.rs:14
  12: error_reporting::main::async_block$0
             at .\src\main.rs:23
  24: error_reporting::main
             at .\src\main.rs:23

Le sytème tente de réaliser un call HTTP sur le domaine ”jsonplaceholder.typicode.com2”, mais celui-ci n’existe pas.

Json

Pour une url=https://jsonplaceholder.typicode.com/users/22, le report renvoit:

missing field `id` at line 1 column 2

Location:
    src\main.rs:15:16

Stack backtrace:
  10: error_reporting::fetch_user::async_fn$0
             at .\src\main.rs:15
  12: error_reporting::main::async_block$0
             at .\src\main.rs:23
  24: error_reporting::main
             at .\src\main.rs:23

Au-delà de 10, l’API renvoit un json vide. La phase de désérialisation échoue car elle n’arrive pas à trouver le champ id.

Enrichir les erreurs

Cette erreur de désérialisation n’est pas claire, essayons de rajouter un peu plus de contexte.

async fn fetch_user(url: &str) -> Result<User> {
    let response = reqwest::get(url).await?;

    let response_string = response.text().await?;
    let user = serde_json::from_str(response_string.as_str())
        .wrap_err(format!("Error while trying to deserialize user from {url}"))?;

    Ok(user)
}

Error while trying to deserialize user from https://jsonplaceholder.typicode.com/users/22

Caused by:
    missing field `id` at line 1 column 2

Et bien, voilà! C’est beaucoup mieux! 😁

Le debugging sera bien plus simple ainsi.

Et nous nous sommes débarassé de beaucoup de code qui venait parasiter notre compréhension des choses.

Nous nous sommes également épargné un crate supplémentaire.

Utiliser eyre dans le contexte d’une lib

La documentation officielle prévient qu’il n’est pas recommendé d’exposer directement un eyre::Result comme sortie d’erreur publique de votre lib.

La créatrice de eyre en a fait une réponse dans un thread d’issue github.

Pour simuler cette exposition d’erreurs par une lib externe, je vous propose d’utiliser ce projet que nous allons détailler ensemble.

Le projet est composé d’un workspace contenant un sous projet user, ce sous-projet sera notre lib externe exposant une API d’erreur spécifique.

Le main.rs principal est plutôt simple, il déclare le réacteur asynchrone de tokio et affiche soit l’utilisateur si trouvé, soit l’erreur venant de la lib user si ce n’est pas le cas.

#[tokio::main]
async fn main() {
    let url = "https://jsonplaceholder.typicode.com/users/2";

    match user::run(url).await {
        Ok(user) => {
            println!("{user:?}");
        }
        Err(error) => {
            eprintln!("{error}")
        }
    }
}

Dans la lib user, la méthode fetch_user ne bouge pas.

Enfin on introduit dans lib user une méthode run dont son rôle est de transformer le Report de fetch_user en une UserError.

use thiserror::Error;

#[derive(Debug, Error)]
pub enum UserError {
    #[error("Unable to fetch url: {0}")]
    Fetch(String),
    #[error("Unable to unmarshal user data: {0}")]
    Unmarshal(String),
    #[error("Unknown error")]
    Unknown,
}

On réutilise ici la crate thiserror pour nous simplifier la création des erreurs, cette crate nous permettant dimplémenté le trait Display.

On va ici introduire une fonctionnalité essentielle de eyre: le déréférencement !

L’idée est de récupérer l’erreur qui a été wrap par le Report.

Imaginons la situation suivante, si l’on wrap une erreur venant d’un File::open, nous allons obtenir un Report contenant une io::Error.

Pour récupérer cette io::Error, nous allons devoir la déréférencer du Report.


let result : Result<File, Report> = File::open("\tmp\not\exists").wrap_err("This file not exists");

if let Err(report) = result {
    if let Some(io_error: &io::Error) = report.downcast_ref::<io::Error>() {
        // ...
    }
}

Ici le plus important à comprendre c’est l’appel à report.downcast_ref::<E>(), E étant le type vers lequel l’on souhaite caster le Report.

Ce qui fait qu’à partir de ce moment là on est capable de savoir le type exact de l’erreur qui vient d’être levée.

La deuxième capacité de downcast_ref, est de pouvoir également extraire le contexte du Report.

if let Err(report) = result {
    if let Some(io_error: &io::Error) = report.downcast_ref::<io::Error>() {
        if let Some(details: &&str) = report.downcast_ref::<&str>() {
            // details == "This file not exists"
        }
    }
}

Attention

Si le contexte provient d’un format! alors son type est String et non &str.

Il faut donc modifier le downcast en conséquence!

let result : Result<File, Report> = File::open("\tmp\not\exists")
    .wrap_err(format!("File {} not exists", "\tmp\not\exists"));

if let Err(report) = result {
    if let Some(io_error: &io::Error) = report.downcast_ref::<io::Error>() {
        if let Some(details: &String) = report.downcast_ref::<String>() {
            // details == "This file not exists"
        }
    }
}

Revenons maintenant à notre lib user.

Notre fonction run, prend en paramètre une URL et effectue un fetch_user.

S’il y a erreur, elle transforme le Report en une UserError qui peut ensuite être présentée publiquement.

pub async fn run(url: &str) -> Result<User, UserError> {
    match fetch_user(url).await {
        Ok(user) => Ok(user),
        Err(report) => {

            // Gestion d'une erreur de fetch
            if let Some(reqwest_error) = report.downcast_ref::<reqwest::Error>() {
                return Err(UserError::Fetch(reqwest_error.to_string()));
            }

            // Gestion d'une erreur de désérialisation
            if let Some(serde_error) = report.downcast_ref::<serde_json::Error>() {
                // Si du contexte est accroché à l'erreur on le récupère
                if let Some(details) = report.downcast_ref::<String>() {
                    return Err(UserError::Unmarshal(details.to_string()));
                }
                // Sinon on renvoie l'erreur brute
                return Err(UserError::Unmarshal(serde_error.to_string()));
            }
            // On gère aussi le cas d'une erreur inconnue
            Err(UserError::Unknown)
        }
    }
}

Faisons quelques essais.

url=”https://jsonplaceholder.typicode.com/users/2”

User { id: 2, name: “Ervin Howell”, email: “Shanna@melissa.tv”, phone: “010-692-6593 x09125”, website: “anastasia.net” }

url=”https://jsonplaceholder.typicode.com/users/22”

Unable to unmarshal user data: Error while trying to deserialize user from https://jsonplaceholder.typicode.com/users/22

url=”https://jsonplaceholder.typicode.com2/users/2”

Unable to fetch url: error sending request for url (https://jsonplaceholder.typicode.com2/users/): error trying to connect: dns error: Hôte inconnu. (os error 11001)

Conclusion

Et Voilà !

Comme toujours, il y aurait encore tant de chose à dire, mais nous allons nous arrêter là pour aujourd’hui.

J’espère que la découverte de la bibliothèque eyre vous a plu, et que la restropective de la gestion d’erreur aussi! 😁

Je vous souhaite une bonne journée et merci de m’avoir lu. ❤️

Debugguer avec la télemétrie en Rust

2022-07-15T00:00:00+00:00

Bonjour à toutes et tous 😀

Un ~~court~~ article sur ma frustration du moment. Je bosse actuellement avec de l’asynchrone et du parrallélisme.

C’est très cool quand ça marche mais c’est une galère sans nom à débugguer quand ça veut pas. 🙄

Et quand je dis ça veut pas, je veux dire, l’app bloque sans messages de log parce que vous êtes dans un test d’inté par exemple (non c’est pas du tout du vécu 😡).

Aujourd’hui, je vous rédige ce billet pour vous montrer de quelle manière l’on peut débugguer ce genre de situations.

Installer les outils

Nous allons utiliser un projet en Go qui s’appelle Jaeger (rien à voir avoir avec les Titans 😋) , ceci est un outil de tracing permettant de visualiser l’éxécution d’un programme asynchrone.

Comme pré-requis, je considère que vous avez Docker d’installé et de fonctionnel sur votre machine.

Ainsi que Rust 1.62+ également installé et de fonctionnel.

Lancez jaeger.

docker run -d --name jaeger \
    -p6831:6831/udp \
    -p6832:6832/udp \
    -p16686:16686 \
    -p14268:14268 \
    jaegertracing/all-in-one:latest

Si vous vous rendez sur localhost:16686. Vous devriez vous retrouver devant une interface comme celle ci:

Nous allons aussi avoir besoin d’un projet en Rust.

cargo new lab-telementry
cd lab-telementry
cargo add opentelemetry
cargo add opentelemetry-jaeger
cargo add tracing
cargo add tracing-opentelemetry
cargo add tracing-subscriber

Ou dans le Cargo.toml

[dependencies]
opentelemetry = "0.17.0"
opentelemetry-jaeger = "0.16.0"
tracing = "0.1.35"
tracing-opentelemetry = "0.17.4"
tracing-subscriber = "0.3.14"

Les concepts de base

Tracer et Layer

Avant de savoir courir il faut apprendre à marcher.

Notre cerveau primitif, n’étant vraiment pas câblé pour l’asynchrone, nous allons expliquer les concepts de bases dans un environnement synchrone.

Pour cela dans le main.rs, nous allons créer un petit code de test.

Nous allons d’abord déclarer notre Tracer jaeger.

let tracer_jaeger = opentelemetry_jaeger::new_agent_pipeline()
    .with_service_name("lab-telemetry")
    .install_simple()
    .unwrap()

Nous lui donnons le nom de service lab-telemetry. C’est en quelque sorte l’identifiant projet dans Jaeger, en effet on peut faire le tracing d’une multitude de projet à la fois. Il faut bien quelque choses pour les distinguer.

Ensuite nous allons déclarer un Layer OpenTelemetry avec notre Tracer jaeger.

let opentelemetry_layer = tracing_opentelemetry::layer()
    .with_tracer(tracer_jaeger);

OpenTelemetry est une initiative d’uniformisation des standards. Son but est de rendre compatibles l’ensemble des outils de l’écosystème de l’observabilité déjà existants.

Puis nous allons enregister notre Layer dans un Registry.

tracing_subscriber::registry()
    .with(opentelemetry_layer)
    .init();

Le rôle du Registry va être de capturer les Span et de les distribuer aux différent Layers qui ont souscrit à ce Registry. Dans notre cas le opentelemetry_layer.

En parlant de Span créons en une.

let _ = span!(tracing::Level::TRACE, "my span");

Une Span est une portion bornée temporellement dans l’éxécution d’un programme, qui a une date de début et une date de fin.

Entre ces deux bornes temporelles, il va se dérouler des évènements.

Nous allons aussi forcer les Tracer à envoyer toutes les Spans qu’ils connaissent avant de terminer le programme.

shutdown_tracer_provider();

Code Rust

use opentelemetry::global::shutdown_tracer_provider;
use tracing::span;
use tracing_subscriber::layer::SubscriberExt;
use tracing_subscriber::util::SubscriberInitExt;

fn main() {
    // Create a Jaeger Tracer
    let tracer_jaeger = opentelemetry_jaeger::new_pipeline()
        .with_service_name("lab-telemetry")
        .install_simple()
        .unwrap();

    // Create a tracing layer with the configured tracer
    let opentelemetry_layer = tracing_opentelemetry::layer().with_tracer(tracer_jaeger);

    // Register Layers
    tracing_subscriber::registry()
        .with(opentelemetry_layer)
        .init();

    // Declare a span
    let _ = span!(tracing::Level::TRACE, "my span");

    // Force all Span to be sent
    shutdown_tracer_provider();
}

Si vous allez sur localhost:16686. En sélectionnant le service lab-telemetry et ensuite en appuyant sur le bouton Find Traces.

Vous devriez désormais voir la span dans le volet de droite, ici entouré en rouge.

Cela signifie que notre système est opérationnel. Il envoie des Span à Jaeger.

On récapitule

Nous avons un Tracer jaeger qui est capable de transformer des Spans en dans un format de messages que Jaeger est capable de comprendre.

Ce Tracer est inclue dans un Layer OpenTelemetry qui sert de couche de compatibilité au reste de la télémétrie.

Ce Layer est enregistré dans un Registry qui écoute les spans de notre éxécution de code.

Les Spans sont des intervalles de temps dans l’éxécution de notre code.

Les spans

Je vous dis depuis tout à l’heure qu’une Span est un intervalle de temps. Mais il ne semble pas y avoir ni de début ni de fin à notre Span.

Déclarons le début de notre Span ainsi que sa fin.

    let guard = span!(Level::TRACE, "my_span bound").entered();
    sleep(Duration::from_secs(2));
    guard.exit();

Nous avons bien une Span de 2 secondes.

Ce qui est intéressant, c’est que les Spans peuvent elles-même contenir d’autres Spans

let parent = span!(Level::TRACE, "parent").entered();

    sleep(Duration::from_secs(2));

    let child = span!(Level::TRACE, "child").entered();
        sleep(Duration::from_secs(1));
    child.exit();

parent.exit();

Dans Jaeger cela nous donne bien une Span de 3 secondes.

Mais détail supplémentaire, cette entrée possède 2 spans.

Cliquez sur 2 Spans.

Nous voyons bien l’imbrication des deux Spans. Le parent dure 3 secondes, l’enfant démarre deux secondes après le début du parent et dure 1 seconde.

Ce que vous voyez là ce nomme un flamechart et constitue le nerf de la guerre de notre article.

Il permet de visualiser temporellement les Spans de notre application et ainsi comprendre les agencements des appels lors de l’éxécution du programme.

Pour le moment tout est synchrone donc simple à comprendre mais ça va se corser très vite. 😇

Le code actualisé.

Code Rust

use opentelemetry::global::shutdown_tracer_provider;
use std::thread::sleep;
use std::time::Duration;
use tracing::{span, Level};
use tracing_subscriber::layer::SubscriberExt;
use tracing_subscriber::util::SubscriberInitExt;

fn main() {
    // Create a Jaeger Tracer
    let tracer_jaeger = opentelemetry_jaeger::new_pipeline()
        .with_service_name("lab-telemetry")
        .install_simple()
        .unwrap();

    // Create a tracing layer with the configured tracer
    let opentelemetry_layer = tracing_opentelemetry::layer().with_tracer(tracer_jaeger);

    // Register Layers
    tracing_subscriber::registry()
        .with(opentelemetry_layer)
        .init();

    // Declare a span
    let parent = span!(Level::TRACE, "parent").entered();

    sleep(Duration::from_secs(2));

    let child = span!(Level::TRACE, "child").entered();
    sleep(Duration::from_secs(1));
    child.exit();

    parent.exit();

    // Force all Span to be sent
    shutdown_tracer_provider();
}

Les logs

Nous sommes désormais dans la capacité de déterminer quand telles où telles Span commencent et se terminent et même de les imbriquer.

C’est bien de savoir le Quand mais le Quoi c’est encore mieux.

C’est à ce stade que la notion de logs est introduite.

Elle va nous permettre de définir des messages rattacher à la Span.

let parent = span!(Level::TRACE, "parent").entered();
    info!("Début de la span parent");

    debug!("Nous allons attendre 2 secondes...");
    sleep(Duration::from_secs(2));
    debug!("Fin du délai d'attente de 2 secondes");

    let child = span!(Level::TRACE, "child").entered();
        info!("Début de la span child");
        debug!("Nous allons attendre 2 secondes...");
        sleep(Duration::from_secs(1));
        debug!("Fin du délai d'attente de 2 secondes");
        info!("Fin de la span child");
    child.exit();
    info!("Fin de la span parent");
parent.exit();

Dans Jaeger.

Si vous cliquez sur les deux textes encadrés en rouge à gauche, puis sur Logs. Vous devriez visualiser ceci:

Ce qui est encadré en bleu se nomme un évènement ou Event. Une même Span peut contenir de zéro à plusieurs événements.

Ici, nos deux Spans possèdent chacune 4 Events.

Il est également possible de les ouvrir pour avoir encore plus de détails.

Ici, nous retrouvons le corps du message ainsi que le niveau de log, le numéro de ligne et le fichier qui a émit cet Event.

Ce qui est intéressant c’est que ces Event peuvent-être variabilisés et enrichis.

let id = 42;
let parent = span!(Level::TRACE, "parent").entered();
  info!(request.id = id, "Début de la span parent");

Et même avec des données complexes comme des structures.

#[derive(Debug)]
struct Request {
    id: u8,
    path: &'static str,
    method: &'static str,
}

impl Display for Request {
    fn fmt(&self, f: &mut Formatter<'_>) -> std::fmt::Result {
        write!(f, "Je suis une requête")
    }
}

let request = Request {
    id: 42,
    path: "/home",
    method: "GET",
};

let parent = span!(Level::TRACE, "parent").entered();
info!(
    request.id = request.id,
    request_display = %request,
    request_debug = ?request,
    "Début de la span parent"
);

Nous pouvons accéder au champ request.id.
Nous pouvons appeler le trait Dispay de Request via le sigil %.
Nous pouvons également appeler le trait Debug de Request via le sigil ?.

Sur Jaeger cela nous donne:

Les champs qui sont rattachés à un Event sont des Tags. Un Tag est une entité indexée qui peut être recherchée dans Jaeger et dans tout autre plateforme d’analyse de télémétrie.

Il en va de même pour notre tag personnalisé request.id.

Et là on s’aperçoit très vite que si l’on balade un identifiant dans toute nos spans on va pouvoir avoir une vision d’ensemble extrêmement précise de ce qui se passe dans notre système pour un identifiant donné.

On récapitule

Nous avons un Tracer jaeger qui est capable de transformer des Span en dans un format de messages que Jaeger est capable de comprendre.

Ce Tracer est compris dans un Layer OpenTelemetry qui sert de couche de compatibilité au reste de la télémétrie.

Ce Layer est enregistré dans un Registry qui écoute les spans de notre éxécution de code.

Les Spans sont des intervalles de temps dans l’éxécution de notre code.

Les Spans peuvent avoir des Events

Les Events sont des points datés dans l’éxécution d’une Span

Un Event peut avoir des Tags

Les Tags sont des clefs-valeurs qui sont indexés et donc qui peuvent être recherchés au sein d’une plateforme d’analyse de télémétrie.

Avec ça, nous avons tout le vocabulaire nécessaire! 😀

Le code de cette partie:

Code Rust

use opentelemetry::global::shutdown_tracer_provider;
use std::fmt::{Display, Formatter};
use std::thread::sleep;
use std::time::Duration;
use tracing::{debug, info, span, Level};
use tracing_subscriber::layer::SubscriberExt;
use tracing_subscriber::util::SubscriberInitExt;

fn main() {
    // Create a Jaeger Tracer
    let tracer_jaeger = opentelemetry_jaeger::new_pipeline()
        .with_service_name("lab-telemetry")
        .install_simple()
        .unwrap();

    // Create a tracing layer with the configured tracer
    let opentelemetry_layer = tracing_opentelemetry::layer().with_tracer(tracer_jaeger);

    // Register Layers
    tracing_subscriber::registry()
        .with(opentelemetry_layer)
        .init();

    #[derive(Debug)]
    struct Request {
        id: u8,
        path: &'static str,
        method: &'static str,
    }

    impl Display for Request {
        fn fmt(&self, f: &mut Formatter<'_>) -> std::fmt::Result {
            write!(f, "Je suis une requête")
        }
    }

    let request = Request {
        id: 42,
        path: "/home",
        method: "GET",
    };

    let parent = span!(Level::TRACE, "parent").entered();
    info!(
        request.id = request.id,
        request_display = %request,
        request_debug = ?request,
        "Début de la span parent"
    );

    debug!("Nous allons attendre 2 secondes...");
    sleep(Duration::from_secs(2));
    debug!("Fin du délai d'attente de 2 secondes");

    let child = span!(Level::TRACE, "child").entered();
    info!("Début de la span child");
    debug!("Nous allons attendre 2 secondes...");
    sleep(Duration::from_secs(1));
    debug!("Fin du délai d'attente de 2 secondes");
    info!("Fin de la span child");
    child.exit();
    info!("Fin de la span parent");
    parent.exit();

    // Force all Span to be sent
    shutdown_tracer_provider();
}

Instrumentation des fonctions

Pour le moment notre système fonctionne bien dans notre méthode main, mais comme tout programme un peu conséquent il faudra invariablement le modulariser.

Et donc le découper en fonction.

Nous allons en écrire deux et réutiliser notre structure Request:

#[derive(Debug)]
struct Request {
    id: u8,
    path: &'static str,
    method: &'static str,
    token: &'static str,
}

fn handle_request(request: Request) {
    if auth(request) {
        // ...
    } else {
        // ...
    }
}

fn auth(request: Request) -> bool {
    request.token == "blabla"
}

Nous allons maintenant rajouter des spans, des events et des tags à nos fonctions.

fn handle_request(request: Request) {
    let span = trace_span!("handle_request").entered();
    if auth(&request) {
        info!(request = ?request, id = request.id, "Request authenticated")
    } else {
        error!(request = ?request, id = request.id, "Request forbidden")
    }
    span.exit();
}

fn auth(request: &Request) -> bool {
    let span = trace_span!("auth").entered();
    // Emulate call for db
    sleep(Duration::from_millis(500));
    let value = request.token == "blabla";
    span.exit();
    value
}

Et dans notre main

let request = Request {
    id: 42,
    path: "/home",
    method: "GET",
    token: "blabla",
};

let request2 = Request {
    id: 43,
    path: "/home",
    method: "GET",
    token: "bleubleu",
};

let span = span!(Level::TRACE, "main").entered();
handle_request(request);
handle_request(request2);
span.exit();

Sur jaeger, cela nous donne ceci:

On y voit une span différente pour chaque appel à handle_request.

En ouvrant les détails nous pouvons voir le token en cause.

Maintenant nous allons simplifier l’écriture en utilisant un attribut de fonction.

Cet attribut est #[tracing::instrument].

#[tracing::instrument(name = "main")]
fn handle_requests() {
    let request = Request {
        id: 42,
        path: "/home",
        method: "GET",
        token: "blabla",
    };

    let request2 = Request {
        id: 43,
        path: "/home",
        method: "GET",
        token: "bleubleu",
    };

    handle_request(request);
    handle_request(request2);
}

#[tracing::instrument]
fn handle_request(request: Request) {
    if auth(&request) {
        info!(request = ?request, id = request.id, "Request authenticated")
    } else {
        error!(request = ?request, id = request.id, "Request forbidden")
    }
}

#[tracing::instrument]
fn auth(request: &Request) -> bool {
    // Emulate call for db
    sleep(Duration::from_millis(500));
    request.token == "blabla"
}

#[tracing::instrument(name = "main")]
Permet de redéfinir le nom de la span; par défaut il s’agit du nom de la fonction décorée.

Il devient alors facile d’outiller les fonctions et d’en rajouter un peu partout.

En bonus, on gagne également le tag request qui provient des paramètres de notre appel à handle_request. Et ce, gratuitement.

Code de la partie.

Code Rust

use opentelemetry::global::shutdown_tracer_provider;

use std::thread::sleep;
use std::time::Duration;
use tracing::{error, info, span, trace_span, Level};
use tracing_subscriber::layer::SubscriberExt;
use tracing_subscriber::util::SubscriberInitExt;

#[derive(Debug)]
struct Request {
    id: u8,
    path: &'static str,
    method: &'static str,
    token: &'static str,
}

fn main() {
    // Create a Jaeger Tracer
    let tracer_jaeger = opentelemetry_jaeger::new_pipeline()
        .with_service_name("lab-telemetry")
        .install_simple()
        .unwrap();

    // Create a tracing layer with the configured tracer
    let opentelemetry_layer = tracing_opentelemetry::layer()
        .with_tracer(tracer_jaeger);

    // Register Layers
    tracing_subscriber::registry()
        .with(opentelemetry_layer)
        .init();

    handle_requests();

    // Force all Span to be sent
    shutdown_tracer_provider();
}

#[tracing::instrument(name = "main")]
fn handle_requests() {
    let request = Request {
        id: 42,
        path: "/home",
        method: "GET",
        token: "blabla",
    };

    let request2 = Request {
        id: 43,
        path: "/home",
        method: "GET",
        token: "bleubleu",
    };

    handle_request(request);
    handle_request(request2);
}

#[tracing::instrument]
fn handle_request(request: Request) {
    if auth(&request) {
        info!(request = ?request, id = request.id, "Request authenticated")
    } else {
        error!(request = ?request, id = request.id, "Request forbidden")
    }
}

#[tracing::instrument]
fn auth(request: &Request) -> bool {
    // Emulate call for db
    sleep(Duration::from_millis(500));
    request.token == "blabla"
}

L’asynchrone

Nous allons rendre asynchrone et parallélisé le code du dessus.

Avant tout installons tokio.

cargo add tokio --features macros --features rt --features rt-multi-thread

Ce qui nous donne dans le Cargo.toml

tokio = { version = "1.20.0", features = ["macros", "rt", "rt-multi-thread"] }

Puis, il faut que l’on fasse évoluer notre méthode handling_requests.

Elle devient asynchrone

#[tracing::instrument(name = "main")]
async fn handle_requests() {
    // corps de la méthode
}

Puis nous allons modifier notre fonction handle_requests.

#[tracing::instrument(name = "main")]
async fn handle_requests() {
    let request = Request {
        id: 42,
        path: "/home",
        method: "GET",
        token: "blabla",
    };

    let request2 = Request {
        id: 43,
        path: "/home",
        method: "GET",
        token: "bleubleu",
    };

    let span = Span::current();

    let t1 = tokio::spawn(handle_request(request));

    let span = Span::current();
    let t2 = tokio::spawn(
        async {
            thread::sleep(Duration::from_millis(100));
            handle_request(request2).await
        }
    );

    let _ = join!(t1, t2);
}

Pour que l’asynchrone fonctionne il lui faut un reactor, ici ce sera tokio.

#[tokio::main]
async fn main() {
    // ...
}

Étant donné que handling_requests est désormais asynchrone, il faut la poll pour qu’elle fasse quelque chose.

handle_requests().await;

Le code complet

Code Rust

use opentelemetry::global::shutdown_tracer_provider;
use std::thread;

use std::thread::sleep;
use std::time::Duration;
use tokio::join;
use tracing::{error, info, Span};
use tracing_subscriber::layer::SubscriberExt;
use tracing_subscriber::util::SubscriberInitExt;

#[derive(Debug)]
struct Request {
    id: u8,
    path: &'static str,
    method: &'static str,
    token: &'static str,
}

#[tokio::main]
async fn main() {
    // Create a Jaeger Tracer
    let tracer_jaeger = opentelemetry_jaeger::new_pipeline()
        .with_service_name("lab-telemetry")
        .install_simple()
        .unwrap();

    // Create a tracing layer with the configured tracer
    let opentelemetry_layer = tracing_opentelemetry::layer().with_tracer(tracer_jaeger);

    // Register Layers
    tracing_subscriber::registry()
        .with(opentelemetry_layer)
        .init();

    handle_requests().await;

    // Force all Span to be sent
    shutdown_tracer_provider();
}

#[tracing::instrument(name = "main")]
async fn handle_requests() {
    let request = Request {
        id: 42,
        path: "/home",
        method: "GET",
        token: "blabla",
    };

    let request2 = Request {
        id: 43,
        path: "/home",
        method: "GET",
        token: "bleubleu",
    };

    let t1 = tokio::spawn(handle_request(request));
    
    let t2 = tokio::spawn(async {
        // Je décale l'exécution de 100 ms pour un rendu plus visuel
        thread::sleep(Duration::from_millis(100));
        handle_request(request2).await
    });

    let _ = join!(t1, t2);
}

#[tracing::instrument]
async fn handle_request(request: Request) {
    if auth(&request) {
        info!(request = ?request, id = request.id, "Request authenticated")
    } else {
        error!(request = ?request, id = request.id, "Request forbidden")
    }
}

#[tracing::instrument]
fn auth(request: &Request) -> bool {
    // Emulate call for db
    sleep(Duration::from_millis(500));
    request.token == "blabla"
}

Si l’on éxécute le code tel quel nous allons observer que nos spans sont découpés en 3.

En effet, les différentes fonctions évoluant dans des threads différents les contextes et donc les root spans sont aussi différents.

Ce qui nous donne le résultat suivant:

Pour réconciller ces threads nous allons devoir opérer quelques changements.

La crate tracing nous permet de facilement attacher une span à un thread et plus particulèrement à la futur éxécutée.

let future = async {
    
};

tokio::spawn(future.instrument(info_span!("ma span")))

Cet appel à instrument va venir accrocher la span “ma span” à l’éxécution de la futur ainsi sera repésenté par “ma span” dans Jaeger.

Faites le test. 😛

On peut donc en extrapole quelque chose comme:

let fut1 = handle_request(request);
let fut2 = async {
    thread::sleep(Duration::from_millis(100));
    handle_request(request2).await
};

let t1 = tokio::spawn(fut1.instrument(info_span!("handle request success")));
let t2 = tokio::spawn(fut2.instrument(info_span!("handle request fail")));

let _ = join!(t1, t2);

Ce qui nous donne le résultat suivant sur Jaeger

Et si l’on désire ne avoir de wrapping on peut également écrire ceci:

let t1 = tokio::spawn(fut1.instrument(Span::current()));
let t2 = tokio::spawn(fut2.instrument(Span::current()));

Span::current() permet de récupérer la span du thread parent.

Et voilà nous sommes en mesure de pouvoir comprendre d’un coup d’oeil ce qu’il se passe temporellement lors de l’éxécution en parallèle de plusieurs threads.

Le code final

Code Rust

use opentelemetry::global::shutdown_tracer_provider;
use std::thread;

use std::thread::sleep;
use std::time::Duration;
use tokio::join;
use tracing::{error, info, Instrument, Span};
use tracing_subscriber::layer::SubscriberExt;
use tracing_subscriber::util::SubscriberInitExt;

#[derive(Debug)]
struct Request {
    id: u8,
    path: &'static str,
    method: &'static str,
    token: &'static str,
}

#[tokio::main]
async fn main() {
    // Create a Jaeger Tracer
    let tracer_jaeger = opentelemetry_jaeger::new_pipeline()
        .with_service_name("lab-telemetry")
        .install_simple()
        .unwrap();

    // Create a tracing layer with the configured tracer
    let opentelemetry_layer = tracing_opentelemetry::layer().with_tracer(tracer_jaeger);

    // Register Layers
    tracing_subscriber::registry()
        .with(opentelemetry_layer)
        .init();

    handle_requests().await;

    // Force all Span to be sent
    shutdown_tracer_provider();
}

#[tracing::instrument(name = "main")]
async fn handle_requests() {
    let request = Request {
        id: 42,
        path: "/home",
        method: "GET",
        token: "blabla",
    };

    let request2 = Request {
        id: 43,
        path: "/home",
        method: "GET",
        token: "bleubleu",
    };

    let fut1 = handle_request(request);
    let fut2 = async {
        thread::sleep(Duration::from_millis(100));
        handle_request(request2).await
    };

    let t1 = tokio::spawn(fut1.instrument(Span::current()));
    let t2 = tokio::spawn(fut2.instrument(Span::current()));

    let _ = join!(t1, t2);
}

#[tracing::instrument]
async fn handle_request(request: Request) {
    if auth(&request) {
        info!(request = ?request, id = request.id, "Request authenticated")
    } else {
        error!(request = ?request, id = request.id, "Request forbidden")
    }
}

#[tracing::instrument]
fn auth(request: &Request) -> bool {
    // Emulate call for db
    sleep(Duration::from_millis(500));
    request.token == "blabla"
}

Problèmes pouvant être rencontrés

La span n’est jamais envoyée.

Parfois nous trouvons dans des situations où une span devrait apparaître mais ne le fait jamais.

Pour comprendre cette situation, prenons le code suivant:

use opentelemetry::global::shutdown_tracer_provider;
use std::thread::sleep;
use std::time::Duration;
use tracing::info;

use tracing_subscriber::layer::SubscriberExt;
use tracing_subscriber::util::SubscriberInitExt;

fn main() {
    // Create a Jaeger Tracer
    let tracer_jaeger = opentelemetry_jaeger::new_pipeline()
        .with_service_name("infinite")
        .install_simple()
        .unwrap();

    // Create a tracing layer with the configured tracer
    let opentelemetry_layer = tracing_opentelemetry::layer()
        .with_tracer(tracer_jaeger)
        .with_threads(true);

    // Register Layers
    tracing_subscriber::registry()
        .with(opentelemetry_layer)
        .init();

    for_loop();
    infinite_loop();

    // Force all Span to be sent
    shutdown_tracer_provider();
}

#[tracing::instrument]
fn infinite_loop() {
    info!("Début de la boucle");
    let mut i = 0;
    loop {
        info!(iteration = i, "Itération");
        sleep(Duration::from_millis(1));
        i += 1;
    }
    info!("Fin de la boucle")
}

#[tracing::instrument]
fn for_loop() {
    info!("Début de la boucle");
    for i in 1..10 {
        info!(iteration = i, "Itération");
        sleep(Duration::from_millis(1));
    }
    info!("Fin de la boucle")
}

Si l’on éxécute celui-ci nous allons avoir le résultat suivant:

Contenant les différents events des itérations.

Par contre, aucune trace de la span infinite_loop.

Une span étant bornée temporellement, si celle-ci ne finit jamais, elle ne sera jamais envoyé au Tracer et par conséquent les Events qui y sont rattachés non plus.

Pour nous permettre de visualiser le comportement de notre fonctions infinite_loop. Nous allons devoir créer une span qui est bornée dans le temps et donc transmissible au Tracer.

Et finalement affichable dans Jaeger.

Pour ce faire nous allon utiliser une méthode qui se nomme in_scope.

info_span!("ma span").in_scope(||{
    info!("Dans ma span");
})

Tous les évènements qui sont déclenchés dans in_scope seront rattachés à ma span et envoyés sur Jaeger comme tel.

Remarque

Le code

info_span!("ma span").in_scope(||{
    info!("Dans ma span");
})

Est équivalent à

let span = info_span!("ma span");
{
    let _enter = span.enter();
    info!("Dans ma span");
}
drop(span);

Si drop(span) n’est pas appelé et que vous vous trouvez dans une boucle infinie.

Votre span ma span ne sera jamais envoyée!

Nous pouvons réécrire notre fonction infinite_loop ainsi:

#[tracing::instrument]
fn infinite_loop() {
    info_span!("infinite_loop").in_scope(|| {
        info!(flag = "start", "Début de la boucle");
    });

    let mut i = 0;
    loop {
        info_span!("infinite_loop").in_scope(|| {
            info!(iteration = i, "Itération");
        });

        sleep(Duration::from_millis(1));
        i += 1;
    }
    info!("Fin de la boucle")
}

Sur Jaeger nous avons désormais une span infinite_loop! 😎

Et en ouvrant son détails on peut voir que toutes les spans ayant le même nom sont regroupés sous la forme d’un bel escalier de spans.

Nous avons notre flag=start tout en haut et les iteration=N ensuite.

D’ailleurs nous pouvons créer le même genre de retour pour notre for_loop, cela permettra de visualiser le temps pris par chaque itération.

#[tracing::instrument]
fn for_loop() {
    info!("Début de la boucle");
    for i in 1..10 {
        info_span!("for_loop").in_scope(|| {
            info!(iteration = i, "Itération");
        });
        sleep(Duration::from_millis(1));
    }
    info!("Fin de la boucle")
}

Cette fois-ci sur Jaeger notre span for_loop devient:

On peut y voir les temps passés dans les in_scope de chaque itération.

Et si l’on ouvre les détails cela nous donne:

Nous avons bien nos events de début et de chaque itération.

Nous avons en prime l’event de fin car cette span est finie.

Nous pouvons également le réaliser en asynchrone.

Code Rust

use opentelemetry::global::shutdown_tracer_provider;
use std::thread::sleep;
use std::time::Duration;
use tokio::{join, spawn};
use tracing::{info, info_span};

use tracing_subscriber::layer::SubscriberExt;
use tracing_subscriber::util::SubscriberInitExt;

#[tokio::main]
async fn main() {
    // Create a Jaeger Tracer
    let tracer_jaeger = opentelemetry_jaeger::new_pipeline()
        .with_service_name("infinite")
        .install_simple()
        .unwrap();

    // Create a tracing layer with the configured tracer
    let opentelemetry_layer = tracing_opentelemetry::layer()
        .with_tracer(tracer_jaeger)
        .with_threads(true);

    // Register Layers
    tracing_subscriber::registry()
        .with(opentelemetry_layer)
        .init();

    let fut1 = spawn(for_loop());
    let fut2 = spawn(infinite_loop());

    let _ = join!(fut1, fut2);

    // Force all Span to be sent
    shutdown_tracer_provider();
}

#[tracing::instrument]
async fn infinite_loop() {
    info_span!("infinite_loop").in_scope(|| {
        info!(flag = "start", "Début de la boucle");
    });

    let mut i = 0;
    loop {
        info_span!("infinite_loop").in_scope(|| {
            info!(iteration = i, "Itération");
        });

        sleep(Duration::from_millis(1));
        i += 1;
    }
    info!("Fin de la boucle")
}

#[tracing::instrument]
async fn for_loop() {
    info!("Début de la boucle");
    for i in 1..10 {
        info_span!("for_loop").in_scope(|| {
            info!(iteration = i, "Itération");
        });
        sleep(Duration::from_millis(1));
    }
    info!("Fin de la boucle")
}

Et obtenir le même résultat dans Jaeger.

Mon Jaeger crash !

Dans certaines condition il se peut que votre Jeager crash, et qu’avant il prenne un nombre exponentiel de mémoire.

Ce cas, je l’ai observé lorsqu’un trop grand nombre de span sont envoyées en très peu de temps.

Vous risquez de vous retrouver avec ce genre de message d’erreur:

On peut aisément reproduire ce comportement grâce à ce code

fn main() {


    // Déclaration du tracing
    
    info_span!("will crash").in_scope(|| {
        for i in 0..1000000 {
            dummy(i)
        }
    });
}

#[tracing::instrument]
fn dummy(index: u64) {
    info!("I was here {}", index)
}

Celui-ci va engorger le système et finir par faire crasher le système de télémétrie.

Heureusement il est possible de régler ce soucis en configurant la manière dont les spans sont traitées.

En effet, il est possible d’affecter un niveau de log à nos spans.

#[tracing::instrument(level = "debug")]
fn dummy(index: u64) {
    debug!("I was here {}", index)
}

Par contre en l’état le système ne filtrera rien, il faut rajouter un filtre qui aura pour effet de venir conditionner le traitement ou non de notre span.

Pour en bénéficier, il faut activer une feature

cargo add tracing-subscriber --features env-filter

Ou via le Cargo.toml

tracing-subscriber = { version = "0.3.14", features = ["env-filter"] }

    // Register Layers
    tracing_subscriber::registry()
        .with(EnvFilter::from_default_env())
        .with(opentelemetry_layer)
        .init();

La 3ème ligne, indique d’utiliser la variable d’environnement standard RUST_LOG.

Ce qui signifie que l’on peut venir piloter les spans au travers d’elle.

RUST_LOG=info cargo run

Pour les besoin du test et pour des raisons de visibilité, nous allons réduire le nombre d’itérations à 10.

fn main() {


    // Déclaration du tracing
    
    info_span!("won't crash").in_scope(|| {
        for i in 0..10 {
            dummy(i)
        }
    });
}

Avec ce réglage vous allez voir dans Jaeger ceci:

Aucune span ne sera produite.

Par contre en éxécutant

RUST_LOG=debugcargo run

Vous verrez

Nous pouvons donc régler le degré de finesse de nos spans en fonction de nos besoins.

Que ce soit de la télémétrie de production ou de développement et donc du debug.

Récapitulatif de code:

Code Rust

use futures::future::join_all;
use futures::{Stream, StreamExt};
use opentelemetry::global::shutdown_tracer_provider;
use opentelemetry::runtime::Tokio;
use tracing::{debug, info_span};

use tracing_subscriber::EnvFilter;

use tracing_subscriber::layer::SubscriberExt;
use tracing_subscriber::util::SubscriberInitExt;

#[tokio::main]
async fn main() {
    // Create a Jaeger Tracer
    let tracer_jaeger = opentelemetry_jaeger::new_pipeline()
        .with_service_name("too much spans")
        .install_batch(Tokio)
        .unwrap();

    // Create a tracing layer with the configured tracer
    let opentelemetry_layer = tracing_opentelemetry::layer()
        .with_tracer(tracer_jaeger)
        .with_threads(true);

    // Register Layers
    tracing_subscriber::registry()
        .with(EnvFilter::from_default_env())
        .with(opentelemetry_layer)
        .init();

    info_span!("won't crash").in_scope(|| {
        for i in 0..10 {
            dummy(i)
        }
    });

    shutdown_tracer_provider();
}

#[tracing::instrument(level = "debug")]
fn dummy(index: u64) {
    debug!("I was here {}", index)
}

Un petit exemple concret

Nous allons réaliser un exemple qui va récapituler les différents concepts et les mettre en action dans un cas concret.

Le système que je vous propose sera un serveur web qui ira chercher des données sur un serveur distant. Et qui mettra en cache dans une base de données sqlite ces réponses de requêtes avant de servir le client.

Disclaimer

Ici le but n’est pas de créer quelque chose qui doit aller en prod, les décisions d’architectures peuvent être qualifier au mieux de discutables. 😅

Pour cela nous allons avoir besoin d’un serveur distant, nous allons utiliser la plateforme JSON placeholder qui est conçu pour cet usage.

Et plus particulièrement son service users. Qui permet de générer des données utilisateurs.

Si l’on interroge ainsi https://jsonplaceholder.typicode.com/users/1. Nous obtenons un utilisateur en particulier.

{
  "id": 1,
  "name": "Leanne Graham",
  "username": "Bret",
  "email": "Sincere@april.biz",
  "address": {
    "street": "Kulas Light",
    "suite": "Apt. 556",
    "city": "Gwenborough",
    "zipcode": "92998-3874",
    "geo": {
      "lat": "-37.3159",
      "lng": "81.1496"
    }
  },
  "phone": "1-770-736-8031 x56442",
  "website": "hildegard.org",
  "company": {
    "name": "Romaguera-Crona",
    "catchPhrase": "Multi-layered client-server neural-net",
    "bs": "harness real-time e-markets"
  }
}

Mais attention au retour de cette API, en effet tout id utilisateur supérieur à 10 renvoit un json vide mais un code de retout HTTP 200.

Afin de pouvoir manipuler ce JSON nous allons utiliser la lib serde_json qui nous impose de créer une structure pour accueillir les données.

On l’installe

cargo add serde --features derive
cargo add serde serde_json

#[derive(Deserialize, Serialize)]
struct User {
    id: u32,
    name: String,
    email: String,
    phone: String,
    website: String,
}

Ensuite pour des raisons de rapidité de mise en oeuvre, je vais utiliser un serveur actix-web.

On l’installe

cargo add actix-web

Voici le main

#[actix_web::main]
async fn main() -> std::io::Result<()> {

    HttpServer::new(|| App::new().service(get_user))
        .bind(("127.0.0.1", 8080))?
        .run()
        .await
}

Il déclare un serveur en écoute locale sur le port 8080, et possède un service get_user.

Que nous allons déclarer dès maintenant.

#[get("/user/{id}")]
async fn get_user(id: web::Path<u32>) -> HttpResponse {
    let id = id.into_inner();

    if id > 10 {
        return HttpResponse::BadRequest().json(json!({
            "message" : "User id can't exceed 10"
        }));
    }

    let user = Cache::hit(id).await;

    match user {
        Ok(user) => HttpResponse::Ok().json(user),
        Err(err) => HttpResponse::NotFound().json(json!({
           "code": 404,
            "message": err.to_string(),
        })),
    }
}

Cette méthode renvoit une BadRequest si l’id est supérieur à 10. Dans le cas contraire il utilise le cache pour récupérer l’utilisateur associer à l’id demandé.

Puis formate la réponse en erreur ou non, sous forme de JSON.

Parlons en du cache.

Celui-ci est constitué d’une base de données sqlite en local.

À chaque requête on vient ouvrir cette BDD et effectuer une opération de SELECT sur l’ID en question.

Code Rust

struct Cache;

impl Cache {

    fn init() -> Result<Connection> {
        let connection = sqlite::open("db.sqlite")?;
        connection.execute("CREATE TABLE IF NOT EXISTS users (id INTEGER , value TEXT )")?;

        Ok(connection)
    }

    fn set(user: &User) -> Result<()> {
        let connection = Self::init()?;
        let mut statement = connection.prepare("INSERT INTO users VALUES(?, ?)")?;
        let user_string = json!(user).to_string();
        statement.bind(1, user.id as i64)?;
        statement.bind(2, user_string.as_str())?;

        statement.next()?;

        Ok(())
    }

    async fn hit(key: u32) -> Result<Option<User>> {
        let connection = Self::init()?;

        let mut statement = connection.prepare("SELECT * FROM users WHERE id = ?")?;
        statement.bind(1, key as i64)?;

        match statement.next().unwrap() {
            State::Row => {
                let user_string = statement.read::<String>(1)?;
                let user = serde_json::from_str::<User>(&user_string)?;

                Ok(Some(user))
            }
            State::Done => {
                let user = fetch_user(key).await?;
                Self::set(&user)?;

                Ok(Some(user))
            }
        }
    }
}

Lors de l’opération de hit du cache, si celui-ci échoue car la valeur n’est pas encore disponible dans le cache. Celui-ci viens appeler une méthode fetch_user qui réalise l’appel sur le réseau.

async fn fetch_user(id: u32) -> reqwest::Result<User> {
    let url = format!("https://jsonplaceholder.typicode.com/users/{}", id);

    let response = reqwest::get(url).await?;
    let user = response.json::<User>().await?;

    Ok(user)
}

Comme nous utilisons un ensemble de crates différentes leurs erreurs ne vont pas être compatibles. Pour éviter ce souci, nous créons une énumération pour unifier les erreurs.

Nous utilisons aussi la crate thiserror qui permet de facilement créer les méthode de display de chacune des erreurs.

Code Rust

#[derive(Error, Debug)]
enum CustomError {
    #[error("sqlite errors {0:?}")]
    Sqlite(sqlite::Error),
    #[error("reqwest errors")]
    Reqwest(reqwest::Error),
    #[error("json errors")]
    Json(serde_json::Error),
}

impl From<sqlite::Error> for CustomError {
    fn from(err: sqlite::Error) -> Self {
        CustomError::Sqlite(err)
    }
}

impl From<serde_json::Error> for CustomError {
    fn from(err: serde_json::Error) -> Self {
        CustomError::Json(err)
    }
}

impl From<reqwest::Error> for CustomError {
    fn from(err: reqwest::Error) -> Self {
        CustomError::Reqwest(err)
    }
}

type Result<T> = std::result::Result<T, CustomError>;

Un petit récap:

Code Rust

use actix_web::{get, web, App, HttpResponse, HttpServer};
use serde::{Deserialize, Serialize};
use serde_json::json;
use sqlite::{Connection, State};
use thiserror::Error;

#[derive(Error, Debug)]
enum CustomError {
    #[error("sqlite errors {0:?}")]
    Sqlite(sqlite::Error),
    #[error("reqwest errors")]
    Reqwest(reqwest::Error),
    #[error("json errors")]
    Json(serde_json::Error),
}

impl From<sqlite::Error> for CustomError {
    fn from(err: sqlite::Error) -> Self {
        CustomError::Sqlite(err)
    }
}

impl From<serde_json::Error> for CustomError {
    fn from(err: serde_json::Error) -> Self {
        CustomError::Json(err)
    }
}

impl From<reqwest::Error> for CustomError {
    fn from(err: reqwest::Error) -> Self {
        CustomError::Reqwest(err)
    }
}

type Result<T> = std::result::Result<T, CustomError>;

#[derive(Deserialize, Serialize)]
struct User {
    id: u32,
    name: String,
    email: String,
    phone: String,
    website: String,
}

struct Cache;

impl Cache {

    fn init() -> Result<Connection> {
        let connection = sqlite::open("db.sqlite")?;
        connection.execute("CREATE TABLE IF NOT EXISTS users (id INTEGER , value TEXT )")?;

        Ok(connection)
    }

    fn set(user: &User) -> Result<()> {
        let connection = Self::init()?;
        let mut statement = connection.prepare("INSERT INTO users VALUES(?, ?)")?;
        let user_string = json!(user).to_string();
        statement.bind(1, user.id as i64)?;
        statement.bind(2, user_string.as_str())?;

        statement.next()?;

        Ok(())
    }

    async fn hit(key: u32) -> Result<Option<User>> {
        let connection = Self::init()?;

        let mut statement = connection.prepare("SELECT * FROM users WHERE id = ?")?;
        statement.bind(1, key as i64)?;

        match statement.next().unwrap() {
            State::Row => {
                let user_string = statement.read::<String>(1)?;
                let user = serde_json::from_str::<User>(&user_string)?;

                Ok(Some(user))
            }
            State::Done => {
                let user = fetch_user(key).await?;
                Self::set(&user)?;

                Ok(Some(user))
            }
        }
    }
}

#[tracing::instrument]
async fn fetch_user(id: u32) -> Result<User> {
    let url = format!("https://jsonplaceholder.typicode.com/users/{}", id);

    let response = reqwest::get(url).await?;
    let response_string = response.text().await?;
    let user = serde_json::from_str(response_string.as_str())?;

    Ok(user)
}

#[get("/user/{id}")]
async fn get_user(id: web::Path<u32>) -> HttpResponse {
    let id = id.into_inner();

    if id > 10 {
        return HttpResponse::BadRequest().json(json!({
            "message" : "User id can't exceed 10"
        }));
    }

    let user = Cache::hit(id).await;

    match user {
        Ok(user) => HttpResponse::Ok().json(user),
        Err(err) => HttpResponse::NotFound().json(json!({
           "code": 404,
            "message": err.to_string(),
        })),
    }
}

#[actix_web::main] // or #[tokio::main]
#[tracing::instrument]
async fn main() -> std::io::Result<()> {

    HttpServer::new(|| App::new().service(get_user))
        .bind(("127.0.0.1", 8080))?
        .run()
        .await
}

Ainsi que les dépendances nécessaire

[dependencies]
actix-web = "4.1.0"
reqwest = { version = "0.11.11", features = ["json"] }
serde = { version = "1.0.140", features = ["derive"] }
serde_json = "1.0.82"
mime = "0.3.16"
sqlite = "0.26.0"
thiserror = "1.0.31"

Bien! Si vous exécuter ce code vous devriez voir apparaître en vous rendant sur localhost:8080 un json avec le user id 2.

Puis en réexécutant cette même requête une réponse sensiblement plus rapide.

Mais plus rapide de combien au juste ? 🧐

La télémétrie va nous venir en aide.

Nous allons outiller nos fonctions !

D’abord le cache

impl Cache {

    #[tracing::instrument]
    fn init() -> Result<Connection> {
        // ...
    }

    #[tracing::instrument(skip(user), fields(id = user.id))]
    fn set(user: &User) -> Result<()> {
        // ...
    }

    #[tracing::instrument]
    async fn hit(key: u32) -> Result<Option<User>> {
        // ...
    }
}

Puis les autres méthodes

#[tracing::instrument]
async fn fetch_user(id: u32) -> reqwest::Result<User> {
    // ...
}


#[get("/user/{id}")]
#[tracing::instrument]
async fn get_user(id: web::Path<u32>) -> HttpResponse {
    // ...
}

Et on finit par initialiser le tracing comme il se doit.

#[actix_web::main] // or #[tokio::main]
#[tracing::instrument]
async fn main() -> std::io::Result<()> {
    // Create a Jaeger Tracer
    let tracer_jaeger = opentelemetry_jaeger::new_pipeline()
        .with_service_name("cache user")
        .install_simple()
        .unwrap();

    // Create a tracing layer with the configured tracer
    let opentelemetry_layer = tracing_opentelemetry::layer()
        .with_tracer(tracer_jaeger)
        .with_threads(true);

    // Register Layers
    tracing_subscriber::registry()
        .with(EnvFilter::from_default_env())
        .with(opentelemetry_layer)
        .init();
    
    // ...
}

Et de rajouter les dépendances nécessaires.

[dependencies]
opentelemetry = { version = "0.17.0", features = ["trace", "metrics"] }
opentelemetry-jaeger = { version = "0.16.0" }
tracing = "0.1.35"
tracing-opentelemetry = "0.17.4"
tracing-subscriber = { version = "0.3.14", features = ["env-filter"] }

Si l’on reproduit cette expérience

Si vous éxécuter ce code vous devriez en vous rendant sur [localhost:8080](https://localhost:8080/user/2) voir apparaître 
un json avec le user id 2.

Puis en réexécutant cette même requête une réponse sensiblement plus rapide.

En ayant pris soin de supprimer la base de données sqlite.

Vous devriez avoir les spans suivantes:

On observe un facteur x100 entre la requête du dessous et celle du dessus.

Bien évidemment, celle du dessus est la requête avec cache et celle du dessous sans cache.

Voyons ces spans en détails.

Tout d’abord sans le cache.

On voit bien l’ordonnencement des actions

  

flowchart LR
get_user-->Cache::hit-->fetch-->Cache::set

On peut d’ailleurs détailler l’exécution grâce aux tags de nos spans.

On voit bien l’ID 2 être baladé dans les différents appels de fonctions.

Et maintenant si on réitère l’opération avec le cache déjà rempli.

On a beacoup moins de spans dont une absence de fetch_user, donc pas d’appel réseau donc pas 100 ms dans la vue en allant rechercher l’info sur le web !!

Notre appel se résume à un simple:

  

flowchart LR
get_user-->Cache::hit

Pour ceux qui en ont besoin je vous met le code ici.

Conclusion

J’espère que cette très légère introduction à la télémétrie vous aura plu.

En écrivant cet article, je n’ai pu que constater le gouffre insondable de mon ignorance et le chemin qui me reste à parcourir pour commencer à maîtriser le sujet.

Voyez cet article comme une sorte d’état de l’art de mes connaissances à l’instant présent.

Je vous remercie de votre lecture et vous donne rendez-vous pour autre chose dans un autre article. ❤️

Centraliser et normaliser ses logs avec Vector

2021-09-14T00:00:00+00:00

Bonjour! 😀

Mon nombre de VMs a explosé au cours de ces derniers mois. Je ne m’en plains pas, mais il devient de plus en plus fastidieux d’aller consulter mes logs.

Un autre de mes problèmes est que mon infra est constituée de programmes écrits dans différents langages qui ont chacun leur manière de rédiger leurs logs.

Une autre complication est l’utisation de Docker et Kubernetes qui enrobe les processus et rajoute une couche de complexité dans la compréhension du run des applications.

J’avais tout d’abord commencé à regarder le produit “Syslog” qui a fait ces preuves. Mais celui-ci ne convenait pas à mes besoins car les messages générés contenanaient trop d’informations parasites, ne permettant pas leur exploitation directe.

C’est alors que durant un de mes lives sur twitch l’un de mes spectateurs m’a indiqué l’existence d’un produit nommé Vector.

Installation

Vector est un binaire qui peut-être installé de diverses manières.

Je vais utiliser la méthode de l’installation par package.

curl -1sLf \
  'https://repositories.timber.io/public/vector/cfg/setup/bash.deb.sh' \
| sudo -E bash
apt install vector

Principes de fonctionnement

Vector possède une architecture fonctionnelle plutôt directe.

Il peut prendre une ou plusieurs de sources de données, réaliser une suite de transformations sur ces évènements puis les distribuer vers une ou plusieurs sorties.

L’ensemble de ce processus est appelé un pipeline.

Il est décrit dans un fichier de configuration utilisant le langage de description TOML. On peut le faire en YAML et en JSON mais ne parlons pas des sujets qui fâchent. 😁

Sources

Les entrées du pipeline sont appelées des sources.

Vector vous proposent un vaste choix de sources qui vont des plus haut-niveau comme directement se connecter à l’API Docker pour récupérer les logs des containers à des choses bien plus bas-niveau comme la lecture de socket ou de fichiers.

Une source est défini ainsi:

[source.ma_source]
type = "type de la source"

Vous pouvez définir autant de sources que vous le désirez.

L’identifiant ma_source est le nom de votre entrée et permettra de l’identifier au sein du pipeline.

Une source a pour sortie un évènement sous la forme d’un message au format JSON. Chaque source possède sa structure de sortie qui est documentée pour chacune d’elle.

Transformations

Chaque source peut bénéficier d’une ou plusieurs transformations. Les transformations sont des opérations qui sont réalisées sur les évènements provenant des sources.

Une transformation peut prendre une ou plusieurs sources.

De même que pour les sources, Vector propose là aussi des transformations déjà existantes.

Une transformation se décrit sous cette forme.

[transforms.ma_transformation]
type = "type de la transformation"
inputs = ["ma_source_1", "ma_source_2"]

Le champ inputs est la collection de flux d’entrées définis par un ou plusieurs identifiants.

Il est aussi possible de chaîner les transformations pour rafiner les traitements.

[transforms.ma_transformation]
type = "type de la transformation"
inputs = ["ma_source_1", "ma_source_2"]

[transforms.ma_transformation_2]
type = "type de la transformation"
inputs = ["ma_transformation"]

Remap

Dans les transformations, il en existe une qui est plus spéciale que les autres. Il s’agit de la transformation remap.

Celle ci a un format un peu différent qui prend un paramètre source.

Dans celui ci, il est possible de définir des transformations personnalisées au moyen d’un langage de manipulation de données appelé le VRL.

Ce langage est ensuite converti en du Rust, permettant de bénéficier de toutes les garanties concernant le typage des données manipulé ainsi que la faillibilité des appels de fonctions et de routines de traitement.

Le langage est complet et propose tous les outils nécessaire comme l’affectatation de variable, la notion de condition, ainsi que de contextes et de blocs.

Sinks

Dans la terminologie de Vector les sorties de pipelines sont appelés des sinks.

De même une sélection de sinks pré-construits existe.

Un sink prend une collection de flux d’événements et les délivre à sa destination.

Votre pipeline peut posséder autant de sinks que vous désirez et chaque sinks prend autant d’entrées que voulu.

[sinks.ma_sortie]
type = "type de ma sortie"
inputs = ["ma_source", "ma_transformation"]

Cas pratique

Cahier des charges

Mon cas d’utilisation est le suivant. Je possède une série de VMs qui tournent à l’intérieur d’un réseau.

Chacune de ces VMs possède une stack Docker décrite par un docker-compose.

Le but est de centraliser les logs de toutes ces VMs, en les regroupant par container et par jours.

Par exemple si nous avons 2 machines appelées respectivement:

docker-001
docker-002

Et possédant chacune le docker-compose suivant:

services:
  tomcat:
    image: tomcat
  jetty:
    image: jetty
  js:
    image: custom-js

Alors l’aborescence de logs finaux devra ressembler à :

logs
└── by-host
    ├── docker-001
    │   └── docker
    │       ├── json
    │       │   ├── tomcat
    │       │   │   ├── 13-09-2021.log
    │       │   │   └── 14-09-2021.log
    │       │   ├── jetty
    │       │   │   ├── 13-09-2021.log
    │       │   │   └── 14-09-2021.log
    │       │   └── js
    │       │       ├── 13-09-2021.log
    │       │       └── 14-09-2021.log
    │       └── text
    │           ├── tomcat
    │           │   ├── 13-09-2021.log
    │           │   └── 14-09-2021.log
    │           ├── jetty
    │           │   ├── 13-09-2021.log
    │           │   └── 14-09-2021.log
    │           └── js
    │               ├── 13-09-2021.log
    │               └── 14-09-2021.log
    └── docker-002
        └── docker
            ├── json
            │   ├── tomcat
            │   │   ├── 13-09-2021.log
            │   │   └── 14-09-2021.log
            │   ├── jetty
            │   │   ├── 13-09-2021.log
            │   │   └── 14-09-2021.log
            │   └── js
            │       ├── 13-09-2021.log
            │       └── 14-09-2021.log
            └── text
                ├── tomcat
                │   ├── 13-09-2021.log
                │   └── 14-09-2021.log
                ├── jetty
                │   ├── 13-09-2021.log
                │   └── 14-09-2021.log
                └── js
                    ├── 13-09-2021.log
                    └── 14-09-2021.log

Notre but va être de construire une topologie de centralisation et de normalisation de logs qui réponde à ce besoin.

Nous utiliseront bien évidemment Vector pour la plupart des opérations.

Descriptif des contraintes

Tomcat et Jetty sont des serveurs HTTP écrits tous les deux en Java mais ne génèrent pas leur logs sous le même format.

Une ligne de log Tomcat ressemblera à :

14-Sep-2021 06:48:31.489 INFO [main] org.apache.catalina.startup.Catalina.start Server startup in [102] milliseconds

Alors que Jetty renverra plutôt des messages de logs ainsi:

2021-09-14 06:48:34.560:INFO:oejs.AbstractConnector:main: Started ServerConnector@11245489{HTTP/1.1, (http/1.1)}{0.0.0.0:8080}

Nous avons aussi dans notre stack une application NodeJs qui possède de même, sa propre façon de créer ses logs.

Vous pouvez retrouvez dans ce projet les sources de l’image NodeJS.

Cette image écrira ses logs sous cette forme:

2021-09-14T06:52:52.480Z [main] info: Application started

Comme vous pouvez le voir chacun de ces logs signifie que l’application a démarré mais aucune de ces lignes n’est identique d’un container à un autre, ce qui complexifie grandement le traitement des logs de notre stack Docker.

Nous allons devoir normaliser tout ça! 😀

Une autre contrainte est que les stacks Docker sont séparées les unes des autres dans des VMs pour des raisons de sécurité et scalabilité.

Il va donc falloir rappatrier ces logs normalisés au niveau d’un point unique qui se chargera de leur aggrégation.

Topologie

Une des règles que nous allons essayer de nous astreindre est de ne pas générer inutilement de SPOF.

Ceci signifie que la stack Docker doit-être à même de fonctionner lorsque le pipeline de logs est defectueux.

Donc avant d’être poussé vers l’aggrégateur, les logs normalisés seront conservés sur les VMs et régulièrement effacés par un logrotate.

Récupérer les logs de ses containers

La première difficulté à laquelle nous allons être confronté, est de pouvoir récupérer les logs qui sont générés par les applications encapsulées dans les containers.

Vector possède une source Docker mais de l’aveu même de la documentation, il est fortement déconseillé de l’utiliser.

Nous allons donc devoir trouver une manière détournée de récupérer ces logs.

Heureusement, Docker nous fourni une série de manières de réaliser cette extraction.

Notre cahier des charges nous impose plusieurs contraintes. Il ne faut pas qu’un défaut dans le système de pipeline de logs n’interdise le fonctionnement de la stack Docker.

Cette difficulté exclut d’emblée tous les systèmes d’envoie de logs par protocole réseau. En effet si le pipeline décède ou est innacessible, les containers ne démarreront pas.

Les éliminés sont donc:

syslog en réseau
fluentd
splunk en réseau
graylog
logentries

On peut aussi sortir les drivers spécifiques au GAFAM: AWS et GCP.

ETW étant pour windows, il ne nous aidera pas non plus sur le coup.

Il nous reste les stockages de logs locaux:

local
json-file
journald

Local est trop simple et ne permet pas de gérer les métadata. Et le stockage JSON ne permet pas une recherche efficace en local.

Nous allons donc nous tourner vers un stockage de logs en utilisant journald.

Pour plus d’informations:

Comme expliqué dans ces ressources, la grande force de journald est de permettre le stockage des méta-données des messages à des fins de filtrages.

Examinons tout d’abord ce que nous fourni le driver de logging journald de Docker.

En plus du message, nous avons accès à plusieurs meta-data, dont:

CONTAINER_ID
SYSLOG_IDENTIFIER ou CONTAINER_TAG
IMAGE_NAME non documenté mais présent dans mes expérimentations

Ceci constituera nos logs brutes.

En plus de ces méta-data propres au driver docker. Il existe une série de méta-datas constitutive du protocole journald dont la liste exhaustive est définie dans l’exemple suivant.

Ceux qui vont particulièrement nous intéresser sont:

host
timestamp
__REALTIME_TIMESTAMP, le timestamp en microsecondes

Configurons nos container pour envoyer leur logs vers journald.

version: '3.7'

services:
  tomcat:
    image: tomcat
    logging:
      driver: journald
      options:
        tag: "java"
  jetty:
    image: jetty
    logging:
      driver: journald
      options:
        tag: "java"
  js:
    image: custom-js
    logging:
      driver: journald
      options:
        tag: "js"

Nous rajoutons un tag qui nous permettra de traiter les messages plus facilement. Cette valeur sera définie dans la méta-donnée SYSLOG_IDENTIFIER.

Nous pouvons maintenant commencer la création de notre pipeline 😁

Pour cela crée un fichier docker_logs_pipeline_normalization.toml

[sources.journald_docker_unit]
type = "journald"
include_units = ["docker"]
data_dir = "${PWD}/data"

journald_docker_unit sera l’identifiant de notre source. Puis on définit cette source comme étant du type journald.

On filtre par seulement l’unit docker et on défini un dossier qui contiendra le checkpoint de lecture du journal.

Ceci permet de ne pas retraiter plusieurs fois les même logs.

Normaliser les évènements

Nous allons normaliser cet évènement pour le rendre moins spécifique à docker. Ceci nous permettra dans l’avenir de plus facilement gérer d’autres sources.

Pour cela nous allons utiliser notre première transformation.

[transforms.normalized_journald_docker_events]
inputs = ["journald_docker_unit"]
type = "remap"
source = '''
service_identifier = .IMAGE_NAME+"/"+.CONTAINER_ID ?? "unknown"
. = {
    "message" : .message,
    "timestamp": .timestamp,
    "unix_timestamp" : .__REALTIME_TIMESTAMP,
    "hostname" : .host,
    "meta" : {
        "type" : "docker",
        "image" : .IMAGE_NAME,
        "container_id" : .CONTAINER_ID,
        "log_topology" : .SYSLOG_IDENTIFIER
    }
}
.service_identifier = service_identifier
'''

Cette transformation prend un évènement du type:

{
  "CONTAINER_ID":"306bbf1dd696",
  "CONTAINER_ID_FULL":"306bbf1dd69616a0435dec35fa2e3a7d73725915e7cd9f331f5da90dafd400f9",
  "CONTAINER_NAME":"docker_tomcat_1",
  "CONTAINER_TAG":"java",
  "IMAGE_NAME":"tomcat",
  "PRIORITY":"6",
  "SYSLOG_IDENTIFIER":"java",
  "_BOOT_ID":"79f4683a192e41218842e2c683972993",
  "_CAP_EFFECTIVE":"3fffffffff",
  "_CMDLINE":"/usr/bin/dockerd -H fd:// --containerd=/run/containerd/containerd.sock",
  "_COMM":"dockerd",
  "_EXE":"/usr/bin/dockerd",
  "_GID":"0",
  "_MACHINE_ID":"c9f961f08f12487d833a6198ff3d4ffe",
  "_PID":"966",
  "_SELINUX_CONTEXT":"unconfined\n",
  "_SOURCE_REALTIME_TIMESTAMP":"163182514785904",
  "_SYSTEMD_CGROUP":"/system.slice/docker.service",
  "_SYSTEMD_INVOCATION_ID":"fc3ebfb5002d41eb9d0e364f60610d94",
  "_SYSTEMD_SLICE":"system.slice",
  "_SYSTEMD_UNIT":"docker.service",
  "_TRANSPORT":"journal",
  "_UID":"0",
  "__MONOTONIC_TIMESTAMP":"254749478898",
  "__REALTIME_TIMESTAMP":"1631825147859",
  "host":"docker-001.example.com",
  "message":"16-Sep-2021 20:45:47.859 INFO [main] org.apache.catalina.startup.Catalina.start Server startup in [146] milliseconds",
  "source_type":"journald",
  "timestamp":"2021-09-16T20:45:47.859335Z"
}

Et le transforme en un document de ce type:

{
   "hostname":"docker-001.example.com",
   "message":"16-Sep-2021 20:45:47.859 INFO [main] org.apache.catalina.startup.Catalina.start Server startup in [146] milliseconds",
   "meta":{
      "container_id":"306bbf1dd696",
      "image":"tomcat",
      "log_topology":"java",
      "type":"docker"
   },
   "service_identifier":"tomcat/306bbf1dd696",
   "timestamp":"2021-09-16T20:45:47.859335Z",
   "unix_timestamp":1631825147859
}

De cette manière les logs peuvent venir de n’importe quel service on ne conserve, les traces de docker que dans les méta-données de l’évènement.

Router les messages

En fonction du type d’application qui produit le log, nous devons effectuer des traitements différents.

Pour se faire, nous allons diviser le flux de messages en fonction qu’il vienne d’une application Java ou NodeJs.

Nous allons utiliser une autre transformation: le routing.

[transforms.split_stream_by_log_topology]
type = "route"
inputs = ["normalized_journald_docker_events"]

    [transforms.split_stream_by_log_topology.route]
    js = '.meta.log_topology == "js"'
    java = '.meta.log_topology == "java"'

Cette transformation créé deux flux, un contenant tous les messages qui ont comme identifiant le tag java et un autre avec le tag js.

Extraire les données des messages de logs

Pour le moment nos messages de logs sont trop bruts pour pouvoir être exploités par un système automatisé.

Il faut extraire les informations de celui-ci.

Généralement les bibilothèques de log dans les différents langages de programmation permettent de définir la sévérité des messages (INFO, WARN, ERROR, FATAL) ainsi que la partie de code qui a produit ce log.

Nous allons tenter d’extraire ces données.

Les logs Java

Nous avons deux types de containers; du Jetty et du Tomcat. Chacun d’eux à sa façon propre de gérer ses logs.

Une ligne de log Tomcat ressemblera à:

13-Sep-2021 05:47:49.513 INFO [main] org.apache.coyote.AbstractProtocol.init Initializing ProtocolHandler ["http-nio-8080"]

Alors que Jetty générera plutôt ceci:

2021-09-13 05:47:47.584:INFO:oejs.AbstractConnector:main: Started ServerConnector@41dddee8{HTTP/1.1, (http/1.1)}{0.0.0.0:8080}

Nous allons utiliser une autre transformation remap pour réaliser ce travail. Le VRL propose tout une série de parsers déjà intégrés.

Malheureusement, aucun d’eux n’est adapté aux logs tel que définis par mes containers.

Il faut donc se rabattre sur nos bonne vieilles regexp. 😛

Voici la transformation que je vous propose, il y aurait surement des axes d’améliorations possibles.

[transforms.parse_message_body_java]
inputs = ["split_stream_by_log_topology.java"]
type = "remap"
source = '''
    structured = parse_regex(.message, r'^\d{2}-\w{3}-\d{4}\s(?:\d{2}:){2}\d{2}.\d{3}\s(?P<severity>\w+)\s\[[\w-]+\]\s(?P<path>[^\s]+)\s(?P<message>.*)$') ??
                 parse_regex(.message, r'^\d{4}-\d{2}-\d{2}\s(?:\d{2}:){2}\d{2}.\d{3}:(?P<severity>\w+):(?P<path>[\w\.-]+):(?P<section>[\w-]+):\s(?P<message>.*)$') ??
                 { "message": .message }
    .message_extracted = structured.message
    .path = structured.path
    .severity = "info"

    if is_string(.severity) {
        .severity = downcase(.severity)
    }
'''

Un mot sur la création de la variable structured. Elle est constituée de plusieurs parties.

Si on schématise cela donne:

structured = A ?? B ?? default

A et B sont appelés des fonctions faillibles, cela signifie que lorsque qu’elle échoue une action doit être entreprise.

Il existe plusieurs moyen de gérer la faillibilité d’une fonction.

La première est de la rendre infaillible en ajoutant un !.

structured = A!

Dans ce cas si une erreur survient, le message est abandonné et ne continuera pas dans le pipeline. C’est la manière la plus rapide de gérer les erreurs mais la plus propre. c’est l’équivalant de lever une exception dans le code.

Une deuxième solution est de traiter l’erreur à la manière de Golang en analysant l’erreur retournée.

structured, err = A

if err != null {
  # on traite l'erreur
}

Le VRL possède son propre système de codes d’erreur.

La troisième et dernière solution qui est à mon avis la plus propre, est la coalescence, il s’agit d’un opérateur qui permet de chaîner des fonctions faillibles.

structured = A ?? B ?? default

Ici, si A échoue alors on éxécute B et si B échoue alors on prend la valeur de default. default doit absolument être infaillible sinon ça ne compilera pas.

Dans notre cas l’idée est d’essayer de parser le corps du message en supposant qu’il s’agit d’un message Tomcat. Si la regex ne match pas, la fonction parse_regex échoue et l’on passe au parse de message Jetty. Et si ça échoue aussi on créé un document par défaut qui ne contient que le message.

Nous allons utiliser ce système de gestion d’erreurs pour gérer plusieurs types de formats de logs au sein d’une même transformation.

13-Sep-2021 05:47:49.513 INFO [main] org.apache.coyote.AbstractProtocol.init Initializing ProtocolHandler ["http-nio-8080"]

2021-09-13 05:47:47.584:INFO:oejs.AbstractConnector:main: Started ServerConnector@41dddee8{HTTP/1.1, (http/1.1)}{0.0.0.0:8080}

Vont respectivement donner ces valeurs à la variable structured:

{"message":"Initializing ProtocolHandler [\"http-nio-8080\"]","severity":"INFO","path":"org.apache.coyote.AbstractProtocol.init"}
{"message":"Started ServerConnector@41dddee8{HTTP/1.1, (http/1.1)}{0.0.0.0:8080}","severity":"INFO","path":"oejs.AbstractConnector"}

On en profite pour normaliser la sévérité du log. Mais on doit prendre quelques précautions. En effet, toutes les lignes ne posséderont pas de sévérité. Or la méthode VRL downcase prend exclusivement des chaîne de caractères comme paramètre d’entrée.

Comme on peut le voir les données sont extraites et normalisées sous une forme commune qui facilite leur traitement ultérieur.

Finalement la sortie finale sera:

{
   "hostname":"docker-001.example.com",
   "message":"16-Sep-2021 20:45:47.859 INFO [main] org.apache.catalina.startup.Catalina.start Server startup in [146] milliseconds",
   "message_extracted":"Server startup in [146] milliseconds",
   "meta":{
      "container_id":"306bbf1dd696",
      "image":"tomcat",
      "log_topology":"java",
      "type":"docker"
   },
   "path":"org.apache.catalina.startup.Catalina.start",
   "service_identifier":"tomcat/306bbf1dd696",
   "severity":"info",
   "timestamp":"2021-09-16T20:45:47.859335Z",
   "unix_timestamp":1631825147859
}

Les logs NodeJs

De la même manière que pour les logs venant des containers java. Nous allons utiliser une transformation qui va venir extraire les données venant de nos lignes de logs.

[transforms.parse_message_body_js]
type = "remap"
inputs = ["split_stream_by_log_topology.js"]
source = '''
    structured = parse_regex(.message, r'^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}.\d{3}Z\s\[(?P<path>[\w_/-]+)\]\s(?P<severity>\w+):\s(?P<message>.*)$') ??
                { "message": .message }
    .message_extracted = structured.message
    .path = structured.path
    .severity = "info"

    if is_string(.severity) {
        .severity = downcase(.severity)
    }
'''

Pour rappel un log NodeJs de notre application ressemble à:

2021-09-14T06:52:52.480Z [main] info: Application started

Après transformation:

{
   "hostname":"docker-001.example.com",
   "message":"2021-09-16T20:45:45.357Z [main] info: Application started",
   "message_extracted":"Application started",
   "meta":{
      "container_id":"2ccdfff60bd2",
      "image":"js",
      "log_topology":"js",
      "type":"docker"
   },
   "path":"main",
   "service_identifier":"js/2ccdfff60bd2",
   "severity":"info",
   "timestamp":"2021-09-16T20:45:45.357827Z",
   "unix_timestamp":1631825145357
}

On a ici aussi fait en sorte que les messages aient des topologies identiques. Nous pourrons désormais traiter de manière unique les logs venant du Java et du NodeJS.

Exporter nos logs normalisés vers l’aggrégateur

Jusqu’à présent nous avons normalisé nos logs mais il reste toujours sur notre machine, nous ne résolvons toujours pas le souci de la centralisation des logs.

Nous allons devoir les exporter vers une destination qui se chargera de leur aggrégation.

Et quoi de mieux que d’envoyer vers un autre pipeline Vector! 😀

Ce choix technique nous permettra de pouvoir réaliser tous les post-traitements voulus. Au contraire de les envoyer directement dans un store comme Elasticsearch ou autre.

Pour cela nous allons utiliser un sink Vector.

Sur la machine contenant la stack docker dont on veut extraire les logs,

on rajoute au pipeline:

[sinks.vector_aggregator]
type = "vector"
inputs = ["parse_message_body_java", "parse_message_body_js"]
address = "192.168.9.63:9000"
version = "1"

Nous allons cette fois-ci prendre 2 flux en entrée, les messages java et NodeJs extraits et normalisés.

En suite on définit l’addresse de notre instance Vector qui sert d’aggrégateur.

Et c’est tout 😁

Vous pouvez désormais envoyer d’une multitude de noeuds vos logs vers un point central.

Définition du pipeline d’aggrégation

Je vous ai dit que nous allions pousser nos logs vers un autre Vector, lui aussi va avoir besoin d’une configuration.

Créons un fichier aggregator.toml

Tout d’abord la source, une source Vector.

[sources.vector_server]
type = "vector"
address = "0.0.0.0:9000"
version = "1"

On écoute sur le port 9000.

Étant donné qu’il s’agit juste de démontrer la faisabilité de la centralisation des logs. Nous allons nous contenter d’une simple sortie fichier. Mais il est bien évidemment possible de faire des choses bien plus complexes, incluant des transformations, des aggrégations et des réductions.

Déclarons donc un sink File.

[sinks.file_json_output]
inputs = ["vector_server"]
type = "file"
encoding = "ndjson"
path = "./logs/by-host/{{ hostname }}/{{ meta.type }}/json/{{ service_identifier }}/%Y-%m-%d.log"

Nous allons définir un autre sinks, qui nous permettra de lire les logs comme si nous étions dans le stdout/err de l’application.

[sinks.file_text_output]
inputs = ["vector_server"]
type = "file"
encoding = "text"
path = "./logs/by-host/{{ hostname }}/{{ meta.type }}/text/{{ service_identifier }}/%Y-%m-%d.log"

Lift-off ! 🚀

On a tous nos pipelines! Il est temps de lancer tout ça! 😁

Tout d’abord, installez Vector sur tout vos serveurs, aussi bien ceux qui contiendront les stack dont on veut récupérer les logs que le noeud d’aggrégation.

Copiez y respectivement les fichiers docker_logs_pipeline_normalization.toml et aggregator.toml.

Lancez dans l’ordre

vector --config aggregator.toml

Puis

vector --config docker_logs_pipeline_normalization.toml

Si vous faites l’inverse vous aurez une erreur car le pipeline d’extraction de logs essaie de se connecter au port 9000. Or celui n’est pas encore en écoute.

Ceci me permet de vous prévenir que si votre réseau n’est pas suffisamment stable, il se peut que des problèmes de connectivité apparaissent et des erreurs surviennent.

Ceci avait motivé notre choix dès le début de confier la gestion des logs en premier lieu à journald puis à Vector. Si Vector tombe les logs ne seront pas perdu et la stack Docker continuera de tourner comme si de rien n’était.

D’une manière général, un couplage faible entre systèmes est toujours a préféré lorsque que les contraintes le permettent. Ici par exemple nous avons perdu en réactivité mais gagné en résillience. Tout est une histoire de balance entre performance et sécurité, c’est un peu la définition de l’ingéniérie. 😁

Maintenant si vous lancez vos docker-compose up, vous devriez voir les fichiers de logs apparaître sur votre noeud d’aggrégation.

On résume

Il est temps de faire le bilan.

On possède deux pipelines:

docker_logs_pipeline_normalization.toml

[sources.journald_docker_unit]
type = "journald"
include_units = ["docker"]
data_dir = "${PWD}/data"

[transforms.normalized_journald_docker_events]
inputs = ["journald_docker_unit"]
type = "remap"
source = '''
    service_identifier = .IMAGE_NAME+"/"+.CONTAINER_ID ?? "unknown"
    . = {
        "message" : .message,
        "timestamp": .timestamp,
        "unix_timestamp" : .__REALTIME_TIMESTAMP,
        "hostname" : .host,
        "meta" : {
            "type" : "docker",
            "image" : .IMAGE_NAME,
            "container_id" : .CONTAINER_ID,
            "log_topology" : .SYSLOG_IDENTIFIER
        }
    }
    .service_identifier = service_identifier
'''

[transforms.split_stream_by_log_topology]
type = "route"
inputs = ["normalized_journald_docker_events"]

    [transforms.split_stream_by_log_topology.route]
    js = '.meta.log_topology == "js"'
    java = '.meta.log_topology == "java"'


[transforms.parse_message_body_java]
inputs = ["split_stream_by_log_topology.java"]
type = "remap"
source = '''
    structured = parse_regex(.message, r'^\d{2}-\w{3}-\d{4}\s(?:\d{2}:){2}\d{2}.\d{3}\s(?P<severity>\w+)\s\[[\w-]+\]\s(?P<path>[^\s]+)\s(?P<message>.*)$') ??
                 parse_regex(.message, r'^\d{4}-\d{2}-\d{2}\s(?:\d{2}:){2}\d{2}.\d{3}:(?P<severity>\w+):(?P<path>[\w\.-]+):(?P<section>[\w-]+):\s(?P<message>.*)$') ??
                 { "message": .message }
    .message_extracted = structured.message
    .path = structured.path
    .severity = "info"

    if is_string(.severity) {
        .severity = downcase(.severity)
    }
'''

[transforms.parse_message_body_js]
type = "remap"
inputs = ["split_stream_by_log_topology.js"]
source = '''
    structured = parse_regex(.message, r'^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}.\d{3}Z\s\[(?P<path>[\w_/-]+)\]\s(?P<severity>\w+):\s(?P<message>.*)$') ??
                { "message": .message }
    .message_extracted = structured.message
    .path = structured.path
    .severity = "info"

    if is_string(.severity) {
        .severity = downcase(.severity)
    }
'''

[sinks.vector_aggregator]
type = "vector"
inputs = ["parse_message_body_java", "parse_message_body_js"]
address = "192.168.9.63:9000"
version = "1"

aggregator.toml

[sources.vector_server]
type = "vector"
address = "0.0.0.0:9000"
version = "1"

[sinks.file_json_output]
inputs = ["vector_server"]
type = "file"
encoding = "ndjson"
path = "./logs/by-host/{{ hostname }}/{{ meta.type }}/json/{{ meta.type }}/{{ service_identifier }}/%Y-%m-%d.log"

[sinks.file_text_output]
inputs = ["vector_server"]
type = "file"
encoding = "text"
path = "./logs/by-host/{{ hostname }}/{{ meta.type }}/text/{{ service_identifier }}/%Y-%m-%d.log"

L’intégralité des sources peut-être retrouvé sur le projet.

Petits dessins parce que c’est cool les dessins. 😉

Voici ce qui se passe schématiquement sur un noeud.

Les applications crachent leurs logs sur journald.

Vector vient lire journald pour en extraire les lignes de logs.

Normalise et extrait les informations pertinentes puis retransmet par réseau à un autre Vector.

Les logs normalisés des différents noeuds transitent par réseau vers notre aggrégateur.

Nous pouvous tout à fait créer des docker-003, 004, ou 100. La topologie restera la même.

Tant que votre réseau tient le traffic et que votre noeud d’aggrégation aussi il n’y aura pas de souci.

Si votre trafic devient trop important, il faudra peut-être penser à une topologie différente qui fera apparaitre un broker de messages qui tiendra lieu de buffer pour gérer la back-pressure de votre traffic de logs.

Conclusion

Cet article est le premier d’une série sur l’Observabilité, une discipline de l’informatique qui se base sur plusieurs concepts dont la gestion des logs.

Nous avons fait que la moitié du chemin concernant l’étude de nos logs, nous les avons normalisés et centralisés mais pas encore traités et rendus intelligents.

Dans la suite des articles, nous tenteront de définir une logique de recherche de logs permettant la détection et la résolution de bugs.

Je n’ai pas encore décidé de la technologie qui sera mis en place mais peut-être un couple Elasticsearch-Kibana ou des produits plus exotiques comme Loki.

J’espère que cette petite présentation des bases de la réalisation d’un système de pipeline de logs vous a plu et l’on se dit à plus tard pour la suite de nos aventures dans le monde merveilleux normalisé et automatisé de l’Observabilité! 🤩

Merci de m’avoir lu! 💖