foundations_macros/lib.rs
1mod common;
2mod info_metric;
3mod metrics;
4mod settings;
5mod span_fn;
6mod span_with_probe;
7mod with_test_telemetry;
8
9use proc_macro::TokenStream;
10
11#[proc_macro_attribute]
12pub fn info_metric(args: TokenStream, item: TokenStream) -> TokenStream {
13 info_metric::expand(args, item)
14}
15
16#[proc_macro_attribute]
17pub fn metrics(args: TokenStream, item: TokenStream) -> TokenStream {
18 metrics::expand(args, item)
19}
20
21#[proc_macro_attribute]
22pub fn settings(args: TokenStream, item: TokenStream) -> TokenStream {
23 settings::expand(args, item)
24}
25
26#[proc_macro_attribute]
27pub fn span_fn(args: TokenStream, item: TokenStream) -> TokenStream {
28 span_fn::expand(args, item)
29}
30
31/// Like `foundations::telemetry::tracing::span`, plus a per-span USDT probe
32/// fired at span end.
33///
34/// Probes are only emitted on linux/x86_64; on any other platform the macro
35/// degrades to a plain `foundations::telemetry::tracing::span` call.
36///
37/// The probe shows up to tracers as
38/// `<binary>:<usdt_provider>:span_end__<sanitized span name>`, where
39/// sanitization replaces `::` with `__` and any other non-alphanumeric
40/// character with `_`.
41///
42/// Expands to a dedicated probe semaphore: a `static` in the `.probes` ELF
43/// section that the tracer (like bpftrace) increments on attach. When the
44/// semaphore is non-zero, the span start timestamp is recorded in the span
45/// state (regardless of span sampling), and the per-span `probe_end` function's
46/// address is stored alongside it. When the last clone of the span drops,
47/// `probe_end` is called with the span duration in nanoseconds, executing the
48/// NOP whose address the `stapsdt` ELF note publishes as the
49/// `span_end__<sanitized span name>` probe location.
50///
51/// # Example
52///
53/// ```rust,ignore
54/// use foundations::telemetry::tracing::span_with_probe;
55///
56/// span_with_probe!("http::client::send_request", usdt_provider = "myapp")
57/// .into_context()
58/// .apply(do_exchange())
59/// .await
60/// ```
61///
62/// Options:
63/// - `crate_path = "..."` (defaults to `::foundations`)
64/// - `usdt_provider = "..."` (defaults to the `FOUNDATIONS_USDT_PROVIDER`
65/// environment variable at compile time — settable per project via `[env]`
66/// in `.cargo/config.toml` — or `"foundations"` when unset); must be
67/// non-empty and must not contain `:`
68#[proc_macro]
69pub fn span_with_probe(input: TokenStream) -> TokenStream {
70 span_with_probe::expand(input)
71}
72
73#[proc_macro_attribute]
74pub fn with_test_telemetry(args: TokenStream, item: TokenStream) -> TokenStream {
75 with_test_telemetry::expand(args, item)
76}