final copy for first pass at docs

Author: davidhewitt

src/lib.rs

@@ -73,11 +73,38 @@
 //!
 //! ## Integrations
 //!
+//! The following sections describe briefly the interaction which this SDK has with other libraries.
+//!
 //! ### With `tracing`
 //!
+//! This SDK is built upon `tracing` (and `tracing-opentelemtry`) for the [`span!`] macro. This means
+//! that any code instrumented with `tracing` will automatically be captured by Logfire, and also
+//! that [`span!`] produces a `tracing::Span` which is fully compatible with the `tracing` ecosystem.
+//!
+//! If you are an existing `tracing` user, it is fine to continue to use the `tracing` APIs directly
+//! and ignore [`logfire::span!`][span]. The upside of [`span!`] is that it will show the fields
+//! directly in the logfire UI.
+//!
+//! There are many great APIs in `tracing` which we do not yet provide equivalents for, such as the
+//! [`#[tracing::instrument]`][`macro@tracing::instrument`] proc macro, so even if using [`logfire::span!`][span]
+//! you will likely use `tracing` APIs directly too.
+//!
 //! ### With `opentelemetry`
 //!
+//! This SDK is built upon the `opentelemetry` Rust SDK and will configure the global `opentelemetry`
+//! state as part of a call to [`logfire::configure()`][configure].
+//!
+//! All calls to [`logfire::info!`][info] and similar macros are directly forwarded to `opentelemetry`
+//! machinery without going through `tracing`, for performance.
+//!
+//! The metrics helpers exported by this SDK, such as [`logfire::u64_counter()`][u64_counter], are
+//! very thin wrappers around the `opentelemetry` SDK.
+//!
 //! ### With `log`
+//!
+//! This SDK configures the global `log` state to use an exporter which forwards logs to opentelemetry.
+//!
+//! All code instrumented with `log` will therefore automatically be captured by Logfire.
 
 use std::borrow::Cow;
 use std::cell::RefCell;

src/macros/mod.rs

@@ -2,10 +2,53 @@
 #[path = "impl_.rs"]
 pub mod __macros_impl;
 
-/// Create a new span.
+/// Create a new [`Span`][tracing::Span]. This macro is a simplified version of `tracing::span!` which accepts
+/// a smaller set of possible arguments and syntaxes.
 ///
-/// The return type of this macro is a [`tracing::Span`], which can be used to enter the span
-/// or to pass it to `tracing::Instrument` methods.
+/// In exchange, the macro automatically adds metadata which leads the span and its fields
+/// to present nicely in the Logfire UI.
+///
+/// # Syntax
+///
+/// The macro accepts the following syntax:
+///
+/// ```rust,ignore
+/// span!(
+///    parent: tracing::Span, // optional, can emit this
+///    level: tracing::Level, // optional
+///    "format string",       // required, must be a format string accepted by `format!()`
+///    arg1 = value1,         // optional, can be repeated
+///    ..                     // as many additional arg = value pairs as desired
+/// )
+/// ```
+///
+/// The format string only accepts arguments by name.
+///
+/// These can be automatically captured from the surrounding scope by the macro,
+/// in which case they will render in the message but will not be.
+///
+/// # Examples
+///
+/// ```rust,no_run
+/// // Span without any arguments
+/// let root_span = logfire::span!("Root span");
+///
+/// // Span with attributes x and y
+/// let span = logfire::span!(parent: &root_span, "Child span", x = 42, y = "hello");
+///
+/// // Typically a span will be "entered" to set the parent implicitly
+/// root_span.in_scope(|| {
+///     // This span will be a child of root_span
+///     let child_span = logfire::span!("Nested span", x = 42, y = "hello");
+///
+///     // Debug-level child span
+///     let debug_span = logfire::span!(level: tracing::Level::DEBUG, "Debugging", x = 42, y = "hello");
+/// });
+///
+/// // With x included in the formatted message but not as an attribute
+/// let x = 42;
+/// let span = logfire::span!("Span with x = {x}, y = {y}", y = "hello");
+/// ```
 #[macro_export]
 macro_rules! span {
     (parent: $parent:expr, level: $level:expr, $format:expr $(, $arg:ident = $value:expr)* $(,)?) => {
@@ -75,6 +118,58 @@ macro_rules! debug {
 }
 
 /// Export a log message at the specified level.
+///
+/// # Syntax
+///
+/// The macro accepts the following syntax:
+///
+/// ```rust,ignore
+/// log!(
+///    parent: tracing::Span, // optional, can emit this
+///    tracing::Level,        // required, see `info!` and variants for convenience
+///    "format string",       // required, must be a format string accepted by `format!()`
+///    arg1 = value1,         // optional, can be repeated
+///    ..                     // as many additional arg = value pairs as desired
+/// )
+/// ```
+///
+/// The format string only accepts arguments by name.
+///
+/// These can be automatically captured from the surrounding scope by the macro,
+/// in which case they will render in the message but will not be.
+///
+/// # Examples
+///
+/// ```rust,no_run
+/// use tracing::Level;
+///
+/// // Root span
+/// let root_span = logfire::span!("Root span");
+///
+/// // Log with attributes x and y
+/// logfire::log!(parent: &root_span, Level::INFO, "Child log", x = 42, y = "hello");
+/// // or
+/// logfire::info!(parent: &root_span, "Child log", x = 42, y = "hello");
+///
+/// // Typically a span will be "entered" to set the parent implicitly
+/// root_span.in_scope(|| {
+///     // This logf will be a child of root_span
+///     logfire::log!(level::INFO, "Nested log", x = 42, y = "hello");
+///     // or
+///     logfire::info!("Nested log", x = 42, y = "hello");
+///
+///     // Debug-level child log
+///     logfire::log!(Level::DEBUG, "Debugging", x = 42, y = "hello");
+///     // or
+///     logfire::debug!("Debugging", x = 42, y = "hello");
+/// });
+///
+/// // With x included in the formatted message but not as an attribute
+/// let x = 42;
+/// logfire::log!(Level::INFO, "Log with x = {x}, y = {y}", y = "hello");
+/// // or
+/// logfire::info!("Log with x = {x}, y = {y}", y = "hello");
+/// ```
 #[macro_export]
 macro_rules! log {
     (parent: $parent:expr, $level:expr, $format:expr, $($($arg:ident = $value:expr),+)?) => {{