Support inline config for #[dial9_tokio_telemetry::main()] (#256)

* support inline config

* pr comments

* refactor builder approach

* pr comments

* fallback config example

* restore old config approach and deprecate it

* pr comments

* create TelemetryRuntime

* TelemetryRuntime builds the guard and the runtime

* move errors to its corresponding place

* wire up build_or_disabled

* review docs

* review tests

* lhf comments

* move writer to config builder, collapse Dial9ConfigFallback, reshape error

* promote TracedRuntime instead of TelemetryRuntime

* always-present TelemetryGuard, inert TelemetryHandle, non-panicking current()

* update changelog

* docs: address review feedback on config builder, examples, and changelog

---------

Co-authored-by: Jess Izen <jlizen@amazon.com>

Author: Fluzko

CHANGELOG.md

@@ -7,6 +7,29 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Added
+
+- **Inline config in the macro**: `#[dial9_tokio_telemetry::main]` now accepts a closure, so simple setups no longer need a separate config function.
+- **Fluent config builder**: `Dial9Config::builder()` with named setters, `with_tokio`/`with_runtime` closures, and `.enabled(bool)`. The original positional API under `dial9_tokio_telemetry::config` is unchanged.
+- **`build_or_disabled()`**: on config validation or writer I/O failure, logs an error and starts a plain tokio runtime instead of crashing. Use `build()` to handle failures explicitly.
+
+All three in action:
+
+  ```rust
+  #[dial9_tokio_telemetry::main(config = || {
+      Dial9Config::builder()
+          .base_path("/tmp/trace.bin")
+          .max_file_size(64 * 1024 * 1024)
+          .max_total_size(256 * 1024 * 1024)
+          .build_or_disabled()
+  })]
+  async fn main() { /* ... */ }
+  ```
+
+### Changed
+
+- `TelemetryHandle::current()` no longer panics off-runtime. It returns an inert handle whose `spawn` falls through to `tokio::spawn`. Use `TelemetryHandle::is_enabled()` to check whether telemetry is live.
+
 ## [0.3.6](https://github.com/dial9-rs/dial9-tokio-telemetry/compare/dial9-tokio-telemetry-v0.3.5...dial9-tokio-telemetry-v0.3.6) - 2026-04-30
 
 ### Added
@@ -97,13 +120,13 @@ tracing_subscriber::registry()
     .init();
 ```
 
-Tracing support means you can attach a request ID or other context to spans via `#[instrument(fields(request_id = %id))]` and then search for specific requests in the trace. You can also see what's happening inside long polls: if a single poll contains many small operations without yielding, the span breakdown shows exactly where the time went. 
+Tracing support means you can attach a request ID or other context to spans via `#[instrument(fields(request_id = %id))]` and then search for specific requests in the trace. You can also see what's happening inside long polls: if a single poll contains many small operations without yielding, the span breakdown shows exactly where the time went.
 
 Standard `tracing-subscriber` filtering rules apply. Without a filter, libraries like the AWS SDK will flood the trace with internal spans. The preceding captures only spans from `my_app`.
 
 ## [0.3.0](https://github.com/dial9-rs/dial9-tokio-telemetry/compare/dial9-tokio-telemetry-v0.2.0...dial9-tokio-telemetry-v0.3.0) - 2026-04-17
 
-Big release. The setup story is much better, there's support for tracing multiple runtimes, you can emit your own events into the trace, and the viewer is its own crate now. 
+Big release. The setup story is much better, there's support for tracing multiple runtimes, you can emit your own events into the trace, and the viewer is its own crate now.
 
 ### `#[dial9_tokio_telemetry::main]` macro ([#212](https://github.com/dial9-rs/dial9-tokio-telemetry/pull/212))
 
@@ -227,6 +250,7 @@ Uncompressed trace files can be concatenated (`cat trace.0.bin trace.1.bin > com
 ## [0.2.0](https://github.com/dial9-rs/dial9-tokio-telemetry/compare/dial9-tokio-telemetry-v0.1.1...dial9-tokio-telemetry-v0.2.0) - 2026-03-20
 
 0.2.0 brings two major improvements:
+
 1. Support for publishing traces to S3
 2. Migration to the new trace format (dial9-trace-format). This format is self describing, extremely compact, compressible and fast to write. This will set us up to easily add application level telemetry in the future.
 
@@ -246,15 +270,15 @@ For setting it up in production applications, the new `.install(true/false)` met
 - Bring back support for locations in offline symbolization ([#110](https://github.com/dial9-rs/dial9-tokio-telemetry/pull/110))
 - stop writing trailing garbage in gzip segments after graceful_shutdown ([#104](https://github.com/dial9-rs/dial9-tokio-telemetry/pull/104))
 - Fix worker spin-loop on gzip-compressed and permanently failing segments ([#102](https://github.com/dial9-rs/dial9-tokio-telemetry/pull/102))
-- *(trace_viewer)* update format name from TOKIOTRC to D9TF in landing screen ([#103](https://github.com/dial9-rs/dial9-tokio-telemetry/pull/103))
-- *(js-decoder)* handle truncated frames gracefully, read symbol frames even if >= MAX_EVENTS ([#98](https://github.com/dial9-rs/dial9-tokio-telemetry/pull/98))
+- _(trace_viewer)_ update format name from TOKIOTRC to D9TF in landing screen ([#103](https://github.com/dial9-rs/dial9-tokio-telemetry/pull/103))
+- _(js-decoder)_ handle truncated frames gracefully, read symbol frames even if >= MAX_EVENTS ([#98](https://github.com/dial9-rs/dial9-tokio-telemetry/pull/98))
 - clarify S3 key layout is the default, not the only option ([#89](https://github.com/dial9-rs/dial9-tokio-telemetry/pull/89))
 - add missing crates.io metadata ([#84](https://github.com/dial9-rs/dial9-tokio-telemetry/pull/84))
 - thread-local buffer not flushing on drop ([#54](https://github.com/dial9-rs/dial9-tokio-telemetry/pull/54))
 
 ### Other
 
-- *(trace-parser)* consolidate per-branch cap checks into early continue ([#116](https://github.com/dial9-rs/dial9-tokio-telemetry/pull/116))
+- _(trace-parser)_ consolidate per-branch cap checks into early continue ([#116](https://github.com/dial9-rs/dial9-tokio-telemetry/pull/116))
 - fix flaky worker park test ([#117](https://github.com/dial9-rs/dial9-tokio-telemetry/pull/117))
 - Harden flush path with ArrayQueue & emit metrics ([#97](https://github.com/dial9-rs/dial9-tokio-telemetry/pull/97))
 - Update demo trace to have symbols ([#105](https://github.com/dial9-rs/dial9-tokio-telemetry/pull/105))

dial9-macro/src/lib.rs

@@ -2,17 +2,26 @@ use proc_macro::TokenStream;
 use proc_macro2::TokenStream as TokenStream2;
 use quote::quote;
 use syn::parse::{Parse, ParseStream};
-use syn::{ItemFn, Path, Token, parse_macro_input};
+use syn::{ExprClosure, ItemFn, Path, Token, parse_macro_input};
+
+enum ConfigSource {
+    Path(Path),
+    Closure(ExprClosure),
+}
 
 struct MainArgs {
-    config: Path,
+    config: ConfigSource,
 }
 
-const MISSING_CONFIG_HELP: &str = "missing required `config = <fn>` argument, \
-                           e.g. #[dial9_tokio_telemetry::main(config = my_config)]";
+const MISSING_CONFIG_HELP: &str = "missing required `config` argument, e.g.\n  \
+                           #[dial9_tokio_telemetry::main(config = my_config_fn)]\n\
+                           or with an inline closure:\n  \
+                           #[dial9_tokio_telemetry::main(config = || Dial9Config::builder().base_path(...).max_file_size(...).max_total_size(...).build().unwrap())]";
 
-const CONFIG_MUST_BE_ZERO_ARG_HELP: &str = "`config` must be a path to a zero-argument function, \
-                           e.g. #[dial9_tokio_telemetry::main(config = my_config)]";
+const CONFIG_MUST_BE_ZERO_ARG_HELP: &str = "`config` must be a zero-argument function path or a zero-argument closure, e.g.\n  \
+                           #[dial9_tokio_telemetry::main(config = my_config_fn)]\n\
+                           or with an inline closure:\n  \
+                           #[dial9_tokio_telemetry::main(config = || Dial9Config::builder().base_path(...).max_file_size(...).max_total_size(...).build().unwrap())]";
 impl Parse for MainArgs {
     fn parse(input: ParseStream) -> syn::Result<Self> {
         if input.is_empty() {
@@ -23,7 +32,20 @@ impl Parse for MainArgs {
             return Err(syn::Error::new(ident.span(), MISSING_CONFIG_HELP));
         }
         input.parse::<Token![=]>()?;
-        let config: Path = input.parse()?;
+
+        let config = if input.peek(Token![|]) || input.peek(Token![move]) {
+            let closure: ExprClosure = input.parse()?;
+            if !closure.inputs.is_empty() {
+                return Err(syn::Error::new_spanned(
+                    &closure.inputs,
+                    CONFIG_MUST_BE_ZERO_ARG_HELP,
+                ));
+            }
+            ConfigSource::Closure(closure)
+        } else {
+            ConfigSource::Path(input.parse()?)
+        };
+
         if !input.is_empty() {
             return Err(input.error(CONFIG_MUST_BE_ZERO_ARG_HELP));
         }
@@ -60,7 +82,10 @@ fn expand_main(args: MainArgs, input: ItemFn) -> Result<TokenStream2, syn::Error
         ));
     }
 
-    let config_fn = &args.config;
+    let config_call = match &args.config {
+        ConfigSource::Path(p) => quote! { #p() },
+        ConfigSource::Closure(c) => quote! { (#c)() },
+    };
     let attrs = &input.attrs;
     let vis = &input.vis;
     let name = &input.sig.ident;
@@ -70,23 +95,8 @@ fn expand_main(args: MainArgs, input: ItemFn) -> Result<TokenStream2, syn::Error
     Ok(quote! {
         #(#attrs)*
         #vis fn #name() #ret {
-            let (__tokio_runtime, __maybe_guard) = #config_fn()
-                .build()
-                .expect("failed to initialize runtime");
-            if let Some(__dial9_guard) = __maybe_guard {
-                let __dial9_handle = __dial9_guard.handle();
-                __tokio_runtime.block_on(async move {
-                    match __dial9_handle.spawn(async move { #(#body_stmts)* }).await {
-                        Ok(output) => output,
-                        Err(err) if err.is_panic() => {
-                            ::std::panic::resume_unwind(err.into_panic())
-                        }
-                        Err(_) => unreachable!("task cannot be cancelled inside block_on"),
-                    }
-                })
-            } else {
-                __tokio_runtime.block_on(async move { #(#body_stmts)* })
-            }
+            let __dial9_rt = ::dial9_tokio_telemetry::TracedRuntime::new(#config_call);
+            __dial9_rt.block_on(async move { #(#body_stmts)* })
         }
     })
 }
@@ -105,18 +115,38 @@ fn expand_main(args: MainArgs, input: ItemFn) -> Result<TokenStream2, syn::Error
 ///
 /// # Arguments
 ///
-/// * `config` — path to a zero-argument function returning [`Dial9Config`].
-///   Build one with [`Dial9ConfigBuilder::new`] (telemetry enabled) or
-///   [`Dial9ConfigBuilder::disabled`] (plain tokio, no telemetry).
+/// * `config` — a zero-argument function path or a zero-argument closure
+///   returning any value convertible into a `TracedRuntime`. In
+///   practice that means one of:
+///     - [`Dial9Config`] from `Dial9Config::builder().build()` (strict):
+///       any builder validation or writer-I/O failure surfaces from
+///       `.build()` as a `Dial9ConfigBuilderError`; runtime construction
+///       under the macro panics on tokio-builder or telemetry-core I/O.
+///     - [`Dial9Config`] from `Dial9Config::builder().build_or_disabled()`
+///       (lenient): the same `Dial9Config` type, but validation and
+///       writer-I/O failures are logged at `error!` and downgraded to a
+///       disabled config that still preserves your `with_tokio`
+///       configurators.
+///     - The deprecated positional `dial9_tokio_telemetry::config::Dial9Config`,
+///       kept compatible via a bridge impl.
+///
+///   Use `.enabled(false)` on the builder to run without telemetry
+///   while keeping your `with_tokio` configurators.
+///
+/// # Examples
 ///
-/// # Example
+/// Using a named function:
 ///
 /// ```rust,ignore
-/// use dial9_tokio_telemetry::{main, config::{Dial9Config, Dial9ConfigBuilder}, telemetry::TelemetryHandle};
+/// use dial9_tokio_telemetry::{main, Dial9Config, telemetry::TelemetryHandle};
 ///
 /// fn my_config() -> Dial9Config {
-///     Dial9ConfigBuilder::new("/tmp/trace.bin", 1024 * 1024, 16 * 1024 * 1024)
+///     Dial9Config::builder()
+///         .base_path("/tmp/trace.bin")
+///         .max_file_size(1024 * 1024)
+///         .max_total_size(16 * 1024 * 1024)
 ///         .build()
+///         .expect("config build failed")
 /// }
 ///
 /// #[dial9_tokio_telemetry::main(config = my_config)]
@@ -128,6 +158,53 @@ fn expand_main(args: MainArgs, input: ItemFn) -> Result<TokenStream2, syn::Error
 ///         .unwrap();
 /// }
 /// ```
+///
+/// Using an inline closure:
+///
+/// ```rust,ignore
+/// #[dial9_tokio_telemetry::main(config = || {
+///     Dial9Config::builder()
+///         .base_path("/tmp/trace.bin")
+///         .max_file_size(1024 * 1024)
+///         .max_total_size(16 * 1024 * 1024)
+///         .build()
+///         .expect("config build failed")
+/// })]
+/// async fn main() {
+///     /* ... */
+/// }
+/// ```
+///
+/// Lenient (telemetry is best-effort; falls back to a plain tokio
+/// runtime if writer setup fails):
+///
+/// ```rust,ignore
+/// #[dial9_tokio_telemetry::main(config = || {
+///     Dial9Config::builder()
+///         .base_path("/tmp/trace.bin")
+///         .max_file_size(1024 * 1024)
+///         .max_total_size(16 * 1024 * 1024)
+///         .build_or_disabled()
+/// })]
+/// async fn main() {
+///     /* ... */
+/// }
+/// ```
+///
+/// Disabled (no telemetry, plain tokio runtime — useful for toggling
+/// dial9 off via a feature flag or env var without removing the macro):
+///
+/// ```rust,ignore
+/// #[dial9_tokio_telemetry::main(config = || {
+///     Dial9Config::builder()
+///         .enabled(false)
+///         .build()
+///         .expect("config build failed")
+/// })]
+/// async fn main() {
+///     /* ... */
+/// }
+/// ```
 #[proc_macro_attribute]
 pub fn main(attr: TokenStream, item: TokenStream) -> TokenStream {
     let args = parse_macro_input!(attr as MainArgs);
@@ -235,31 +312,63 @@ mod tests {
     #[test]
     fn error_empty_args() {
         let msg = parse_args_err(quote! {});
-        assert!(msg.contains("config = <fn>"), "unexpected error: {msg}");
+        assert!(
+            msg.contains("missing required `config`"),
+            "unexpected error: {msg}"
+        );
     }
 
     #[test]
     fn error_wrong_arg_name() {
         let msg = parse_args_err(quote! { foo = bar });
-        assert!(msg.contains("config = <fn>"), "unexpected error: {msg}");
+        assert!(
+            msg.contains("missing required `config`"),
+            "unexpected error: {msg}"
+        );
     }
 
     #[test]
     fn error_config_with_args() {
         let msg = parse_args_err(quote! { config = my_config(arg) });
-        assert!(
-            msg.contains("zero-argument function"),
-            "unexpected error: {msg}"
-        );
+        assert!(msg.contains("zero-argument"), "unexpected error: {msg}");
     }
 
     #[test]
     fn error_config_trailing_tokens() {
         let msg = parse_args_err(quote! { config = my_config, extra = stuff });
-        assert!(
-            msg.contains("zero-argument function"),
-            "unexpected error: {msg}"
+        assert!(msg.contains("zero-argument"), "unexpected error: {msg}");
+    }
+
+    #[test]
+    fn expand_with_inline_closure() {
+        let output = expand(
+            quote! { config = || my_config() },
+            quote! {
+                async fn main() {
+                    do_work().await;
+                }
+            },
         );
+        insta::assert_snapshot!(output);
+    }
+
+    #[test]
+    fn expand_with_move_closure() {
+        let output = expand(
+            quote! { config = move || my_config() },
+            quote! {
+                async fn main() {
+                    do_work().await;
+                }
+            },
+        );
+        insta::assert_snapshot!(output);
+    }
+
+    #[test]
+    fn error_closure_with_args() {
+        let msg = parse_args_err(quote! { config = |x| my_config() });
+        assert!(msg.contains("zero-argument"), "unexpected error: {msg}");
     }
 
     #[test]

dial9-macro/src/snapshots/dial9_macro__tests__expand_basic.snap

@@ -3,30 +3,9 @@ source: dial9-macro/src/lib.rs
 expression: output
 ---
 fn main() {
-    let (__tokio_runtime, __maybe_guard) = my_config()
-        .build()
-        .expect("failed to initialize runtime");
-    if let Some(__dial9_guard) = __maybe_guard {
-        let __dial9_handle = __dial9_guard.handle();
-        __tokio_runtime
-            .block_on(async move {
-                match __dial9_handle
-                    .spawn(async move {
-                        do_work().await;
-                    })
-                    .await
-                {
-                    Ok(output) => output,
-                    Err(err) if err.is_panic() => {
-                        ::std::panic::resume_unwind(err.into_panic())
-                    }
-                    Err(_) => unreachable!("task cannot be cancelled inside block_on"),
-                }
-            })
-    } else {
-        __tokio_runtime
-            .block_on(async move {
-                do_work().await;
-            })
-    }
+    let __dial9_rt = ::dial9_tokio_telemetry::TracedRuntime::new(my_config());
+    __dial9_rt
+        .block_on(async move {
+            do_work().await;
+        })
 }