refactor(sqlite): simplify profiling fingerprints

Author: NathanFlurry

docs/content/docs/sqlite-profiling.mdx

@@ -6,6 +6,8 @@ skill: true
 
 Profiling helps you find slow queries, transaction contention, and unnecessary storage activity.
 
+Collect [Prometheus metrics from each worker](/actors/self-host/workers/prometheus-metrics/) to use the queries below.
+
 ## Identify operations
 
 ### Transaction names
@@ -18,17 +20,29 @@ Without a name, RivetKit falls back to a fingerprint of the transaction's statem
 
 ### Statement fingerprints
 
-RivetKit normalizes each SQL statement into a sanitized shape, then hashes that shape into a stable fingerprint. The fingerprint groups metrics without putting SQL text in a Prometheus label.
-
-- Bound and inline literal values do not change the fingerprint.
-- Whitespace, capitalization, and comments do not change the fingerprint.
-- Keep query structure static and use `?` or named bindings for dynamic values.
+RivetKit hashes each SQL statement exactly as provided. The fingerprint groups metrics without putting SQL text in a Prometheus label.
 
 For example, repeated `SELECT * FROM orders WHERE id = ?` calls share one fingerprint regardless of the bound ID.
 
+### Find the SQL for a fingerprint
+
+RivetKit logs the SQL statement or transaction name for each tracked fingerprint.
+
+For example, suppose a Prometheus result contains `fingerprint="select-a1b2c3d4e5f60718"`:
+
+1. Copy the fingerprint: `select-a1b2c3d4e5f60718`.
+2. Search the actor logs for `sqlite fingerprint catalog` and `select-a1b2c3d4e5f60718`.
+3. Read `identity` from the matching log line:
+
+   ```text
+   sqlite fingerprint catalog fingerprint="select-a1b2c3d4e5f60718" identity="SELECT value FROM items WHERE id = ?"
+   ```
+
+For a transaction fingerprint, `identity` contains its static transaction name.
+
 ## Find slow operations
 
-**Slowest statements and transactions**
+### Slowest statements and transactions
 
 ```promql
 histogram_quantile(
@@ -39,25 +53,72 @@ histogram_quantile(
 )
 ```
 
-**Failed operations**
+### Slowest latency phases
+
+```promql
+histogram_quantile(
+  0.95,
+  sum by (le, actor_name, type, fingerprint, phase) (
+    rate(rivet_rivetkit_sqlite_phase_duration_seconds_bucket[5m])
+  )
+)
+```
+
+- `transaction_wait`: waiting for another transaction on the actor to finish.
+- `worker_wait`: waiting for earlier SQLite work on the actor to finish.
+- `storage`: loading or saving SQLite data.
+- `local_work`: executing SQL and preparing results, excluding storage time.
+- `application_time`: time the transaction stays open between SQL calls.
+- `commit`: saving changes at the end of a transaction.
+
+### Non-success outcomes
 
 ```promql
 sum by (actor_name, type, fingerprint, outcome) (
   rate(rivet_rivetkit_sqlite_outcome_total{outcome!="success"}[5m])
 )
 ```
 
-**Transaction contention**
+### Transaction contention
 
 ```promql
 max by (actor_name) (
   max_over_time(rivet_rivetkit_sqlite_coordinator_queue_depth[5m])
 )
 ```
 
+### Native worker saturation
+
+```promql
+max by (actor_name) (
+  max_over_time(rivet_rivetkit_sqlite_worker_queue_depth[5m])
+)
+```
+
+```promql
+avg by (actor_name) (
+  avg_over_time(rivet_rivetkit_sqlite_worker_inflight[5m])
+)
+```
+
+A sustained worker queue indicates SQLite work is arriving faster than the actor's native worker completes it. The average `worker_inflight` value is the fraction of sampled time that the worker was executing a command.
+
+### Transactions with the most statements
+
+```promql
+histogram_quantile(
+  0.95,
+  sum by (le, actor_name, fingerprint) (
+    rate(rivet_rivetkit_sqlite_transaction_statement_count_bucket[5m])
+  )
+)
+```
+
+Large statement counts can identify loops or oversized units of work. Use a static transaction name so the fingerprint remains stable across branches.
+
 ## Find storage-heavy operations
 
-**Operations with the most storage requests**
+### Average storage round trips per operation
 
 ```promql
 sum by (actor_name, type, fingerprint) (
@@ -69,15 +130,48 @@ sum by (actor_name, type, fingerprint) (
 )
 ```
 
-**SQLite page usage by kind**
+### Pages per physical storage request
+
+```promql
+sum by (actor_name, request_ordinal, page_kind) (
+  rate(rivet_rivetkit_sqlite_get_pages_pages_sum[5m])
+)
+/
+sum by (actor_name, request_ordinal, page_kind) (
+  rate(rivet_rivetkit_sqlite_get_pages_pages_count[5m])
+)
+```
+
+Compare `response_present` with `demand_requested` to see response amplification. `overflow_expansion_extra` shows pages added while resolving SQLite overflow chains, and `prefetch_requested` shows speculative reads.
+
+### Large storage responses
+
+```promql
+histogram_quantile(
+  0.95,
+  sum by (le, actor_name, request_ordinal) (
+    rate(rivet_rivetkit_sqlite_get_pages_response_bytes_bucket[5m])
+  )
+)
+```
+
+### Missing response pages
+
+```promql
+sum by (actor_name, request_ordinal) (
+  rate(rivet_rivetkit_sqlite_get_pages_missing_pages_total[5m])
+)
+```
+
+### SQLite page usage by kind
 
 ```promql
 sum by (actor_name, type, page_kind) (
   rate(rivet_rivetkit_sqlite_local_pages_total[5m])
 )
 ```
 
-**SQLite data volume by kind**
+### SQLite data volume by kind
 
 ```promql
 sum by (actor_name, type, byte_kind) (
@@ -91,18 +185,15 @@ High round-trip or page counts can indicate a missing index, a large scan, or in
 
 RivetKit emits bounded structured diagnostics for operations that are slow, fail, show unusual storage amplification, or are selected by baseline sampling.
 
-- Fingerprint catalog events map a fingerprint to its sanitized SQL shape or static transaction name.
-- Operation events include latency phases, rows, bytes, page activity, and storage requests.
+- Operation events include timing components, rows, bytes, page activity, and storage requests.
 - Transaction events include statement count, application-held time, commit time, and terminal outcome.
 - Event sampling, rate limits, and a bounded queue prevent diagnostics from blocking SQLite work.
 
-Search actor logs for `sqlite fingerprint catalog` or `sampled SQLite operation profile` and match events using the `fingerprint` field.
-
-Catalog events contain the sanitized SQL shape, never bound values or raw SQL. Continue binding dynamic values instead of constructing SQL strings.
+Search actor logs for `sampled SQLite operation profile` to inspect one profiled statement execution. Transaction details use `sampled SQLite transaction profile`.
 
 ## Configure profiling
 
-Profiling is enabled by default and most applications do not need to configure it. Set `profiling.slowOperationThresholdMs` or `profiling.baselineSampleRate` on the database provider when needed.
+Profiling is enabled by default and most applications do not need to configure it. The entire profiling configuration surface is experimental and subject to change without notice. Set `profiling.slowOperationThresholdMs` or `profiling.baselineSampleRate` on the database provider when needed.
 
 Increase fingerprint limits only when `other` is hiding frequently repeated operations. Prometheus series remain allocated for the life of the process after admission.
 
@@ -114,7 +205,7 @@ Fast statements initially appear under `other`, while overflow metrics show when
 
 ### Too many fingerprints
 
-Fingerprints use normalized SQL shapes, so formatting, comments, and literal values do not create separate entries. Keep query structure static and pass dynamic values as bindings.
+Statement fingerprints use the exact query text. Keep formatting and query structure static, and pass dynamic values as bindings instead of constructing SQL strings.
 
 ### Transactions are hard to identify
 

rivetkit-rust/packages/rivetkit-core/src/actor/config.rs

@@ -67,10 +67,7 @@ pub struct SqliteProfilingConfig {
 	pub max_prometheus_series: usize,
 	pub max_statements_per_transaction_trace: usize,
 	pub max_get_pages_requests_per_trace: usize,
-	pub max_sql_bytes_to_normalize: usize,
-	pub max_catalog_sql_shape_bytes: usize,
 	pub max_transaction_name_bytes: usize,
-	pub fingerprint_computation_cache_entries: usize,
 	pub slow_operation_threshold_ms: u64,
 	pub baseline_sample_rate: f64,
 	pub max_diagnostic_events_per_minute: usize,
@@ -86,10 +83,7 @@ impl Default for SqliteProfilingConfig {
 			max_prometheus_series: 25_000,
 			max_statements_per_transaction_trace: 32,
 			max_get_pages_requests_per_trace: 16,
-			max_sql_bytes_to_normalize: 65_536,
-			max_catalog_sql_shape_bytes: 4_096,
 			max_transaction_name_bytes: 128,
-			fingerprint_computation_cache_entries: 1_024,
 			slow_operation_threshold_ms: 10,
 			baseline_sample_rate: 0.001,
 			max_diagnostic_events_per_minute: 120,
@@ -111,10 +105,7 @@ pub struct SqliteProfilingConfigInput {
 	pub max_prometheus_series: Option<u32>,
 	pub max_statements_per_transaction_trace: Option<u32>,
 	pub max_get_pages_requests_per_trace: Option<u32>,
-	pub max_sql_bytes_to_normalize: Option<u32>,
-	pub max_catalog_sql_shape_bytes: Option<u32>,
 	pub max_transaction_name_bytes: Option<u32>,
-	pub fingerprint_computation_cache_entries: Option<u32>,
 	pub slow_operation_threshold_ms: Option<u32>,
 	pub baseline_sample_rate: Option<f64>,
 	pub max_diagnostic_events_per_minute: Option<u32>,
@@ -139,10 +130,7 @@ impl SqliteProfilingConfig {
 		set_usize!(max_prometheus_series);
 		set_usize!(max_statements_per_transaction_trace);
 		set_usize!(max_get_pages_requests_per_trace);
-		set_usize!(max_sql_bytes_to_normalize);
-		set_usize!(max_catalog_sql_shape_bytes);
 		set_usize!(max_transaction_name_bytes);
-		set_usize!(fingerprint_computation_cache_entries);
 		if let Some(value) = input.slow_operation_threshold_ms {
 			config.slow_operation_threshold_ms = u64::from(value);
 		}

rivetkit-rust/packages/rivetkit-core/src/actor/sqlite/mod.rs

@@ -474,15 +474,15 @@ impl SqliteDb {
 		}
 		let fingerprint = self.profiling.statement_fingerprint(sql)?;
 		let observation = profiling::StatementObservation {
-			fingerprint: Arc::clone(&fingerprint),
+			fingerprint,
 			total_ns: duration_ns(started_at.elapsed()),
 			transaction_wait_ns: duration_ns(transaction_wait),
 			profile: profile.unwrap_or_default(),
 		};
 		if let Some(metrics) = &self.vfs_metrics {
 			let metric = depot_client::vfs::SqliteOperationMetric {
 				operation_type: "statement",
-				fingerprint: fingerprint.display.clone(),
+				fingerprint: observation.fingerprint.display.clone(),
 				fingerprint_source: "query",
 				transaction_mode,
 				storage_transport: "proxy",
@@ -493,13 +493,13 @@ impl SqliteDb {
 				profile: observation.profile.clone(),
 			};
 			if metrics.observe_operation_profile(&metric)
-				&& self.profiling.mark_cataloged(&fingerprint.display)
+				&& self.profiling.mark_cataloged(&metric.fingerprint)
 			{
 				metrics.record_fingerprint_catalog(
 					"statement",
-					&fingerprint.display,
-					&fingerprint.normalized_sql,
-					1,
+					&metric.fingerprint,
+					sql,
+					profiling::FINGERPRINT_FORMAT_VERSION,
 				);
 			}
 			metrics.emit_operation_diagnostic_event(