https://github.com/fast/fastrace-axum
A axum instrument for propagating trace context for fastrace.
https://github.com/fast/fastrace-axum
Last synced: about 1 year ago
JSON representation
A axum instrument for propagating trace context for fastrace.
- Host: GitHub
- URL: https://github.com/fast/fastrace-axum
- Owner: fast
- License: apache-2.0
- Created: 2025-03-27T11:11:28.000Z (over 1 year ago)
- Default Branch: main
- Last Pushed: 2025-03-31T11:00:02.000Z (about 1 year ago)
- Last Synced: 2025-05-11T04:11:13.100Z (about 1 year ago)
- Language: Rust
- Size: 28.3 KB
- Stars: 6
- Watchers: 1
- Forks: 3
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# fastrace-axum
[](https://crates.io/crates/fastrace-axum)
[](https://docs.rs/fastrace-axum/)
[](https://www.whatrustisit.com)
[](https://github.com/fast/fastrace-axum/actions)
[](https://github.com/fast/fastrace-axum/blob/main/LICENSE)
`fastrace-axum` is a middleware library that connects [fastrace](https://crates.io/crates/fastrace), a distributed tracing library, with [axum](https://crates.io/crates/axum), a gRPC framework for Rust. This integration enables seamless trace context propagation across microservice boundaries in gRPC-based applications.
## 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-axum` 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**: Automatically extract trace context from HTTP requests.
- 🌉 **Seamless Integration**: Works seamlessly with the `fastrace` library for complete distributed tracing.
- 📊 **Full Compatibility**: Works with fastrace's collection and reporting capabilities.
## Usage
### Server Integration
Add `fastrace-axum` to your Cargo.toml:
```toml
[dependencies]
fastrace = "0.7"
fastrace-axum = "0.1"
```
Apply the `FastraceLayer` to your axum server:
```rust
use fastrace::collector::Config;
use fastrace::collector::ConsoleReporter;
#[tokio::main]
async fn main() {
// Configurate fastrace reporter.
fastrace::set_reporter(ConsoleReporter, Config::default());
let app = axum::Router::new()
.route("/ping", axum::routing::get(ping))
// Add a the FastraceLayer to routes.
// The layer extracts trace context from incoming requests.
.layer(fastrace_axum::FastraceLayer);
let listener = tokio::net::TcpListener::bind("0.0.0.0:8080").await.unwrap();
axum::serve(listener, app).await.unwrap();
}
#[fastrace::trace] // Trace individual handlers.
async fn ping() -> &'static str {
"pong"
}
```
### Client Usage with fastrace-reqwest
To propagate trace context from clients to your axum service:
```rust
use fastrace::prelude::*;
use reqwest::Client;
#[fastrace::trace]
async fn send_request() {
let client = Client::new();
let response = client
.get("http://your-axum-service/endpoint")
.headers(fastrace_reqwest::traceparent_headers()) // Adds traceparent header.
.send()
.await
.unwrap();
// Process response...
}
```
## Example
Check out the [examples directory](https://github.com/fast/fastrace-axum/tree/main/example) for a complete ping/pong service example that demonstrates both client and server tracing.
To run the example:
1. Start the server:
```
cargo run --example server
```
3. In another terminal, run the client:
```
cargo run --example client
```
Both applications will output trace information showing the request flow, including the propagated context.
## How It Works
2. When a server receives the request, `FastraceLayer` extracts the trace context from the `traceparent` header and creates a new span as a child of the received context.
3. If no trace context is provided, the server creates a new root span.
This process ensures that all operations across services are properly connected in the resulting trace, providing visibility into the entire request lifecycle.
## License
This project is licensed under the [Apache-2.0](./LICENSE) license.