/ 
DBIx-Fast-0.17
/ DBIx::Fast::Output

NAME

DBIx::Fast::Output - Unified output layer for the profiler subsystem

SYNOPSIS

# Text (default): print_* methods render to STDOUT exactly as always.
my $db = DBIx::Fast->new(dsn => $dsn);

# JSON lines: every print_* emits one machine-readable line instead.
my $db = DBIx::Fast->new(dsn => $dsn, profile_output => 'json');

# Callback: integrate with your logger, no parsing needed.
my $db = DBIx::Fast->new(dsn => $dsn, profile_output => sub ($event, $data, $meta) {
    $log->info("profiler $meta->{source}/$event", $data);
});

# Switch at runtime, per object:
$db->tracker->output('json');
open my $fh, '>>', 'profiler.jsonl' or die $!;
chmod 0600, 'profiler.jsonl';
$db->profiler->output_fh($fh);

DESCRIPTION

Object::Pad role composed into DBIx::Fast::Profiler and DBIx::Fast::Profile::Base (and through it every driver profile). All print_* report methods route through it: in text mode they render the same formatted output as previous releases; in json or callback mode they emit the underlying structured data (the same hashrefs the get_* methods return) and skip text rendering entirely.

EVENTS

JSON mode writes one object per line with canonical (sorted) keys:

{"data":{...},"driver":"MariaDB","event":"stats","source":"profile","ts":"2026-08-18T12:34:56.789Z"}

source is tracker (the query tracker, DBIx::Fast::Profiler) or profile (a driver profile; driver names it). event is query, stats or summary for the tracker, and stats, index_analysis or connection_monitor for profiles. data is the structured report. A callback receives the same information unencoded: $cb->($event, $data, {ts, source, driver?}).

METHODS

output

$obj->output;            # current mode
$obj->output('json');    # set: 'text' | 'json' | coderef (validated)

output_fh

$obj->output_fh($fh);    # where text/json lines are written

Defaults to the currently selected handle (normally STDOUT), so output redirection done by the caller keeps working.

emit ($event, $data)

Routes one event. Returns false in text mode - the caller is expected to render text itself through out/outf - and true when the json/callback sink consumed the event. Sink failures (dying callback, closed filehandle, unencodable data) warn and are swallowed: profiling never kills the application's queries.

SECURITY

The json and callback sinks receive the same cleartext SQL and bind parameters that text mode prints - including any PII the application binds. Point them only at destinations with the same protection you would give the database itself (note the chmod 0600 in the SYNOPSIS). JSON encoding escapes control characters natively, so terminal-escape sanitization is only applied in text mode.

AUTHOR

SeHarrys

LICENSE

This is free software under the Artistic License 2.0.