rust_observer 0.2.1

Express telemetry rust SDK
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

# Rust Observer: Observability for High-Performance Systems

Rust Observer is a high-performance, concurrent observability library designed for mission-critical Rust applications. It provides unified logging, tracing, and metrics collection with minimal runtime impact, optimized for systems with strict performance requirements.

> Rust Observer is part of the Express Telemetry Project.

## Core Principles

1. **Concurrency-first design**: Built from the ground up for highly concurrent systems.
2. **Unified observability**: Integrates logging, tracing, and metrics in a cohesive manner.
3. **Extensibility**: Easily adaptable to custom enterprise environments.

## Key Features

- **Non-blocking operations**: All telemetry operations are non-blocking, preserving application responsiveness.
- **Lock-free architecture**: Utilizes atomic operations and lock-free data structures to minimize contention.
- **Adaptive sampling**: Implements intelligent sampling to manage data volume without loss of critical information.
- **Buffered, batched exports**: Optimizes I/O operations for improved throughput.
- **Fine-grained configuration**: Offers detailed tuning options via TOML configuration.

## Integration

1. Add to `Cargo.toml`:
   ```toml
   [dependencies]
   rust_observer = "0.2.1"
   ```

2. Initialize in your application:
   ```rust
   use rust_observer::initialize_observability;

   #[tokio::main]
   async fn main() -> Result<(), Box<dyn std::error::Error>> {
       initialize_observability("config/observability.toml")?;
       // Application logic
       Ok(())
   }
   ```

## Usage Examples

### Structured Logging
```rust
use rust_observer::logging::info;

info!("Transaction processed", attrs: {
    "transaction_id" => tx.id,
    "amount" => tx.amount,
    "currency" => tx.currency,
    "status" => tx.status
});
```

### Distributed Tracing
```rust
use rust_observer::tracing::{trace, OptionalTraceContext};

#[trace(Server)]
async fn process_order(ctx: OptionalTraceContext, order: Order) -> Result<(), Error> {
    validate_order(ctx.clone(), &order)?;
    update_inventory(ctx.clone(), &order)?;
    process_payment(ctx.clone(), &order)?;
    Ok(())
}
```

### Interval-based Metrics
```rust
use rust_observer::metrics::HttpMetrics;

async fn handle_request(req: Request) -> Response {
    let start = Instant::now();
    let response = process_request(req).await;
    let duration = start.elapsed().as_millis() as u64;

    HttpMetrics::increment_counter().await;
    HttpMetrics::update_method_count(req.method()).await;
    HttpMetrics::update_status_code(response.status()).await;
    HttpMetrics::update_request_duration(req.method(), response.status(), duration).await;

    response
}
```

## Advanced Configuration

Rust Observer supports fine-grained configuration via TOML:

```toml
[project]
name = "falcon-9"
app_name = "flight-computer"
service_name = "telemetry-processor"

[logging]
enabled = true
level = "INFO"

[logging.exporter]
type = "stdout"
format = "extended"

[tracing]
enabled = true

[tracing.exporter]
type = "stdout"
format = "extended"

[metrics]
enabled = true
interval_secs = 5

[metrics.exporter]
type = "stdout"
format = "extended"

[metrics.http]
enabled = true

[metrics.grpc]
enabled = true

[metrics.websockets]
enabled = true

[metrics.system]
enabled = true

[metrics.process]
enabled = true
```

## Deployment Considerations

- Supports horizontal scaling with consistent performance characteristics.
- Integrates seamlessly with service mesh technologies like Istio for additional observability layers.