docs: revamp README to match Python & JS SDKs better (#65)

Author: davidhewitt

README.md

@@ -9,17 +9,15 @@
   <a href="https://logfire.pydantic.dev/docs/join-slack/"><img src="https://img.shields.io/badge/Slack-Join%20Slack-4A154B?logo=slack" alt="Join Slack" /></a>
 </p>
 
-> ***Initial release - feedback wanted!***
->
-> This is an initial release of the Logfire Rust SDK. We've been using it internally to build Logfire for some time, and it is serving us well. As we're using it ourselves in production, we figured it's ready for everyone else also using Logfire.
->
-> We are continually iterating to make this SDK better. We'd love your feedback on all aspects of the SDK and are keen to make the design as idiomatic and performant as possible. There are also many features currently supported by the Python SDK which are not yet supported by this SDK; please open issues to help us prioritize these to close this gap.
->
-> In particular, the current coupling to `tracing` is an open design point. By building on top of tracing we get widest compatibility and a relatively simple SDK, however to make Logfire-specific adjustments we might prefer in future to move `tracing` to be an optional integration.
-
 From the team behind Pydantic, **Logfire** is an observability platform built on the same belief as our
 open source library — that the most powerful tools can be easy to use.
 
+What sets Logfire apart:
+
+- **Simple and Powerful:** Logfire's dashboard is simple relative to the power it provides, ensuring your entire engineering team will actually use it.
+- **SQL:** Query your data using standard SQL — all the control and (for many) nothing new to learn. Using SQL also means you can query your data with existing BI tools and database querying libraries.
+- **OpenTelemetry:** Logfire is an opinionated wrapper around OpenTelemetry, allowing you to leverage existing tooling, infrastructure, and instrumentation for many common Python packages, and enabling support for virtually any language. We offer full support for all OpenTelemetry signals (traces, metrics and logs).
+
 This repository contains the Rust SDK for instrumenting with Logfire.
 
 See also:
@@ -33,35 +31,74 @@ The Logfire server application for recording and displaying data is closed sourc
 
 First [set up a Logfire project](https://logfire.pydantic.dev/docs/#logfire) and [create a write token](https://logfire.pydantic.dev/docs/how-to-guides/create-write-tokens/). You'll need to set this token as an environment variable (`LOGFIRE_TOKEN`) to export to Logfire.
 
-Here's a simple manual tracing (aka logging) example:
-
-```rust
-
-fn main() -> Result<(), Box<dyn std::error::Error>> {
-    let shutdown_handler = logfire::configure()
-        .install_panic_handler()
-        .finish()?;
+With a logfire project set up, start by adding the `logfire` crate to your `Cargo.toml`:
 
-    logfire::info!("Hello, {name}!", name = "world");
+```toml
+[dependencies]
+logfire = "0.6"
+```
 
-    {
-        let _span = logfire::span!(
-            "Asking the user their {question}",
-            question = "age",
-        ).entered();
+Then, you can use the SDK to instrument the code. Here's a simple example which counts the size of files in the current directory, creating spans for the full operation and each file read:
 
-        println!("When were you born [YYYY-mm-dd]?");
-        let mut dob = String::new();
-        std::io::stdin().read_line(&mut dob)?;
 
-        logfire::debug!("dob={dob}", dob = dob.trim().to_owned());
-    }
+```rust
+use std::fs;
+use std::sync::LazyLock;
+
+use opentelemetry::{KeyValue, metrics::Counter};
+
+type Result<T> = std::result::Result<T, Box<dyn std::error::Error>>;
+
+fn main() -> Result<()> {
+    let shutdown_handler = logfire::configure().install_panic_handler().finish()?;
+
+    let mut total_size = 0u64;
+
+    let cwd = std::env::current_dir()?;
+
+    logfire::span!("counting size of {cwd}", cwd = cwd.display().to_string()).in_scope(|| {
+        let entries = fs::read_dir(&cwd)?;
+        for entry in entries {
+            let entry = entry?;
+            let path = entry.path();
+
+            let _span = logfire::span!(
+                "reading {path}",
+                path = path
+                    .strip_prefix(&cwd)
+                    .unwrap_or(&path)
+                    .display()
+                    .to_string()
+            )
+            .entered();
+
+            let metadata = entry.metadata()?;
+            if metadata.is_file() {
+                total_size += metadata.len();
+            }
+        }
+        Result::Ok(())
+    })?;
+
+    logfire::info!(
+        "total size of {cwd} is {size} bytes",
+        cwd = cwd.display().to_string(),
+        size = total_size as i64
+    );
 
     shutdown_handler.shutdown()?;
     Ok(())
 }
 ```
 
+(Read the [Logfire concepts documentation](https://logfire.pydantic.dev/docs/concepts/) for additional detail on spans, events, and further Logfire concepts.)
+
+See additional examples in the [examples directory](https://github.com/pydantic/logfire-rust/tree/main/examples):
+
+- [basic](https://github.com/pydantic/logfire-rust/tree/main/examples/basic.rs)
+- [axum webserver](https://github.com/pydantic/logfire-rust/tree/main/examples/axum.rs)
+- [actix webserver](https://github.com/pydantic/logfire-rust/tree/main/examples/actix-web.rs)
+
 ### Integration
 
 Logfire's Rust SDK is currently built directly upon [`tracing`](https://docs.rs/tracing/latest/tracing/) and [`opentelemetry`](https://github.com/open-telemetry/opentelemetry-rust/).

examples/basic.rs

@@ -1,35 +1,57 @@
 //! A basic example of using Logfire to instrument Rust code.
 
+use std::fs;
 use std::sync::LazyLock;
 
 use opentelemetry::{KeyValue, metrics::Counter};
 
-static BASIC_COUNTER: LazyLock<Counter<u64>> = LazyLock::new(|| {
-    logfire::u64_counter("basic_counter")
+static FILES_COUNTER: LazyLock<Counter<u64>> = LazyLock::new(|| {
+    logfire::u64_counter("FILES_COUNTER")
         .with_description("Just an example")
         .with_unit("s")
         .build()
 });
 
-fn main() -> Result<(), Box<dyn std::error::Error>> {
-    let shutdown_handler = logfire::configure()
-        .install_panic_handler()
-        .with_console(None)
-        .finish()?;
-
-    tracing::info!("Hello, world!");
-
-    {
-        let _span = logfire::span!("Asking the user their {question}", question = "age").entered();
-
-        println!("When were you born [YYYY-mm-dd]?");
-        let mut dob = String::new();
-        std::io::stdin().read_line(&mut dob)?;
-
-        logfire::debug!("dob={dob}", dob = dob.trim().to_owned());
-    }
-
-    BASIC_COUNTER.add(1, &[KeyValue::new("process", "abc123")]);
+type Result<T> = std::result::Result<T, Box<dyn std::error::Error>>;
+
+fn main() -> Result<()> {
+    let shutdown_handler = logfire::configure().install_panic_handler().finish()?;
+
+    let mut total_size = 0u64;
+
+    let cwd = std::env::current_dir()?;
+
+    logfire::span!("counting size of {cwd}", cwd = cwd.display().to_string()).in_scope(|| {
+        let entries = fs::read_dir(&cwd)?;
+        for entry in entries {
+            let entry = entry?;
+            let path = entry.path();
+
+            let _span = logfire::span!(
+                "reading {path}",
+                path = path
+                    .strip_prefix(&cwd)
+                    .unwrap_or(&path)
+                    .display()
+                    .to_string()
+            )
+            .entered();
+
+            FILES_COUNTER.add(1, &[KeyValue::new("process", "abc123")]);
+
+            let metadata = entry.metadata()?;
+            if metadata.is_file() {
+                total_size += metadata.len();
+            }
+        }
+        Result::Ok(())
+    })?;
+
+    logfire::info!(
+        "total size of {cwd} is {size} bytes",
+        cwd = cwd.display().to_string(),
+        size = total_size as i64
+    );
 
     shutdown_handler.shutdown()?;
     Ok(())