RFC: fastrace 0.8 API cleanup

[andylokandy]

Context

#114 tracks the broader 1.0 roadmap. This issue is narrower: it proposes a 0.8 breaking release as an intermediate cleanup step before the public API becomes harder to change.

The main goal is to clarify the boundaries between live spans, propagation context, async instrumentation, and collector backends.

Related issues: #172, #158, #92, #167, #171, #164.

0.7 deprecation release

Before 0.8, we can publish a 0.7.x release that deprecates APIs planned for removal:

• fastrace::prelude
• old async instrumentation APIs such as enter_on_poll
• async wrappers that require users to construct a live Span and move it into the wrapper

0.8 can then remove them and update docs and examples to the new style.

Async instrumentation

The current async API exposes a low-level model:

future.in_span(Span::enter_with_parent("task", &root));
stream.in_span(Span::enter_with_parent("stream", &root));

For 0.8, we should avoid keeping this model under another name such as with_span(span). Instead, async APIs should be named by the lifetime of the span they create:

future.in_span("task", &root)
future.in_poll_span("poll")

stream.in_span("stream", &root)
stream.in_poll_span("poll")
stream.in_item_span("item")

in_span covers the whole future or stream. in_poll_span creates a short LocalSpan for each poll. in_item_span creates a span for each yielded stream item.

This also gives us a clearer migration path from tracing-futures and closes the main gap in #172.

Trace Context model

0.8 should move from case-by-case W3C helpers toward a coherent Trace Context model.

Suggested split:

Span             // live span, owns timing and drop reporting
SpanContext      // cheap internal parent and link context
TraceContext     // W3C propagation boundary: traceparent and tracestate

TraceContext should be the W3C Trace Context type, including traceparent, tracestate, and trace flags.

This likely means changing the ID and flag model:

pub struct TraceId([u8; 16]);
pub struct SpanId([u8; 8]);
pub struct TraceFlags(u8);

That gives us a natural place to support both W3C flags: sampled and random-trace-id. It also addresses the wire-representation concern in #167.

ID validity

0.8 should remove APIs that make invalid IDs easy to create.

In particular, we should remove Default for TraceId, SpanId, and likely SpanContext, make ID fields private, and use checked construction or parsing for public APIs. All-zero trace IDs and span IDs should not be easy to construct accidentally.

This is the breaking cleanup already discussed in #92, #111, and #112.

TraceState

tracestate should be part of the propagation boundary, not an incidental Option<String> added to one helper.

A compact first version could be:

pub struct TraceState(Option<Arc<str>>);

That keeps pass-through cheap while leaving room for validation and vendor-entry updates later.

Collector and compatibility boundary

The current global collector design is still valuable: foreground work stays low, while aggregation and reporting happen in the background.

The issue is that frontend actions are tightly coupled to fastrace's own global command pipeline. This makes compatibility work harder, especially for the reverse direction of fastrace-tracing: producing fastrace spans into tracing so applications can reuse tracing reporters.

For 0.8, we should revisit whether span and local span actions can target a small core recording boundary before collector-specific aggregation happens. The existing global collector can remain the default backend, but the frontend action model should not make future tracing compatibility impossible.

[bzp2010]

I have a small suggestion regarding the InSpan API. A review of existing APIs and a look ahead to new APIs.

"Would it be possible to make it accept references instead of moves?"

This is because the span’s lifecycle may not necessarily align with the Future’s, and sometimes I want to precisely control when the span ends rather than relying on automatic span drop.

For example, consider the following scenario:

An Axum web API server that emits a root span on every incoming HTTP request and stops the root span when the response is complete.
This works well with the req/resp pattern, but sometimes we handle SSE responses.
When the response header has been sent to client, the async task fn(req) -> Future<resp> is completed. SSE blocks are generated on a stream that does not share a lifecycle with the response, because this stream is the return value of the handler function.
Therefore, the other spans on the SSE will begin after the root span ends, which is not in accordance with the specification and also appears to be incorrect.

At this point, I need to manually control when the span ends, which can of course be achieved using drop(root_span), provided I haven’t passed it to the in_span function.

However, I must ensure that the hierarchical relationship of the span is tracked correctly (via the parent span), so calls to in_span—which involve manually “suspending” and “resuming” the local parent before and after the await point—are unavoidable.

So I did the following:

async fn trace(mut req: Request, next: Next) -> Response<TimedBody> {
    let root_span = generate_span(&req);

    let (response, root_span) = (WithSpan {
        inner: async {
            let response = next.run(req).await;
            LocalSpan::add_property(|| {
                (
                    HTTP_RESPONSE_STATUS_CODE,
                    response.status().as_u16().to_string(),
                )
            });
            response
        },
        span: Some(root_span),
    })
    .await;

    Response::from_parts(
        parts,
        TimedBody { span: Some(root_span), response },
    )
}

WithSpan, It's basically copied from InSpan, with the only difference being that it also returns the input span itself.

#[pin_project::pin_project]
pub struct WithSpan<F> {
    #[pin]
    pub inner: F,
    pub span: Option<Span>,
}

impl<F: Future> Future for WithSpan<F> {
    type Output = (F::Output, Span);

    fn poll(self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<Self::Output> {
        let this = self.project();
        let _guard = this.span.as_ref().map(|s| s.set_local_parent());

        match this.inner.poll(cx) {
            Poll::Ready(val) => Poll::Ready((val, this.span.take().unwrap())), // <=
            Poll::Pending => Poll::Pending,
        }
    }
}

TimedBody

TimedBody, Using the poll_frame hook provided by the http_body::Body trait, ownership of the span is acquired only after the response has been sent, and it is dropped when the poll_frame function ends.

pub struct TimedBody {
    span: Option<Span>,
    response: Response,
}

impl http_body::Body for TimedBody {
    type Data = Bytes;
    type Error = Error;

    #[inline]
    fn poll_frame(
        mut self: Pin<&mut Self>,
        cx: &mut Context<'_>,
    ) -> Poll<Option<Result<Frame<Self::Data>, Self::Error>>> {
        let poll = Pin::new(&mut self.inner).poll_frame(cx);

        match &poll {
            Poll::Ready(Some(Ok(frame))) => { ... }
            Poll::Ready(None) => {
                self.span.take();
            }
            Poll::Ready(Some(Err(_))) => {
                self.span.take();
            }
            Poll::Pending => {}
        }

        poll
    }

    ...
}

If the in_span function simply returned the input span itself, or if it accepted only pointers instead of values, I could control the span’s lifecycle much more easily.

The assumption that the lifecycle of a span used for asynchronous tasks must be bound to a Future does not always hold true.

The new signature future.in_span("task", &root) you mentioned is based on pass-by-reference. Thus, I think this may align with what I mentioned above. The difference is that your API involves direct modifications to the API rather than maintaining backward compatibility.
I'm not sure if, when you mentioned &root, you actually intended to change it to pass-by-reference, so I'm adding this comment to clarify that we do need to consider doing so.

[andylokandy]

Thanks for the detailed example. I agree this is a case we should keep in mind.

My current read is that the request span should stay outside in_span if its lifetime is longer than the handler future. For SSE, that span can be owned by the response body wrapper and dropped when the stream is actually done.

The handler future can still get a local parent by using a child span:

let root = generate_span(&req);
let handler = Span::enter_with_parent("handler", &root);

let response = next.run(req)
    .in_span(handler)
    .await;

Response::from_parts(parts, TimedBody {
    span: Some(root),
    response,
})

That keeps the root lifetime independent from the future, while spans created inside the future still attach under handler, and handler attaches under root.

The future.in_span("task", &root) shape in the RFC is not settled. In practice it likely needs a separate handle type, which adds more API surface. So #176 keeps the owned-span model for now and focuses on cleaning up the names and poll-span behavior.

[bzp2010]

Some additional explanations.

My current read is that the request span should stay outside in_span if its lifetime is longer than the handler future. For SSE, that span can be owned by the response body wrapper and dropped when the stream is actually done.

The reason I use the pattern I mentioned is:

1. I need to register attributes and events on the root span using the LocalSpan::add_property API inside the handler.

   Sometimes this happens inside a fn trace, and sometimes it’s added inside a handler function, but the response = next.run(req).await pattern prevents us from passing the span into the handler, and we also can’t pass it via req.extensions (because that requires ownership of the span; once the span is moved to req.ext, InSpan can no longer use it) .

   Therefore, I need an API similar to InSpan to “attach” a span to an asynchronous context, so that I can add attributes (by LocalSpan) within the handler without requiring a &span.

2. I would prefer a flatter span tree structure, rather than binding a new span to a Future as soon as it is created. This would result in deeply nested span trees. "A span contains exactly one child span, and this pattern continues recursively."

Strictly, though, they’re just minor annoyances, and I’m now able to resolve them by above pattern.

[andylokandy]

Thanks for the extra context. This example makes the problem clearer to me.

I think the better 0.8 direction is to separate two concepts:

• owning a Span for the whole future lifetime
• carrying a SpanContext as the current execution context while polling the future

So instead of making in_span borrow and return the same Span, we can support a context-only async wrapper:

let root = generate_span(&req);
let root_ctx = root.context();

let response = next.run(req)
    .trace()
    .with_context(root_ctx)
    .await;

Response::from_parts(parts, TimedBody {
    span: Some(root),
    response,
})

In this shape, the response body still owns root and controls when it ends, while the handler future can still use LocalSpan::add_property and create child local spans under the root context. It also keeps the span tree flat when that is what the middleware wants.

For cases where the future itself should have a lifecycle span, the API can still be:

future
    .trace()
    .in_span(Span::start("handler", parent_ctx))

So the current direction I’m considering is:

future.trace()                     // capture current context
future.trace().with_context(ctx)   // carry an explicit context, no span ownership
future.trace().in_span(span)       // own a span for the future lifetime
future.trace().with_poll_span("poll")

This should cover the SSE use case without requiring borrowed spans or returning the span from in_span.