Envoyer des logs avec une bibliothèque de logs - Rust - gelf_logger et log4rs-gelf

Objectif

Ce guide explique comment envoyer vos logs vers Logs Data Platform depuis Rust, à l'aide de deux bibliothèques différentes. Utilisez celle que vous préférez.

Rust dispose d'une implémentation de journalisation (log) largement utilisée. OVHcloud a implémenté ce système pour prendre en charge le format GELF :

• gelf_logger : un logger minimaliste.
• log4rs-gelf : basé sur gelf_logger, cette implémentation est compatible avec le framework configurable et complexe log4rs.

Ces loggers vont :

• sérialiser les entrées de log à l'aide de la crate serde_gelf.
• mettre en mémoire tampon le résultat.
• envoyer les logs par lots sur le réseau via TCP/TLS.
• veiller à ce que les champs respectent les conventions de nommage LDP.

Prérequis

Pour suivre ce guide, vous aurez besoin de :

• Rust. Nous recommandons la dernière version stable.
• Un compte Logs Data Platform activé.
• Créer au moins un flux et récupérer son jeton.
• Installer la crate serde avec la fonctionnalité derive.
• Installer la crate log avec la fonctionnalité serde.

En pratique

Première méthode : gelf_logger

Vous pouvez installer la crate gelf_logger en ajoutant la dépendance à votre Cargo.toml :

[dependencies]
gelf_logger = { version = "0.3.0", features = ["ovh-ldp"] }

Autrement, la commande cargo suivante permet de l'installer :

$ cargo add gelf_logger -F ovh-ldp

Voici un fichier main.rs complet montrant comment utiliser l'API log et gelf_logger.

use gelf_logger::{
    gelf_alert, gelf_critical, gelf_debug, gelf_emergency, gelf_error, gelf_info, gelf_log,
    gelf_notice, gelf_warn, Builder, GelfLevel,
};
use log::{error, info, warn, LevelFilter};
use serde::Serialize;

#[derive(Serialize, Debug)]
struct Request<'a> {
    id: u16,
    method: &'a str,
    path: &'a str,
}

fn main() {
    Builder::new()
        .filter_level(LevelFilter::Info)
        .ovh_ldp(
            "`<YOUR-LDP-CLUSTER-ADDRESS>`".to_owned(),
            "`<YOUR-WRITE-TOKEN>`".to_owned(),
        )
        .init();

    // basic logs
    info!("hello from rust");

    // Basic key-value logs.
    info!(count = 5; "packet received");
    warn!(user = "foo"; "unknown user");
    error!(err:err = "abc".parse::`<u32>`().unwrap_err(); "parse error");

    let req = Request {
        id: 42,
        method: "GET",
        path: "/login",
    };
    // Sera sérialisé sous forme de chaîne `Debug`.
    info!(req:?; "incoming request");
    // Aplatit tous les champs et les ajoute comme champs supplémentaires.
    info!(req:serde; "incoming request flattened");

    // Gelf specific levels.
    gelf_log!(GelfLevel::Emergency, foo = "bar"; "an emergency log");
    gelf_emergency!(foo = "bar"; "an emergency log");
    gelf_alert!(foo = "bar"; "an alert log");
    gelf_critical!(foo = "bar"; "a critical log");
    gelf_error!(foo = "bar"; "an error log");
    gelf_warn!(foo = "bar"; "a warn log");
    gelf_notice!(foo = "bar"; "a notice log");
    gelf_info!(foo = "bar"; "an info log");
    gelf_debug!(foo = "bar"; "a debug log");

    // Flush underlying TCP socket.
    // Ceci ne fait que vider le tampon. Le socket peut être fermé sans arrêt propre.
    log::logger().flush();
}

N'oubliez pas de remplacer le placeholder <YOUR-LDP-CLUSTER-ADDRESS> par le cluster où réside votre flux. Il n'est pas nécessaire d'indiquer le port GELF. Exemple : « gra3.logs.ovh.com ».

N'oubliez pas de remplacer le placeholder <YOUR-WRITE-TOKEN> par la valeur réelle du jeton d'écriture de votre flux.

Vous pouvez également consulter la documentation de l'API générée.

Seconde méthode : log4rs-gelf

Cette méthode est une alternative à la précédente. Considérez ce qui suit comme un projet Rust distinct. Vous devez être familier avec le framework log4rs.

Installez log4rs et log4rs-gelf dans votre projet Rust.

Voici le fichier Cargo.toml modifié :

[dependencies]
log = { version = "0.4.22", features = ["serde"] }
log4rs = "1.3.0"
log4rs-gelf = { version = "0.1.4", features = ["ovh-ldp"] }
serde = { version = "1.0.204", features = ["derive"] }

Autrement, utilisez les commandes cargo suivantes :

$ cargo add log4rs

$ cargo add log4rs-gelf -F ovh-ldp

Exemples

À partir d'un fichier de configuration YAML

Copiez le contenu de ce fichier yaml dans un fichier log4rs.yaml. Ce fichier sera récupéré par le programme Rust pour configurer le framework.

appenders:
  stdout:
    kind: console
  ldp:
    additional_fields:
      X-OVH-TOKEN: `<YOUR-WRITE-TOKEN>`
      component: rust-cs
    buffer_duration: 5
    buffer_size: 5
    hostname: `<YOUR-LDP-CLUSTER-ADDRESS>`
    kind: buffer
    level: Informational
    null_character: true
    port: 12202
    use_tls: true
root:
  appenders:
  - ldp
  - stdout
  level: info

N'oubliez pas de remplacer le placeholder <YOUR-LDP-CLUSTER-ADDRESS> par le cluster où réside votre flux. Il n'est pas nécessaire d'indiquer le port GELF. Exemple : « gra3.logs.ovh.com ».

N'oubliez pas de remplacer le placeholder <YOUR-WRITE-TOKEN> par la valeur réelle du jeton d'écriture de votre flux.

Remplacez la valeur X-OVH-TOKEN par la valeur du jeton X-OVH-TOKEN de votre flux, et le hostname par votre cluster.

Utilisez cette configuration dans votre projet :

use core::time;
use std::thread::sleep;

use log::{info, warn};

fn main() {
    // reading
    log4rs_gelf::init_file("./log4rs.yml", None).unwrap();

    // using log crate APIs
    info!("Hello from rust");
    warn!("Warning from rust");

    // simulating some work (log framework is asynchronous)
    sleep(time::Duration::from_secs(5));

    // flushing remaining logs
    log4rs_gelf::flush().expect("Failed to send buffer, log records could be lost !");
}

Vous pouvez également consulter la documentation de l'API générée.

Aller plus loin

• Pour bien démarrer : Démarrage rapide
• Documentation : Guides
• Créer un compte : Essayez !
• Hub communautaire : communauté d'utilisateurs