refactor!: clean up async span instrumentation APIs

AGENTS.md

@@ -19,14 +19,14 @@
 - Tail sampling: spans are held until root commit; `Span::cancel()` on the root triggers `CancelCollect` to discard the trace.
 
 ## Key Types & Behaviors
-- `Span` (`fastrace/src/span.rs`): thread-safe span, can be cross-thread; supports `enter_with_parent(s)`, `enter_with_local_parent`, `add_event`, `add_properties`, `push_child_spans`, `elapsed`, `cancel`.
+- `Span` (`fastrace/src/span.rs`): thread-safe span, can be cross-thread; supports `start`, `start_with_local_parent`, `set_local_parent`, `add_event`, `add_properties`, `push_child_spans`, `elapsed`, `cancel`.
 - `LocalSpan` (`local/local_span.rs`): single-thread fast path; requires an active local parent (`Span::set_local_parent` or nested `LocalSpan`). Stack discipline enforced; dropping out of order panics in tests.
 - `LocalCollector` (`local/local_collector.rs`): start/collect local spans when parent may be set later; returns `LocalSpans` attachable via `Span::push_child_spans` or convertible to `SpanRecord`s without a reporter.
 - ID types (`collector/id.rs`): `TraceId(u128)`, `SpanId(u64)`; thread-local generator (`SpanId::next_id`) and W3C traceparent encode/decode helpers. `SpanContext` carries trace, parent span id, and `sampled` flag.
 - `Config` (`collector/mod.rs`): `report_interval`; note `max_spans_per_trace` deprecated no-op and `tail_sampled` deprecated no-op.
 - `Reporter` trait (`collector/global_collector.rs`): synchronous `report(Vec<SpanRecord>)`. TestReporter collects into a shared Vec; ConsoleReporter prints.
-- Async adapters: `FutureExt::{in_span, enter_on_poll}` (`src/future.rs`); Stream/Sink adapters in `fastrace-futures`.
-- Proc macro `#[trace]` (`fastrace-macro/src/lib.rs`): wraps sync fns with `LocalSpan`; async fns with `Span::enter_with_local_parent` plus `in_span` by default or `enter_on_poll=true`. Options: `name`, `short_name`, `enter_on_poll`, `properties={k:"fmt"}`, `crate=path`.
+- Async adapters: `FutureExt::in_span(Span::start(...)).with_poll_span(...)` (`src/future.rs`); Stream/Sink adapters in `fastrace-futures`.
+- Proc macro `#[trace]` (`fastrace-macro/src/lib.rs`): wraps sync fns with `LocalSpan`; async fns with `Span::start_with_local_parent` plus the owned future wrapper, and `poll_span = true` adds per-poll spans. Options: `name`, `short_name`, `poll_span`, `properties={k:"fmt"}`, `crate=path`.
 - `enable` feature gates runtime collection; workspace members (examples/tests) request it, so full builds usually compile with tracing enabled. Ensure any changes keep the no-feature path compiling (many functions are #[cfg(feature="enable")] guarded).
 
 ## Reporters
@@ -50,7 +50,7 @@
 
 ## Gotchas & Tips
 - Always call `set_reporter` early; spans emitted before reporter init are dropped. Call `flush()` before shutdown to drain SPSC queues.
-- `LocalSpan` does nothing without a local parent; `Span::enter_with_local_parent` falls back to noop if no stack token exists.
+- `LocalSpan` does nothing without a local parent; `Span::start_with_local_parent` falls back to noop if no stack token exists.
 - Default local stack capacity: 4096 span lines and span queue size 10240; overflows drop spans silently (return None).
 - Tail sampling is the default; `Span::cancel()` on the root discards spans collected up to the root's drop (spans submitted after the root finishes may still be reported).
 - Keep both code paths healthy: when `enable` is off, public APIs stay callable but must remain no-ops without panicking.

CHANGELOG.md

@@ -8,6 +8,17 @@ All significant changes to this project will be documented in this file.
 
 - Upgrade MSRV to 1.85 and Edition to 2024.
 
+### Breaking Changes
+
+- Rename async poll instrumentation APIs: remove `enter_on_poll` and use
+  `in_span(Span::start(...)).with_poll_span(name)` for future and stream polling.
+- Rename span constructors from `Span::enter_with_parent` and
+  `Span::enter_with_local_parent` to `Span::start` and `Span::start_with_local_parent`.
+- Remove deprecated `Span::enter_with_parents`; use `Span::start(...).with_link(...)` instead.
+- Rename `LocalSpan::enter_with_local_parent` to `LocalSpan::start`.
+- Rename the macro option `enter_on_poll` to `poll_span`; it now creates the async function
+  lifecycle span and adds a poll span on each poll.
+
 ## v0.7.17
 
 ### Breaking Changes

examples/asynchronous.rs

@@ -25,11 +25,11 @@ use fastrace::collector::Reporter;
 use fastrace::prelude::*;
 use opentelemetry_otlp::WithExportConfig;
 
-fn parallel_job() -> Vec<tokio::task::JoinHandle<()>> {
+fn parallel_job(parent: &Span) -> Vec<tokio::task::JoinHandle<()>> {
     let mut v = Vec::with_capacity(4);
     for i in 0..4 {
         v.push(tokio::spawn(
-            iter_job(i).in_span(Span::enter_with_local_parent("iter job")),
+            iter_job(i).in_span(Span::start("iter job", parent)),
         ));
     }
     v
@@ -41,7 +41,7 @@ async fn iter_job(iter: u64) {
     other_job().await;
 }
 
-#[trace(enter_on_poll = true)]
+#[trace(poll_span = true)]
 async fn other_job() {
     for i in 0..20 {
         if i == 10 {
@@ -61,9 +61,9 @@ async fn main() {
 
         let f = async {
             let jhs = {
-                let _span = LocalSpan::enter_with_local_parent("a span")
+                let span = Span::start_with_local_parent("a span")
                     .with_property(|| ("a property", "a value"));
-                parallel_job()
+                parallel_job(&span)
             };
 
             other_job().await;
@@ -72,7 +72,7 @@ async fn main() {
                 jh.await.unwrap();
             }
         }
-        .in_span(span);
+        .in_span(Span::start("main task", &span));
 
         tokio::spawn(f).await.unwrap();
     }

examples/basic.rs

@@ -26,7 +26,7 @@ fn do_main() {
     let parent = SpanContext::random();
     let root = Span::root("root", parent);
     let _g = root.set_local_parent();
-    let _g = LocalSpan::enter_with_local_parent("child");
+    let _g = LocalSpan::start("child");
 
     // do business
 }

examples/harness.rs

@@ -56,8 +56,11 @@ mod test_util {
             .enable_all()
             .build()
             .unwrap();
-        let root = Span::root(closure_name::<F>(), SpanContext::random());
-        rt.block_on(test().in_span(root)).unwrap();
+        {
+            let root = Span::root(closure_name::<F>(), SpanContext::random());
+            rt.block_on(test().in_span(Span::start("test", &root)))
+                .unwrap();
+        }
         fastrace::flush();
     }
 

examples/logging.rs

@@ -48,7 +48,7 @@ fn do_main() {
 
     info!("event in root span");
 
-    let _local_span_guard = LocalSpan::enter_with_local_parent("child");
+    let _local_span_guard = LocalSpan::start("child");
 
     info!("event in child span");
 

examples/synchronous.rs

@@ -25,7 +25,7 @@ use fastrace::prelude::*;
 use opentelemetry_otlp::WithExportConfig;
 
 fn func1(i: u64) {
-    let _guard = LocalSpan::enter_with_local_parent("func1");
+    let _guard = LocalSpan::start("func1");
     std::thread::sleep(Duration::from_millis(i));
     func2(i);
 }
@@ -44,8 +44,7 @@ async fn main() {
         let root = Span::root("root", parent);
 
         let _g = root.set_local_parent();
-        let _span = LocalSpan::enter_with_local_parent("a span")
-            .with_property(|| ("a property", "a value"));
+        let _span = LocalSpan::start("a span").with_property(|| ("a property", "a value"));
 
         for i in 1..=10 {
             func1(i);