DBIx::OpenTracing - automatically create OpenTracing spans around DBI queries
v0.0.9
use DBI; use DBIx::OpenTracing; # use DBI as usual my $dbh = DBI->connect(...); $dbh->do(...); DBIx::OpenTracing->disable(); $dbh->do($secret_query); DBIx::OpenTracing->enable(); sub process_secrets { DBIx::OpenTracing->suspend(); ... }
This module overrides DBI methods to create spans around all queries. It will also try to extract information like the query SQL and the number of rows returned. OpenTracing::GlobalTracer is used to accomplish this, so make sure you set your tracer there.
Spans created by this module will be named after the DBI method they wrap and prefixed with "dbi_", a call to $dbh-execute()> would produce a span called "dbi_execute". Note that the span method name may differ from the one used in your code, since many methods are simply wrappers around others. The following tags will be added to each span (if possible) in accordance with OpenTracing conventions:
$dbh-
db.type - always set to "sql"
db.instance - the database name
db.user - the user associated with the handle (not always available)
db.statement - the query SQL (with comments removed)
db.statement_summary - the statement type and main affected table, for ex. "SELECT: users"
db.rows - the number of rows affected (not always available)
error - will be set to true if the query failed
error.kind - A string containing the SQLSTATE, for ex. "SQLSTATE_0700F"
SQLSTATE
message - A readable message indicating the kind of error (not the SQL-Statement)
It's possible to pick a default tag selection with an import argument. The following are supported:
no tags by default, can be shown with show_tags
no tags which could contain sensitive data (SQL statement, bind values, username and db), can be shown with show_tags
hide the same tags as -safe but it's not possible to show them in any way
You can call DBIx::OpenTracing->disable to turn off all of this modules functionality. It can be re-enabled later with enable.
DBIx::OpenTracing->disable
Enable the module features again after being disabled. It's safe to call this multiple times.
Disable the module until the end of current scope.
Enable the module until the end of current scope.
Similarly to disable_temporarily, will disable the module until the end of current scope. However, until that scope is over, calls to enable and enable_temprarily will be ignored. Use this if you want to make sure absolutely nothing is traced within the scope, regardless of what any called functions are doing.
Will cause all the specified tags to be skipped when creating spans. This can be used to hide sensitive SQL statements. See DBIx::OpenTracing::Constants for tag names.
Will cause previously hidden tags to start appearing again.
Same as hide_tags but only works until the end of current scope.
Same as show_tags but only works until the end of current scope.
Similarly to suspend, will hide all specified tags until the end of current scope and not allow them to be shown by calls to show_tags or show_tags_temporarily until then.
Szymon Nieznański <snieznanski@perceptyx.com>
'DBIx::OpenTracing' is Copyright (C) 2020, Perceptyx Inc
This library is free software; you can redistribute it and/or modify it under the terms of the Artistic License 2.0.
This package is distributed in the hope that it will be useful, but it is provided "as is" and without any express or implied warranties.
For details, see the full text of the license in the file LICENSE.
To install DBIx::OpenTracing, copy and paste the appropriate command in to your terminal.
cpanm
cpanm DBIx::OpenTracing
CPAN shell
perl -MCPAN -e shell install DBIx::OpenTracing
For more information on module installation, please visit the detailed CPAN module installation guide.