chore(metrics)!: align names with Prometheus base units

Rename Firewood metrics to follow Prometheus naming best practices: https://prometheus.io/docs/practices/naming/

Examples (old -> new):
- proposals -> proposals_total
- commit.latency_ms -> commit.latency_seconds_total
- io.read_ms -> io.read_seconds_total
- space.reused -> space.reused_bytes_total
- commit_ms_bucket -> commit_duration_seconds

BREAKING CHANGE: all metric names changed; update dashboards, alerts, and external consumers.

Author: rkuris

METRICS.md

@@ -62,8 +62,8 @@ See the [FFI README](ffi/README.md) for more details on FFI metrics configuratio
   - Labels: `success=true|false`
   - Use: Monitor proposal creation success rate
 
-- **`proposal.create_ms`** (counter with `success` label)
-  - Description: Time spent creating proposals in milliseconds
+- **`proposal.create_s`** (counter with `success` label)
+  - Description: Time spent creating proposals in seconds (accumulated as nanoseconds)
   - Labels: `success=true|false`
   - Use: Track proposal creation latency
 
@@ -72,8 +72,8 @@ See the [FFI README](ffi/README.md) for more details on FFI metrics configuratio
   - Labels: `success=true|false`
   - Use: Monitor commit success rate
 
-- **`proposal.commit_ms`** (counter with `success` label)
-  - Description: Time spent committing proposals in milliseconds
+- **`proposal.commit_s`** (counter with `success` label)
+  - Description: Time spent committing proposals in seconds (accumulated as nanoseconds)
   - Labels: `success=true|false`
   - Use: Track commit latency and identify slow commits
 
@@ -142,14 +142,14 @@ See the [FFI README](ffi/README.md) for more details on FFI metrics configuratio
   - Description: Total number of I/O read operations
   - Use: Track I/O operation count
 
-- **`io.read_ms`** (counter)
-  - Description: Total time spent in I/O reads in milliseconds
+- **`io.read_s`** (counter)
+  - Description: Total time spent in I/O reads in seconds (accumulated as nanoseconds)
   - Use: Identify I/O bottlenecks and disk performance issues
 
 #### Node Persistence
 
 - **`flush_nodes`** (counter)
-  - Description: Cumulative time spent flushing nodes to disk in milliseconds (counter incremented by flush duration)
+  - Description: Cumulative time spent flushing nodes to disk in seconds (accumulated as nanoseconds)
   - Use: Monitor flush performance and identify slow disk writes; calculate average flush time using rate()
 
 ### Memory Management
@@ -202,30 +202,42 @@ These metrics are specific to the Foreign Function Interface (Go) layer:
   - Description: Count of batch operations completed
   - Use: Track FFI batch throughput
 
-- **`ffi.batch_ms`** (counter)
-  - Description: Time spent processing batches in milliseconds
+- **`ffi.batch_s`** (counter)
+  - Description: Time spent processing batches in seconds (accumulated as nanoseconds)
   - Use: Monitor FFI batch latency
 
+- **`ffi.batch_seconds_bucket`** (histogram)
+  - Description: Histogram of batch processing durations in seconds
+  - Use: Analyze batch latency distribution
+
 #### Proposal Operations
 
 - **`ffi.propose`** (counter)
   - Description: Count of proposal operations via FFI
   - Use: Track FFI proposal throughput
 
-- **`ffi.propose_ms`** (counter)
-  - Description: Time spent creating proposals via FFI in milliseconds
+- **`ffi.propose_s`** (counter)
+  - Description: Time spent creating proposals via FFI in seconds (accumulated as nanoseconds)
   - Use: Monitor FFI proposal latency
 
+- **`ffi.propose_seconds_bucket`** (histogram)
+  - Description: Histogram of proposal creation durations in seconds
+  - Use: Analyze proposal latency distribution
+
 #### Commit Operations
 
 - **`ffi.commit`** (counter)
   - Description: Count of commit operations via FFI
   - Use: Track FFI commit throughput
 
-- **`ffi.commit_ms`** (counter)
-  - Description: Time spent committing via FFI in milliseconds
+- **`ffi.commit_s`** (counter)
+  - Description: Time spent committing via FFI in seconds (accumulated as nanoseconds)
   - Use: Monitor FFI commit latency
 
+- **`ffi.commit_seconds_bucket`** (histogram)
+  - Description: Histogram of commit durations in seconds
+  - Use: Analyze commit latency distribution
+
 #### View Caching
 
 - **`ffi.cached_view.hit`** (counter)
@@ -240,12 +252,12 @@ These metrics are specific to the Foreign Function Interface (Go) layer:
 
 ### Performance Monitoring
 
-1. **Latency Tracking**: The `*_ms` metrics track operation durations. Monitor these for:
+1. **Latency Tracking**: The `*_s` metrics track operation durations in seconds (accumulated as nanoseconds for precision). Monitor these for:
    - Sudden increases indicating performance degradation
    - Baseline establishment for SLA monitoring
    - Correlation with system load
 
-2. **Throughput Monitoring**: Counter metrics without `_ms` suffix track operation counts:
+2. **Throughput Monitoring**: Counter metrics without `_s` suffix track operation counts:
    - Rate of change indicates throughput
    - Compare with expected load patterns
    - Identify anomalies in operation rates
@@ -288,8 +300,9 @@ These metrics are specific to the Foreign Function Interface (Go) layer:
 For Prometheus-based monitoring (note: metric names use underscores in queries):
 
 ```promql
-# Average commit latency over 5 minutes
-rate(firewood_proposal_commit_ms[5m]) / rate(firewood_proposal_commit[5m])
+# Average commit latency over 5 minutes (in seconds)
+# Note: counters store nanoseconds, so divide by 1e9 to get seconds
+rate(firewood_proposal_commit_s[5m]) / 1e9 / rate(firewood_proposal_commit[5m])
 
 # Cache hit rate
 sum(rate(firewood_cache_node{type="hit"}[5m])) /

METRICS_UPDATE_SUMMARY.md

@@ -0,0 +1,120 @@
+# Metrics Naming Update Summary
+
+## Overview
+
+All Firewood metrics have been updated to follow Prometheus naming conventions:
+
+1. **Base units**: seconds (not milliseconds), bytes (not kilobytes)
+2. **Plural units**: `_seconds` not `_second`, `_bytes` not `_byte`  
+3. **Accumulating counters**: Must have `_total` suffix
+4. **Histograms**: Named `*_duration_seconds` for timing observations
+
+## Changed Metric Names
+
+### Firewood Core
+
+| Old Name | New Name | Type | Unit |
+|----------|----------|------|------|
+| `proposals` | `proposals_total` | counter | count |
+| `proposals.created` | `proposals.created_total` | counter | count |
+| `proposals.discarded` | `proposals.discarded_total` | counter | count |
+| `insert` | `insert_total` | counter | count |
+| `remove` | `remove_total` | counter | count |
+| `change_proof.next` | `change_proof.next_total` | counter | count |
+| `commit_latency_s` | `commit_latency_seconds_total` | counter | nanoseconds |
+
+### Storage Layer
+
+| Old Name | New Name | Type | Unit |
+|----------|----------|------|------|
+| `space.reused` | `space.reused_bytes_total` | counter | bytes |
+| `space.from_end` | `space.from_end_bytes_total` | counter | bytes |
+| `space.freed` | `space.freed_bytes_total` | counter | bytes |
+| `delete_node` | `delete_node_total` | counter | count |
+| `flush_nodes` | `flush_nodes_seconds_total` | counter | nanoseconds |
+| `read_node` | `read_node_total` | counter | count |
+| `cache.node` | `cache.node_total` | counter | count |
+| `cache.freelist` | `cache.freelist_total` | counter | count |
+| `io.read_s` | `io.read_seconds_total` | counter | nanoseconds |
+| `io.read` | `io.read_total` | counter | count |
+| `proposals.reparented` | `proposals.reparented_total` | counter | count |
+| `ring.eagain_write_retry` | `ring.eagain_write_retry_total` | counter | count |
+| `ring.full` | `ring.full_total` | counter | count |
+| `ring.sq_wait` | `ring.sq_wait_total` | counter | count |
+| `ring.partial_write_retry` | `ring.partial_write_retry_total` | counter | count |
+
+### FFI Layer
+
+| Old Name | New Name | Type | Unit |
+|----------|----------|------|------|
+| `ffi.commit_s` | `ffi.commit_seconds_total` | counter | nanoseconds |
+| `ffi.commit` | `ffi.commit_total` | counter | count |
+| `ffi.commit_seconds_bucket` | `ffi.commit_duration_seconds` | histogram | seconds |
+| `ffi.propose_s` | `ffi.propose_seconds_total` | counter | nanoseconds |
+| `ffi.propose` | `ffi.propose_total` | counter | count |
+| `ffi.propose_seconds_bucket` | `ffi.propose_duration_seconds` | histogram | seconds |
+| `ffi.batch_s` | `ffi.batch_seconds_total` | counter | nanoseconds |
+| `ffi.batch` | `ffi.batch_total` | counter | count |
+| `ffi.batch_seconds_bucket` | `ffi.batch_duration_seconds` | histogram | seconds |
+| `ffi.cached_view.miss` | `ffi.cached_view.miss_total` | counter | count |
+| `ffi.cached_view.hit` | `ffi.cached_view.hit_total` | counter | count |
+| `firewood.ffi.merge` | `firewood.ffi.merge_total` | counter | count |
+
+### Replay Layer
+
+| Old Name | New Name | Type | Unit |
+|----------|----------|------|------|
+| `replay.propose_s` | `replay.propose_seconds_total` | counter | nanoseconds |
+| `replay.propose` | `replay.propose_total` | counter | count |
+| `replay.commit_s` | `replay.commit_seconds_total` | counter | nanoseconds |
+| `replay.commit` | `replay.commit_total` | counter | count |
+
+## Implementation Details
+
+### Time Metrics
+
+- **Counters** (e.g., `*_seconds_total`): Accumulate nanoseconds for precision, conceptually represent seconds
+  - Usage: `firewood_increment!(METRIC, elapsed.as_nanos() as u64)`
+  - Prometheus query: Divide by 1e9 to convert to seconds: `rate(metric_seconds_total[5m]) / 1e9`
+
+- **Histograms** (e.g., `*_duration_seconds`): Record observations in seconds
+  - Usage: `firewood_record!(METRIC, elapsed.as_f64(), expensive)`
+  - Prometheus automatically creates `_bucket`, `_sum`, `_count` suffixes
+
+### Size Metrics
+
+- All size metrics now explicitly include `_bytes_total` suffix
+- Values represent actual bytes (not KB/MB)
+
+## Breaking Changes
+
+⚠️ **This is a breaking change** for:
+- Prometheus dashboards and queries
+- Alerting rules
+- Any external monitoring systems
+
+### Migration Guide
+
+1. Update Prometheus queries:
+   ```promql
+   # Old
+   rate(firewood_ffi_commit_s[5m])
+   
+   # New
+   rate(firewood_ffi_commit_seconds_total[5m]) / 1e9
+   ```
+
+2. Update Grafana dashboards:
+   - Replace all old metric names with new ones
+   - Add `/1e9` division for timing counters
+
+3. Update alerting rules with new metric names
+
+## Testing
+
+All metrics tested with:
+```bash
+cargo check --workspace --features ethhash,logger --all-targets
+```
+
+Compilation successful ✅

ffi/metrics_test.go

@@ -22,20 +22,20 @@ import (
 var (
 	metricsPort     = uint16(3000)
 	expectedMetrics = map[string]dto.MetricType{
-		"ffi_batch":          dto.MetricType_COUNTER,
-		"proposal_commit":    dto.MetricType_COUNTER,
-		"proposal_commit_ms": dto.MetricType_COUNTER,
-		"ffi_propose_ms":     dto.MetricType_COUNTER,
-		"ffi_commit_ms":      dto.MetricType_COUNTER,
-		"ffi_batch_ms":       dto.MetricType_COUNTER,
-		"flush_nodes":        dto.MetricType_COUNTER,
-		"insert":             dto.MetricType_COUNTER,
-		"space_from_end":     dto.MetricType_COUNTER,
+		"ffi_batch_total":         dto.MetricType_COUNTER,
+		"proposal_commit_total":   dto.MetricType_COUNTER,
+		"proposal_commit_seconds_total": dto.MetricType_COUNTER,
+		"ffi_propose_seconds_total":   dto.MetricType_COUNTER,
+		"ffi_commit_seconds_total":    dto.MetricType_COUNTER,
+		"ffi_batch_seconds_total":     dto.MetricType_COUNTER,
+		"flush_nodes_seconds_total":   dto.MetricType_COUNTER,
+		"insert_total":              dto.MetricType_COUNTER,
+		"space_from_end_bytes_total": dto.MetricType_COUNTER,
 	}
 	expectedExpensiveMetrics = map[string]dto.MetricType{
-		"ffi_commit_ms_bucket":  dto.MetricType_HISTOGRAM,
-		"ffi_propose_ms_bucket": dto.MetricType_HISTOGRAM,
-		"ffi_batch_ms_bucket":   dto.MetricType_HISTOGRAM,
+		"ffi_commit_duration_seconds":  dto.MetricType_HISTOGRAM,
+		"ffi_propose_duration_seconds": dto.MetricType_HISTOGRAM,
+		"ffi_batch_duration_seconds":   dto.MetricType_HISTOGRAM,
 	}
 	initMetrics   sync.Once
 	initLogs      sync.Once

ffi/src/handle.rs

@@ -224,20 +224,20 @@ impl DatabaseHandle {
             self.create_proposal_handle(values.as_ref())?;
 
         let root_hash = handle.commit_proposal(|commit_time| {
-            firewood_increment!(crate::registry::COMMIT_MS, commit_time.as_millis());
+            firewood_increment!(crate::registry::COMMIT_SECONDS_TOTAL, commit_time.as_nanos() as u64);
             firewood_record!(
-                crate::registry::COMMIT_MS_BUCKET,
-                commit_time.as_f64() * 1000.0,
+                crate::registry::COMMIT_DURATION_SECONDS,
+                commit_time.as_f64(),
                 expensive
             );
         })?;
 
         let elapsed = start_time.elapsed();
-        firewood_increment!(crate::registry::BATCH_MS, elapsed.as_millis());
-        firewood_increment!(crate::registry::BATCH_COUNT, 1);
+        firewood_increment!(crate::registry::BATCH_SECONDS_TOTAL, elapsed.as_nanos() as u64);
+        firewood_increment!(crate::registry::BATCH_TOTAL, 1);
         firewood_record!(
-            crate::registry::BATCH_MS_BUCKET,
-            elapsed.as_f64() * 1000.0,
+            crate::registry::BATCH_DURATION_SECONDS,
+            elapsed.as_f64(),
             expensive
         );
 
@@ -267,9 +267,9 @@ impl DatabaseHandle {
         })?;
 
         if cache_miss {
-            firewood_increment!(crate::registry::CACHED_VIEW_MISS, 1);
+            firewood_increment!(crate::registry::CACHED_VIEW_MISS_TOTAL, 1);
         } else {
-            firewood_increment!(crate::registry::CACHED_VIEW_HIT, 1);
+            firewood_increment!(crate::registry::CACHED_VIEW_HIT_TOTAL, 1);
         }
 
         Ok(view)

ffi/src/lib.rs

@@ -518,11 +518,11 @@ pub extern "C" fn fwd_commit_proposal(proposal: Option<Box<ProposalHandle<'_>>>)
 
     let result = invoke_with_handle(proposal, move |proposal| {
         proposal.commit_proposal(|commit_time| {
-            firewood_increment!(crate::registry::COMMIT_MS, commit_time.as_millis());
-            firewood_increment!(crate::registry::COMMIT_COUNT, 1);
+            firewood_increment!(crate::registry::COMMIT_SECONDS_TOTAL, commit_time.as_nanos() as u64);
+            firewood_increment!(crate::registry::COMMIT_TOTAL, 1);
             firewood_record!(
-                crate::registry::COMMIT_MS_BUCKET,
-                commit_time.as_f64() * 1000.0,
+                crate::registry::COMMIT_DURATION_SECONDS,
+                commit_time.as_f64(),
                 expensive
             );
         })

ffi/src/proofs/change.rs

@@ -248,8 +248,8 @@ impl<'db> ProposedChangeProofContext<'db> {
         };
 
         let metrics_cb = |commit_time: coarsetime::Duration| {
-            firewood_increment!(crate::registry::COMMIT_MS, commit_time.as_millis(), "change" => "commit");
-            firewood_increment!(crate::registry::MERGE_COUNT, 1, "change" => "commit");
+            firewood_increment!(crate::registry::COMMIT_SECONDS_TOTAL, commit_time.as_nanos() as u64, "change" => "commit");
+            firewood_increment!(crate::registry::MERGE_TOTAL, 1, "change" => "commit");
         };
 
         let result = proposal_handle.commit_proposal(metrics_cb);

ffi/src/proofs/range.rs

@@ -225,8 +225,8 @@ impl<'db> RangeProofContext<'db> {
         };
 
         let metrics_cb = |commit_time: coarsetime::Duration| {
-            firewood_increment!(crate::registry::COMMIT_MS, commit_time.as_millis());
-            firewood_increment!(crate::registry::MERGE_COUNT, 1);
+            firewood_increment!(crate::registry::COMMIT_SECONDS_TOTAL, commit_time.as_nanos() as u64);
+            firewood_increment!(crate::registry::MERGE_TOTAL, 1);
         };
 
         let result = proposal_handle.commit_proposal(metrics_cb);

ffi/src/proposal.rs

@@ -130,11 +130,11 @@ impl<'db> CreateProposalResult<'db> {
         let start_time = coarsetime::Instant::now();
         let proposal = f()?;
         let propose_time = start_time.elapsed();
-        firewood_increment!(crate::registry::PROPOSE_MS, propose_time.as_millis());
-        firewood_increment!(crate::registry::PROPOSE_COUNT, 1);
+        firewood_increment!(crate::registry::PROPOSE_SECONDS_TOTAL, propose_time.as_nanos() as u64);
+        firewood_increment!(crate::registry::PROPOSE_TOTAL, 1);
         firewood_record!(
-            crate::registry::PROPOSE_MS_BUCKET,
-            propose_time.as_f64() * 1000.0,
+            crate::registry::PROPOSE_DURATION_SECONDS,
+            propose_time.as_f64(),
             expensive
         );