Feature/issue 176 profiling

.kiro/specs/database-query-instrumentation/.config.kiro

@@ -0,0 +1 @@
+{"specId": "7947673b-befa-4de6-9c5f-cedb46fab061", "workflowType": "requirements-first", "specType": "feature"}

.kiro/specs/database-query-instrumentation/requirements.md

@@ -0,0 +1,114 @@
+# Requirements Document
+
+## Introduction
+
+This document specifies requirements for database query instrumentation and performance monitoring in a Rust-based payment processing system. The system uses sqlx with PostgreSQL, and slow queries are the primary cause of API latency degradation. The instrumentation must identify and monitor query performance with minimal overhead to enable proactive optimization.
+
+## Glossary
+
+- **Query_Instrumentor**: The component responsible for measuring and recording database query execution metrics
+- **Query_Logger**: The component responsible for logging query execution details
+- **Metrics_Exporter**: The component responsible for exposing query performance metrics
+- **Instrumented_Pool**: A wrapper around sqlx::PgPool that provides timing and logging capabilities
+- **Query_Identifier**: A human-readable name identifying the function or operation executing a query
+- **Slow_Query**: A database query whose execution time exceeds the configured threshold
+- **Configuration_Manager**: The component responsible for loading and providing configuration values
+
+## Requirements
+
+### Requirement 1: Measure Query Execution Time
+
+**User Story:** As a developer, I want to measure the execution time of every database query, so that I can identify performance bottlenecks.
+
+#### Acceptance Criteria
+
+1. WHEN a database query is executed, THE Query_Instrumentor SHALL record the start time before execution
+2. WHEN a database query completes, THE Query_Instrumentor SHALL record the end time after execution
+3. THE Query_Instrumentor SHALL calculate execution duration as the difference between end time and start time
+4. THE Query_Instrumentor SHALL measure time using std::time::Instant for monotonic timing
+5. THE Query_Instrumentor SHALL add less than 1 millisecond of overhead per query execution
+
+### Requirement 2: Log Slow Queries
+
+**User Story:** As a developer, I want slow queries to be automatically logged, so that I can investigate performance issues without manual monitoring.
+
+#### Acceptance Criteria
+
+1. THE Configuration_Manager SHALL provide a SLOW_QUERY_THRESHOLD_MS setting with a default value of 100 milliseconds
+2. WHEN a query execution time exceeds SLOW_QUERY_THRESHOLD_MS, THE Query_Logger SHALL log the query details
+3. THE Query_Logger SHALL include the Query_Identifier in slow query logs
+4. THE Query_Logger SHALL include the execution duration in milliseconds in slow query logs
+5. THE Query_Logger SHALL include the affected row count in slow query logs
+6. THE Query_Logger SHALL avoid cloning query strings to minimize overhead
+
+### Requirement 3: Support Development Debug Mode
+
+**User Story:** As a developer, I want to log all queries during development, so that I can debug database interactions without modifying code.
+
+#### Acceptance Criteria
+
+1. THE Configuration_Manager SHALL provide a DB_LOG_ALL_QUERIES setting with a default value of false
+2. WHERE DB_LOG_ALL_QUERIES is true, THE Query_Logger SHALL log every query regardless of execution time
+3. WHERE DB_LOG_ALL_QUERIES is true, THE Query_Logger SHALL include the Query_Identifier in logs
+4. WHERE DB_LOG_ALL_QUERIES is true, THE Query_Logger SHALL include the execution duration in milliseconds in logs
+5. WHERE DB_LOG_ALL_QUERIES is false, THE Query_Logger SHALL only log queries exceeding SLOW_QUERY_THRESHOLD_MS
+
+### Requirement 4: Expose Query Performance Metrics
+
+**User Story:** As an operations engineer, I want query performance metrics exposed in a standard format, so that I can monitor database performance using existing observability tools.
+
+#### Acceptance Criteria
+
+1. WHERE metrics collection is enabled, THE Metrics_Exporter SHALL expose a db_query_duration_seconds histogram metric
+2. THE Metrics_Exporter SHALL label the db_query_duration_seconds metric with a query_name dimension containing the Query_Identifier
+3. THE Metrics_Exporter SHALL record execution duration in seconds with millisecond precision
+4. WHERE metrics collection is disabled, THE Query_Instrumentor SHALL skip metrics recording to avoid overhead
+5. THE Metrics_Exporter SHALL use histogram buckets appropriate for database query latencies
+
+### Requirement 5: Provide Instrumented Database Pool
+
+**User Story:** As a developer, I want a drop-in replacement for sqlx::PgPool that includes instrumentation, so that I can add monitoring without rewriting query code.
+
+#### Acceptance Criteria
+
+1. THE Instrumented_Pool SHALL wrap sqlx::PgPool to provide instrumentation capabilities
+2. THE Instrumented_Pool SHALL accept a Query_Identifier parameter for each query execution
+3. THE Instrumented_Pool SHALL execute queries using the underlying sqlx::PgPool
+4. THE Instrumented_Pool SHALL apply timing measurement to all query executions
+5. THE Instrumented_Pool SHALL return query results identical to sqlx::PgPool
+
+### Requirement 6: Provide Query Instrumentation Helper
+
+**User Story:** As a developer, I want a convenient macro or helper function for instrumented queries, so that I can easily add monitoring to existing query code.
+
+#### Acceptance Criteria
+
+1. THE Query_Instrumentor SHALL provide a timed_query helper that wraps sqlx::query with instrumentation
+2. THE timed_query helper SHALL accept a Query_Identifier as a parameter
+3. THE timed_query helper SHALL accept a sqlx query as a parameter
+4. THE timed_query helper SHALL return query results compatible with sqlx::query
+5. THE timed_query helper SHALL automatically apply timing, logging, and metrics recording
+
+### Requirement 7: Integrate with Existing Query Functions
+
+**User Story:** As a developer, I want existing query functions to use instrumentation, so that I can monitor production queries without breaking existing functionality.
+
+#### Acceptance Criteria
+
+1. THE Query_Instrumentor SHALL be integrated into query functions in src/db/queries.rs
+2. WHEN a query function is called, THE Query_Instrumentor SHALL use the function name as the Query_Identifier
+3. THE Query_Instrumentor SHALL preserve the original return types of query functions
+4. THE Query_Instrumentor SHALL preserve the original error handling behavior of query functions
+5. THE Query_Instrumentor SHALL maintain backward compatibility with existing query function signatures
+
+### Requirement 8: Configure Instrumentation Settings
+
+**User Story:** As an operations engineer, I want to configure instrumentation behavior through environment variables, so that I can adjust monitoring without code changes.
+
+#### Acceptance Criteria
+
+1. THE Configuration_Manager SHALL load SLOW_QUERY_THRESHOLD_MS from environment variables or configuration files
+2. THE Configuration_Manager SHALL load DB_LOG_ALL_QUERIES from environment variables or configuration files
+3. THE Configuration_Manager SHALL validate that SLOW_QUERY_THRESHOLD_MS is a positive integer
+4. THE Configuration_Manager SHALL validate that DB_LOG_ALL_QUERIES is a boolean value
+5. IF configuration values are invalid, THEN THE Configuration_Manager SHALL use default values and log a warning

.kiro/specs/database-query-instrumentation/tasks.md

@@ -0,0 +1,162 @@
+# Implementation Plan: Database Query Instrumentation
+
+## Overview
+
+This plan implements database query instrumentation for a Rust-based payment processing system using sqlx with PostgreSQL. The implementation adds timing measurement, slow query logging, optional Prometheus metrics, and debug mode support with minimal overhead (< 1ms per query).
+
+## Tasks
+
+- [ ] 1. Extend configuration module with instrumentation settings
+  - [ ] 1.1 Add instrumentation configuration fields to src/config.rs
+    - Add `slow_query_threshold_ms: u64` field (default: 100)
+    - Add `db_log_all_queries: bool` field (default: false)
+    - Add `enable_db_metrics: bool` field (default: false)
+    - Implement environment variable loading for new fields
+    - Add validation for positive threshold values
+    - _Requirements: 2.1, 3.1, 3.2, 8.1, 8.2, 8.3, 8.4, 8.5_
+
+  - [ ]* 1.2 Write unit tests for configuration loading
+    - Test default values are applied correctly
+    - Test environment variable overrides work
+    - Test invalid values trigger warnings and use defaults
+    - _Requirements: 8.3, 8.4, 8.5_
+
+- [ ] 2. Create instrumented database pool module
+  - [ ] 2.1 Create src/db/instrumented.rs with InstrumentedPool struct
+    - Define `InstrumentedPool` wrapping `sqlx::PgPool`
+    - Add fields for configuration (threshold, log_all, metrics_enabled)
+    - Add optional `MetricsExporter` field for Prometheus integration
+    - Implement `new()` constructor accepting pool and config
+    - Implement `Clone` trait for InstrumentedPool
+    - _Requirements: 5.1, 5.3, 5.5_
+
+  - [ ] 2.2 Implement timing measurement infrastructure
+    - Create helper function to capture start time using `std::time::Instant`
+    - Create helper function to calculate duration in milliseconds
+    - Ensure overhead is minimal (< 1ms)
+    - _Requirements: 1.1, 1.2, 1.3, 1.4, 1.5_
+
+  - [ ] 2.3 Implement query logging functionality
+    - Create `log_query()` helper function accepting query_name, duration, rows_affected
+    - Implement slow query logging when duration exceeds threshold
+    - Implement debug mode logging for all queries
+    - Use efficient logging without cloning query strings
+    - Include query_name, duration_ms, and rows_affected in logs
+    - _Requirements: 2.2, 2.3, 2.4, 2.5, 2.6, 3.2, 3.3, 3.4, 3.5_
+
+  - [ ]* 2.4 Write unit tests for logging functionality
+    - Test slow query logging triggers correctly
+    - Test debug mode logs all queries
+    - Test normal mode skips fast queries
+    - Test log format includes required fields
+    - _Requirements: 2.2, 2.3, 2.4, 2.5, 3.2, 3.3, 3.4, 3.5_
+
+- [ ] 3. Implement optional Prometheus metrics
+  - [ ] 3.1 Create MetricsExporter struct in src/db/instrumented.rs
+    - Define `MetricsExporter` with histogram for query durations
+    - Create `db_query_duration_seconds` histogram metric
+    - Configure histogram buckets for database latencies (0.001, 0.005, 0.01, 0.05, 0.1, 0.5, 1.0, 5.0)
+    - Implement `record_query()` method accepting query_name and duration
+    - Add `query_name` label to histogram
+    - _Requirements: 4.1, 4.2, 4.3, 4.5_
+
+  - [ ] 3.2 Integrate metrics recording into InstrumentedPool
+    - Add conditional metrics recording based on `enable_db_metrics` flag
+    - Convert duration from milliseconds to seconds for metrics
+    - Skip metrics recording when disabled to avoid overhead
+    - _Requirements: 4.3, 4.4_
+
+  - [ ]* 3.3 Write unit tests for metrics recording
+    - Test metrics are recorded when enabled
+    - Test metrics are skipped when disabled
+    - Test histogram labels include query_name
+    - Test duration conversion to seconds
+    - _Requirements: 4.1, 4.2, 4.3, 4.4_
+
+- [ ] 4. Checkpoint - Ensure all tests pass
+  - Ensure all tests pass, ask the user if questions arise.
+
+- [ ] 5. Implement timed_query helper function
+  - [ ] 5.1 Create timed_query helper in src/db/instrumented.rs
+    - Accept `query_name: &str` parameter
+    - Accept `pool: &InstrumentedPool` parameter
+    - Accept `query: sqlx::Query` parameter
+    - Return `Result` compatible with sqlx::query
+    - Measure execution time using Instant::now()
+    - Apply logging based on configuration
+    - Apply metrics recording if enabled
+    - Preserve sqlx error types in return value
+    - _Requirements: 6.1, 6.2, 6.3, 6.4, 6.5, 1.1, 1.2, 1.3_
+
+  - [ ]* 5.2 Write unit tests for timed_query helper
+    - Test successful query execution and timing
+    - Test error propagation from sqlx
+    - Test return type compatibility
+    - Test logging is triggered appropriately
+    - _Requirements: 6.4, 6.5_
+
+- [ ] 6. Update database module initialization
+  - [ ] 6.1 Modify src/db/mod.rs to create InstrumentedPool
+    - Import InstrumentedPool from instrumented module
+    - Wrap existing PgPool creation with InstrumentedPool::new()
+    - Pass configuration values to InstrumentedPool
+    - Initialize MetricsExporter if metrics are enabled
+    - Export InstrumentedPool for use in query functions
+    - _Requirements: 5.1, 5.2, 5.3_
+
+  - [ ]* 6.2 Write integration tests for pool initialization
+    - Test pool creation with various configurations
+    - Test metrics exporter initialization
+    - Test pool can execute queries successfully
+    - _Requirements: 5.1, 5.2, 5.3, 5.5_
+
+- [ ] 7. Retrofit existing query functions
+  - [ ] 7.1 Update query functions in src/db/queries.rs to use instrumentation
+    - Replace direct sqlx::query calls with timed_query helper
+    - Use function name as query_identifier for each function
+    - Preserve original return types
+    - Preserve original error handling
+    - Maintain backward compatibility with function signatures
+    - Update all query functions: get_payment, create_payment, update_payment_status, etc.
+    - _Requirements: 7.1, 7.2, 7.3, 7.4, 7.5_
+
+  - [ ]* 7.2 Write integration tests for retrofitted query functions
+    - Test each query function executes successfully
+    - Test timing is recorded for each function
+    - Test slow queries are logged
+    - Test return values match original behavior
+    - Test error handling matches original behavior
+    - _Requirements: 7.3, 7.4, 7.5_
+
+- [ ] 8. Add property-based tests using proptest
+  - [ ]* 8.1 Write property test for timing overhead
+    - Generate random query execution scenarios
+    - Verify instrumentation overhead is always < 1ms
+    - Test with various query durations
+    - _Requirements: 1.5_
+
+  - [ ]* 8.2 Write property test for configuration validation
+    - Generate random configuration values
+    - Verify invalid thresholds use defaults
+    - Verify boolean parsing handles various inputs
+    - _Requirements: 8.3, 8.4, 8.5_
+
+  - [ ]* 8.3 Write property test for logging behavior
+    - Generate random query durations
+    - Verify slow queries are always logged when exceeding threshold
+    - Verify fast queries are not logged in normal mode
+    - Verify all queries are logged in debug mode
+    - _Requirements: 2.2, 3.2, 3.3, 3.4, 3.5_
+
+- [ ] 9. Final checkpoint - Ensure all tests pass
+  - Ensure all tests pass, ask the user if questions arise.
+
+## Notes
+
+- Tasks marked with `*` are optional and can be skipped for faster MVP
+- Each task references specific requirements for traceability
+- Checkpoints ensure incremental validation
+- Property tests validate universal correctness properties using proptest
+- Unit tests validate specific examples and edge cases
+- The implementation maintains backward compatibility with existing query code
+- Metrics integration is optional and can be disabled for zero overhead

.kiro/specs/stellar-memo-verification/.config.kiro

@@ -0,0 +1 @@
+{"specId": "7947673b-befa-4de6-9c5f-cedb46fab061", "workflowType": "requirements-first", "specType": "feature"}