https://github.com/fast/fastrace-poem
A Poem middleware for propagating trace context for fastrace.
https://github.com/fast/fastrace-poem
Last synced: about 1 year ago
JSON representation
A Poem middleware for propagating trace context for fastrace.
- Host: GitHub
- URL: https://github.com/fast/fastrace-poem
- Owner: fast
- License: apache-2.0
- Created: 2025-03-18T10:35:59.000Z (over 1 year ago)
- Default Branch: main
- Last Pushed: 2025-03-27T13:31:00.000Z (about 1 year ago)
- Last Synced: 2025-04-30T08:52:03.417Z (about 1 year ago)
- Language: Rust
- Homepage:
- Size: 29.3 KB
- Stars: 1
- Watchers: 1
- Forks: 2
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# fastrace-poem
[](https://crates.io/crates/fastrace-poem)
[](https://docs.rs/fastrace-poem/)
[](https://www.whatrustisit.com)
[](https://github.com/fast/fastrace-poem/actions)
[](https://github.com/fast/fastrace-poem/blob/main/LICENSE)
Distributed tracing integration for [Poem](https://github.com/poem-web/poem) web framework with [fastrace](https://crates.io/crates/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](https://www.w3.org/TR/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`:
```toml
[dependencies]
fastrace = "0.7"
fastrace-poem = "0.1"
```
## Usage
### Server Integration
```rust
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:
```rust
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](https://github.com/fast/fastrace-poem/tree/main/examples) 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:
```bash
# 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) license.