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.2"

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::default());
    
    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...
}

Custom span context extractor

By default, the middleware reads the traceparent header and starts a new trace when it is missing or invalid. To customize extraction (for example, keep noop when it is missing), configure an extractor. Return None to keep noop:

use fastrace_poem::TRACEPARENT_HEADER;

let middleware = fastrace_poem::FastraceMiddleware::default()
    .with_span_context_extractor(|req| {
        req.headers()
            .get(TRACEPARENT_HEADER)
            .and_then(|traceparent| {
                fastrace::prelude::SpanContext::decode_w3c_traceparent(
                    traceparent.to_str().ok()?,
                )
            })
    });

How It Works

1. When a request arrives, the middleware runs the span context extractor. By default, it decodes the traceparent header, otherwise starts a new trace.
2. If the extractor returns None, a noop span is used.
3. When a context is available, a new root span is created for the request using the method and path 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.