fastrace-poem

Distributed tracing integration for Poem web framework with fastrace.

Overview

fastrace-poem provides middleware for the Poem web framework to enable distributed tracing with automatic context propagation. This helps you track requests as they flow through your microservice architecture, giving you valuable insights for debugging, performance analysis, and system understanding.

What is Context Propagation?

Context propagation is a fundamental concept in distributed tracing that enables the correlation of operations spanning multiple services. When a request moves from one service to another, trace context information needs to be passed along, ensuring that all operations are recorded as part of the same trace.

fastrace-poem implements the W3C Trace Context standard for propagating trace information between services. This ensures compatibility with other tracing systems that follow the same standard.

Features

• 🔄 Automatic context propagation via W3C traceparent headers.
• 🌉 Seamless integration with Poem's middleware system.
• 🔗 Request tracing with proper parent-child span relationships.
• 📊 Full compatibility with fastrace's collection and reporting capabilities.

Installation

Add the following to your Cargo.toml:

[dependencies]
fastrace = "0.7"
fastrace-poem = "0.1"

Usage

Server Integration

use fastrace::collector::{Config, ConsoleReporter};
use fastrace_poem::FastraceMiddleware;
use poem::{get, handler, EndpointExt, Request, Response, Route, Server};
use poem::listener::TcpListener;

#[tokio::main]
async fn main() -> Result<(), std::io::Error> {
    // Configure fastrace reporter.
    fastrace::set_reporter(ConsoleReporter, Config::default());
    
    // Add the FastraceMiddleware to your routes.
    let app = Route::new()
        .at("/ping", get(ping))
        .with(FastraceMiddleware);
    
    Server::new(TcpListener::bind("0.0.0.0:8080"))
        .run(app)
        .await?;
    
    fastrace::flush();

    Ok(())
}

#[handler]
#[fastrace::trace] // Trace individual handlers.
fn ping() -> Response {
    Response::builder().body("pong")
}

Client Usage with fastrace-reqwest

To propagate trace context from clients to your Poem service:

use fastrace::prelude::*;
use reqwest::Client;

#[fastrace::trace]
async fn send_request() {
    let client = Client::new();
    let response = client
        .get("http://your-poem-service/endpoint")
        .headers(fastrace_reqwest::traceparent_headers()) // Adds traceparent header.
        .send()
        .await
        .unwrap();
    
    // Process response...
}

How It Works

1. When a request arrives, the middleware checks for a traceparent header.
2. If present, it extracts the trace context; otherwise, it creates a new random context.
3. A new root span is created for the request using the URI as the name.
4. The request handler is executed within this span, and any child spans are properly linked.
5. The trace is then collected by your configured fastrace reporter.

Complete Example

Check out the examples directory for complete working examples showing:

• client.rs - How to send requests with trace context.
• server.rs - How to receive and process trace context using fastrace-poem.

To run the examples:

# First start the server
cargo run --example server

# Then in another terminal, run the client
cargo run --example client

License

This project is licensed under the Apache-2.0 license.