@@ -16,22 +16,27 @@ $ bundle add async-utilization
1616
1717The key components are:
1818
19- - {ruby Async::Utilization::Registry}: Thread-local singleton for emitting metrics
20- - {ruby Async::Utilization::Schema}: Defines the binary layout for serialization
21- - {ruby Async::Utilization::Observer}: Writes metrics to shared memory using the schema
19+ - {ruby Async::Utilization::Registry}: Thread-local singleton for emitting metrics.
20+ - {ruby Async::Utilization::Schema}: Defines the binary layout for serialization.
21+ - {ruby Async::Utilization::Observer}: Writes metrics to shared memory using the schema.
22+ - {ruby Async::Utilization::Metric}: Caches metric value and fast path for direct buffer updates.
2223
2324## Basic Usage
2425
25- The simplest way to use ` async-utilization ` is to emit metrics directly :
26+ The recommended way to use ` async-utilization ` is to get a cached metric reference and use it :
2627
2728``` ruby
2829require " async/utilization"
2930
30- # Increment a metric
31- Async ::Utilization .increment(:total_requests )
31+ # Get metrics:
32+ total_requests = Async ::Utilization .metric(:total_requests )
33+ active_requests = Async ::Utilization .metric(:active_requests )
3234
33- # Increment with auto-decrement
34- Async ::Utilization .increment(:active_requests ) do
35+ # Increment a metric:
36+ total_requests.increment
37+
38+ # Increment with auto-decrement:
39+ active_requests.increment do
3540 # Handle request - automatically decrements when block completes
3641end
3742```
@@ -63,8 +68,9 @@ observer = Async::Utilization::Observer.open(
6368# Set observer - metrics will now be written to shared memory
6469Async ::Utilization .observer = observer
6570
66- # Now all metrics are written to shared memory
67- Async ::Utilization .increment(:total_requests )
71+ # All metrics are written directly to shared memory:
72+ total_requests = Async ::Utilization .metric(:total_requests )
73+ total_requests.increment
6874```
6975
7076The observer automatically handles page alignment requirements for memory mapping, so you can use any segment size and offset. The supervisor process can then read these metrics from shared memory to aggregate utilization across all workers.
0 commit comments