Skip to content

Commit 7df7d36

Browse files
josecelanojosecelano
committed
docs(metrics): enhance README with comprehensive documentation and examples
- Add detailed overview and key features section - Include quick start guide with practical usage examples - Document architecture with core components and type system - Add comprehensive development guide with building, testing, and coverage - Include performance considerations and compatibility notes - Add contributing guidelines and related projects - Transform from basic description to full developer documentation - Update cSpell.json with new technical terms (println, serde) This provides much better onboarding for developers and users of the metrics library.
1 parent dfd950d commit 7df7d36

File tree

2 files changed

+177
-10
lines changed

2 files changed

+177
-10
lines changed

‎packages/metrics/README.md‎

Lines changed: 175 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -1,37 +1,202 @@
11
# Torrust Tracker Metrics
22

3-
A library with the metrics types used by the [Torrust Tracker](https://github.com/torrust/torrust-tracker) packages.
3+
A comprehensive metrics library providing type-safe metric collection, aggregation, and Prometheus export functionality for the [Torrust Tracker](https://github.com/torrust/torrust-tracker) ecosystem.
4+
5+
## Overview
6+
7+
This library offers a robust metrics system designed specifically for tracking and monitoring BitTorrent tracker performance. It provides type-safe metric collection with support for labels, time-series data, and multiple export formats including Prometheus.
8+
9+
## Key Features
10+
11+
- **Type-Safe Metrics**: Strongly typed `Counter` and `Gauge` metrics with compile-time guarantees
12+
- **Label Support**: Rich labeling system for multi-dimensional metrics
13+
- **Time-Series Data**: Built-in support for timestamped samples
14+
- **Prometheus Export**: Native Prometheus format serialization
15+
- **Aggregation Functions**: Sum operations with mathematically appropriate return types
16+
- **JSON Serialization**: Full serde support for all metric types
17+
- **Memory Efficient**: Optimized data structures for high-performance scenarios
18+
19+
## Quick Start
20+
21+
Add this to your `Cargo.toml`:
22+
23+
```toml
24+
[dependencies]
25+
torrust-tracker-metrics = "3.0.0"
26+
```
27+
28+
### Basic Usage
29+
30+
```rust
31+
use torrust_tracker_metrics::{
32+
metric_collection::MetricCollection,
33+
label::{LabelSet, LabelValue},
34+
metric_name, label_name,
35+
};
36+
use torrust_tracker_primitives::DurationSinceUnixEpoch;
37+
38+
// Create a metric collection
39+
let mut metrics = MetricCollection::default();
40+
41+
// Define labels
42+
let labels: LabelSet = [
43+
(label_name!("server"), LabelValue::new("tracker-01")),
44+
(label_name!("protocol"), LabelValue::new("http")),
45+
].into();
46+
47+
// Record metrics
48+
let time = DurationSinceUnixEpoch::from_secs(1234567890);
49+
metrics.increment_counter(
50+
&metric_name!("requests_total"),
51+
&labels,
52+
time,
53+
)?;
54+
55+
metrics.set_gauge(
56+
&metric_name!("active_connections"),
57+
&labels,
58+
42.0,
59+
time,
60+
)?;
61+
62+
// Export to Prometheus format
63+
let prometheus_output = metrics.to_prometheus();
64+
println!("{}", prometheus_output);
65+
```
66+
67+
### Metric Aggregation
68+
69+
```rust
70+
use torrust_tracker_metrics::metric_collection::aggregate::Sum;
71+
72+
// Sum all counter values matching specific labels
73+
let total_requests = metrics.sum(
74+
&metric_name!("requests_total"),
75+
&[("server", "tracker-01")].into(),
76+
);
77+
78+
println!("Total requests: {:?}", total_requests);
79+
```
80+
81+
## Architecture
82+
83+
### Core Components
84+
85+
- **`Counter`**: Monotonically increasing integer values (u64)
86+
- **`Gauge`**: Arbitrary floating-point values that can increase or decrease (f64)
87+
- **`Metric<T>`**: Generic metric container with metadata (name, description, unit)
88+
- **`MetricCollection`**: Type-safe collection managing both counters and gauges
89+
- **`LabelSet`**: Key-value pairs for metric dimensionality
90+
- **`Sample`**: Timestamped metric values with associated labels
91+
92+
### Type System
93+
94+
The library uses Rust's type system to ensure metric safety:
95+
96+
```rust
97+
// Counter operations return u64
98+
let counter_sum: Option<u64> = counter_collection.sum(&name, &labels);
99+
100+
// Gauge operations return f64
101+
let gauge_sum: Option<f64> = gauge_collection.sum(&name, &labels);
102+
103+
// Mixed collections convert to f64 for compatibility
104+
let mixed_sum: Option<f64> = metric_collection.sum(&name, &labels);
105+
```
106+
107+
### Module Structure
108+
109+
```output
110+
src/
111+
├── counter.rs # Counter metric type
112+
├── gauge.rs # Gauge metric type
113+
├── metric/ # Generic metric container
114+
│ ├── mod.rs
115+
│ ├── name.rs # Metric naming
116+
│ ├── description.rs # Metric descriptions
117+
│ └── aggregate/ # Metric-level aggregations
118+
├── metric_collection/ # Collection management
119+
│ ├── mod.rs
120+
│ └── aggregate/ # Collection-level aggregations
121+
├── label/ # Label system
122+
│ ├── name.rs # Label names
123+
│ ├── value.rs # Label values
124+
│ └── set.rs # Label collections
125+
├── sample.rs # Timestamped values
126+
├── sample_collection.rs # Sample management
127+
├── prometheus.rs # Prometheus export
128+
└── unit.rs # Measurement units
129+
```
4130

5131
## Documentation
6132

7-
[Crate documentation](https://docs.rs/torrust-tracker-metrics).
133+
- [Crate documentation](https://docs.rs/torrust-tracker-metrics)
134+
- [API Reference](https://docs.rs/torrust-tracker-metrics/latest/torrust_tracker_metrics/)
135+
136+
## Development
8137

9-
## Testing
138+
### Code Coverage
10139

11-
Run coverage report:
140+
Run basic coverage report:
12141

13142
```console
14143
cargo llvm-cov --package torrust-tracker-metrics
15144
```
16145

17-
Generate LCOV report with `llvm-cov` (for Visual Studio Code extension):
146+
Generate LCOV report (for IDE integration):
18147

19148
```console
20149
mkdir -p ./.coverage
21-
cargo llvm-cov --package torrust-tracker-metrics --lcov --output-path=./.coverage/lcov.info
150+
cargo llvm-cov --package torrust-tracker-metrics --lcov --output-path=./.coverage/lcov.info
22151
```
23152

24-
Generate HTML report with `llvm-cov`:
153+
Generate detailed HTML coverage report:
154+
155+
Generate detailed HTML coverage report:
25156

26157
```console
27158
mkdir -p ./.coverage
28-
cargo llvm-cov --package torrust-tracker-metrics --html --output-dir ./.coverage
159+
cargo llvm-cov --package torrust-tracker-metrics --html --output-dir ./.coverage
29160
```
30161

162+
Open the coverage report in your browser:
163+
164+
```console
165+
open ./.coverage/index.html # macOS
166+
xdg-open ./.coverage/index.html # Linux
167+
```
168+
169+
## Performance Considerations
170+
171+
- **Memory Usage**: Metrics are stored in-memory with efficient HashMap-based collections
172+
- **Label Cardinality**: Be mindful of label combinations as they create separate time series
173+
- **Aggregation**: Sum operations are optimized for both single-type and mixed collections
174+
175+
## Compatibility
176+
177+
This library is designed to be compatible with the standard Rust [metrics](https://crates.io/crates/metrics) crate ecosystem where possible.
178+
179+
## Contributing
180+
181+
We welcome contributions! Please see the main [Torrust Tracker repository](https://github.com/torrust/torrust-tracker) for contribution guidelines.
182+
183+
### Reporting Issues
184+
185+
- [Bug Reports](https://github.com/torrust/torrust-tracker/issues/new?template=bug_report.md)
186+
- [Feature Requests](https://github.com/torrust/torrust-tracker/issues/new?template=feature_request.md)
187+
31188
## Acknowledgements
32189

33-
We copied some parts like units or function names and signatures from the crate [metrics](https://crates.io/crates/metrics) because we wanted to make it compatible as much as possible with it. In the future, we may consider using the `metrics` crate directly instead of maintaining our own version.
190+
This library draws inspiration from the Rust [metrics](https://crates.io/crates/metrics) crate, incorporating compatible APIs and naming conventions where possible. We may consider migrating to the standard metrics crate in future versions while maintaining our specialized functionality.
191+
192+
Special thanks to the Rust metrics ecosystem contributors for establishing excellent patterns for metrics collection and export.
34193

35194
## License
36195

37-
The project is licensed under the terms of the [GNU AFFERO GENERAL PUBLIC LICENSE](./LICENSE).
196+
This project is licensed under the [GNU AFFERO GENERAL PUBLIC LICENSE v3.0](./LICENSE).
197+
198+
## Related Projects
199+
200+
- [Torrust Tracker](https://github.com/torrust/torrust-tracker) - The main BitTorrent tracker
201+
- [metrics](https://crates.io/crates/metrics) - Standard Rust metrics facade
202+
- [prometheus](https://crates.io/crates/prometheus) - Prometheus client library

‎packages/metrics/cSpell.json‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -6,7 +6,9 @@
66
"Kibibytes",
77
"Mebibytes",
88
"ñaca",
9+
"println",
910
"rstest",
11+
"serde",
1012
"subsec",
1113
"Tebibytes",
1214
"thiserror"

0 commit comments

Comments
 (0)