/ 
DBIx-Fast-0.17
/ DBIx::Fast::Profiler

NAME

DBIx::Fast::Profiler - Query profiling and statistics for DBIx::Fast

DESCRIPTION

Records and analyzes SQL query execution times, providing detailed statistics, slow query detection, and colored terminal output. Queries are stored in a circular buffer controlled by max_queries.

METHODS

add_query

$profiler->add_query($sql, \@params, $start_time, $end_time);

Records a query execution with its SQL, bind parameters, and timing. Automatically prints the query if auto_print is enabled.

$profiler->print_query(\%query_info);

Reports a single query. In the default text output mode, prints its details with color-coded duration (green, yellow, or red) and a stack trace for slow queries. In json or callback mode (see DBIx::Fast::Output), emits a query event carrying the raw record plus a computed severity (ok/warn/slow) instead.

Reports a summary of query statistics grouped by query type (SELECT, INSERT, etc.) with count, total time, average, min, and max for each type. Text mode prints it formatted; json/callback mode emits a summary event with the "get_detailed_stats" data.

Reports comprehensive query statistics including totals, averages, slow query percentage, queries per second, and a per-type breakdown. Text mode prints it formatted; json/callback mode emits a stats event with the "get_stats" data.

get_stats

my $stats = $profiler->get_stats();

Returns a hashref with aggregate statistics: total_queries, total_time, avg_time, min_time, max_time, slow_queries, slow_query_percentage, queries_per_second, and query_types breakdown.

get_detailed_stats

my $stats = $profiler->get_detailed_stats();

Returns a hashref keyed by query type with count, total_time, avg_time, min_time, and max_time for each type.

get_slow_queries

my $slow = $profiler->get_slow_queries($limit);

Returns an arrayref of the top $limit (default 10) slowest queries, sorted by duration descending.

clear

Clears all recorded queries from the profiler buffer.

SECURITY

The profiler stores full bind parameter values alongside each recorded query (see "add_query") and, with auto_print enabled, writes them to STDOUT in clear text. The json and callback output modes (DBIx::Fast::Output) receive exactly the same cleartext values - routing to a file or logger does not redact anything. Bind values can include passwords, payment tokens, session identifiers, email addresses and any other PII or PCI data flowing through the application.

Do not enable this profiler in production with real customer traffic. The intended use is development, integration tests, and ad-hoc performance debugging against synthetic or anonymized data.

If you must run it against a live system:

  • Construct it with auto_print => 0 (the $db->tracker accessor already does this) so values do not hit STDOUT.

  • Treat the in-memory queries buffer as a sensitive store. Do not log, serialize, or expose it via debug endpoints.

  • Call "clear" as soon as the analysis is complete to drop bind values from memory.

  • Pair with DBIx::Fast errors_redact => 1 so driver error messages do not echo the same values into the error buffer.

AUTHOR

SeHarrys

LICENSE

This is free software under the Artistic License 2.0.