rust_mobile_telemetry 0.1.3

Observability instrumentation (tracing + metrics) for mobile-backend applications or embedded / edge services.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145

# Rust Mobile Telemetry 🚀


[![Crates.io](https://img.shields.io/crates/v/rust_mobile_telemetry.svg)](https://crates.io/crates/rust_mobile_telemetry)
[![Documentation](https://docs.rs/rust_mobile_telemetry/badge.svg)](https://docs.rs/rust_mobile_telemetry)
[![License](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/emorilebo/rust_mobile_telemetry/blob/main/LICENSE)

**Observability made simple for mobile backends and edge services.**

`rust_mobile_telemetry` is a production-ready Rust crate that helps you understand *exactly* what is happening in your application. It provides **tracing** (timelines of operations) and **metrics** (counters, gauges) with minimal setup, tailored for mobile-backend environments where device metadata (like OS version or Device ID) is critical for debugging.

## Why use this?


- **🔍 Instant Visibility**: See full request traces and performance metrics immediately.
- **📱 Mobile-First**: Automatically attaches mobile metadata (App Version, OS, Device ID) to every trace.
- **⚡ Zero-Config Defaults**: Works out of the box with sensible defaults, but fully customizable.
- **🔌 OpenTelemetry Standard**: Built on the industry-standard OpenTelemetry ecosystem, compatible with Jaeger, Prometheus, Honeycomb, Datadog, and more.

---

## 📦 Installation


Add this to your `Cargo.toml`:

```toml
[dependencies]
rust_mobile_telemetry = "0.1.1"
```

---

## 🚀 Getting Started


### 1. Initialize Telemetry


Call `init_telemetry` at the start of your `main` function. This sets up the global tracer and meter.

```rust
use rust_mobile_telemetry::{ConfigBuilder, ExporterType, init_telemetry, MobileMetadata};

#[tokio::main]

async fn main() -> Result<(), Box<dyn std::error::Error + Send + Sync>> {
    // 1. Define metadata about the client (optional but recommended)
    let metadata = MobileMetadata {
        app_version: Some("1.0.0".to_string()),
        device_os: Some("iOS 17.2".to_string()),
        device_id: Some("user-device-uuid-123".to_string()),
    };

    // 2. Build configuration
    let config = ConfigBuilder::new()
        .service_name("my-mobile-backend")
        .exporter_type(ExporterType::Console) // Use Console for local dev, Otlp for production
        .mobile_metadata(metadata)
        .build();

    // 3. Initialize!
    init_telemetry(config)?;
    
    println!("Telemetry initialized! 📡");
    
    // ... your app logic ...
    
    // 4. Ensure data is flushed before exit
    rust_mobile_telemetry::init::shutdown_telemetry();
    
    Ok(())
}
```

### 2. Instrument Your Code


Wrap operations in spans to track how long they take.

```rust
use rust_mobile_telemetry::with_span;

fn process_user_login() {
    with_span("process_login", || {
        // Your logic here...
        println!("Logging in user...");
        std::thread::sleep(std::time::Duration::from_millis(50));
    });
}
```

### 3. Record Metrics


Count events or measure latencies.

```rust
use rust_mobile_telemetry::instrumentation::{get_counter, get_histogram};

fn handle_request() {
    // Counters: Good for "how many times did X happen?"
    let requests = get_counter("http_requests_total", "Total HTTP requests");
    requests.add(1, &[]);

    // Histograms: Good for "how long did X take?"
    let latency = get_histogram("http_request_duration", "Request duration in seconds");
    latency.record(0.123, &[]);
}
```

---

## ⚙️ Configuration Options


You can configure the library using the `ConfigBuilder` or Environment Variables.

| Option | Builder Method | Env Variable | Description |
|--------|---------------|--------------|-------------|
| **Service Name** | `.service_name("name")` | `OTEL_SERVICE_NAME` | Name of your service (e.g., `auth-api`). |
| **Exporter** | `.exporter_type(type)` | N/A | Where to send data: `Console` (stdout) or `Otlp` (collector). |
| **OTLP Endpoint** | `.otlp_endpoint("url")` | `OTEL_EXPORTER_OTLP_ENDPOINT` | URL for OTLP exporter (default: `http://localhost:4317`). |
| **Metrics** | `.enable_metrics(bool)` | N/A | Enable/disable metrics collection. |
| **Tracing** | `.enable_tracing(bool)` | N/A | Enable/disable tracing. |

### Example: Production Config (OTLP)


For production, you typically want to send data to an OpenTelemetry Collector or a vendor (like Honeycomb/Datadog).

```rust
let config = ConfigBuilder::new()
    .service_name("production-backend")
    .exporter_type(ExporterType::Otlp) // Send over network
    .otlp_endpoint("http://otel-collector:4317")
    .build();
```

---

## ❓ Troubleshooting


### "File locking" error on Windows

If you see `os error 32` during build or publish, it's likely an antivirus or the OS locking the build directory.
**Fix**: Restart your terminal or computer.

### No output in Console?

Ensure you initialized with `ExporterType::Console` and that your application runs long enough to flush data (or call `shutdown_telemetry()`).

---

## 📄 License


MIT License. See [LICENSE](LICENSE) for details.