Tracing Rust: métodos, exemplos, instalação

O que é Tracing e por que ele é necessário em Rust?

\n\n

A biblioteca Tracing é um framework poderoso para registro estruturado e instrumentação (rastreamento) de aplicações em Rust. Diferente de loggers simples, o Tracing fornece o conceito de spans e eventos (events), que permitem rastrear a execução do código no contexto de operações assíncronas, sistemas distribuídos e chamadas aninhadas complexas.

\n\n

O principal objetivo do Tracing é dar ao desenvolvedor uma visão completa do que acontece dentro do programa: quais funções são chamadas, quanto tempo elas levam para executar, quais erros ocorrem e como eles estão relacionados entre si. É uma ferramenta indispensável para depuração, criação de perfil e monitoramento de sistemas em produção.

\n\n

A biblioteca faz parte do ecossistema Tokio e é ativamente usada em projetos como actix-web, axum, hyper e muitos outros.

\n\n

Instalação do Tracing

\n\n

Para adicionar Tracing ao seu projeto em Rust, abra o arquivo Cargo.toml e adicione as seguintes dependências:

\n\n

[dependencies]\ntracing = "0.1"\ntracing-subscriber = "0.3"  # Para exibir logs no console\ntracing-appender = "0.2"    # Para gravar logs em arquivo (opcional)

\n\n

Depois disso, execute o comando cargo build para baixar e compilar as bibliotecas.

\n\n

Início rápido: primeiro exemplo

\n\n

Vamos escrever um programa simples que registra uma mensagem usando Tracing:

\n\n

use tracing::{info, Level};\nuse tracing_subscriber::FmtSubscriber;\n\nfn main() {\n    // Inicializamos o subscriber para exibir logs no stdout\n    let subscriber = FmtSubscriber::builder()\n        .with_max_level(Level::INFO)\n        .finish();\n    tracing::subscriber::set_global_default(subscriber)\n        .expect("Falha ao definir o subscriber global");\n\n    // Registramos uma mensagem simples\n    info!("Aplicação iniciada!");\n\n    // Chamada de função com rastreamento\n    process_data("example.txt");\n}\n\nfn process_data(filename: &str) {\n    // Criamos um span para rastrear a função\n    let span = tracing::span!(Level::INFO, "process_data", filename = filename);\n    let _guard = span.enter(); // Entramos no span\n\n    info!("Iniciando processamento do arquivo");\n    // ... algum trabalho ...\n    std::thread::sleep(std::time::Duration::from_millis(100));\n    info!("Processamento concluído");\n}

\n\n

Ao executar, você verá uma saída estruturada com carimbos de data/hora, níveis e nomes de spans.

\n\n

Principais métodos e funções do Tracing

\n\n

Abaixo estão 10 funções e macros chave da biblioteca Tracing com descrição detalhada e exemplos.

\n\n

1. `tracing::span!` — Criação de span

O que faz: Cria um novo span — uma unidade lógica de trabalho que pode ser aninhada. O span tem um nome, um nível e um conjunto de campos.

Parâmetros:

Level — nível de registro (ERROR, WARN, INFO, DEBUG, TRACE)
target (opcional) — string que identifica o módulo
field = value — campos arbitrários para contexto

Exemplo:

use tracing::Level;\n\nfn handle_request(id: u64) {\n    let span = tracing::span!(Level::INFO, "handle_request", request_id = id);\n    let _guard = span.enter();\n    // Código dentro do span\n    tracing::info!("Processando requisição");\n}

\n\n