README

This bundle adds automatic spanning for Doctrine DBAL connections to the OpentracingBundle.

Installation

Prerequisites

This bundle is only an additional plugin and should not be installed independently. See its documentation for more information on installing the OpentracingBundle first.

Require dependencies

After you have installed the OpentracingBundle:

require the dependencies:

    composer req auxmoney/opentracing-bundle-doctrine-dbal

Enable the bundle

If you are using Symfony Flex, you are all set!

If you are not using it, you need to manually enable the bundle:

add bundle to your application:

    # Symfony 3: AppKernel.php
    $bundles[] = new Auxmoney\OpentracingDoctrineDBALBundle\OpentracingDoctrineDBALBundle();

    # Symfony 4+: bundles.php
    Auxmoney\OpentracingDoctrineDBALBundle\OpentracingDoctrineDBALBundle::class => ['all' => true],

Configuration

You can optionally configure environment variables, however, the default configuration will run fine out of the box for most DBAL based applications. If you cannot change environment variables in your project, you can alternatively overwrite the container parameters directly.

environment variable	container parameter	type	default	description
AUXMONEY_OPENTRACING_DOCTRINE_FULL_STATEMENT	auxmoney_opentracing.doctrine.tag_full_statement	`string`	`true`	whether to add a tag with the full SQL statement to the span
AUXMONEY_OPENTRACING_DOCTRINE_PARAMETERS	auxmoney_opentracing.doctrine.tag_parameters	`string`	`true`	whether to add a tag with the statement parameters to the span
AUXMONEY_OPENTRACING_DOCTRINE_ROW_COUNT	auxmoney_opentracing.doctrine.tag_row_count	`string`	`false`	whether to add a tag with the affected / returned rows to the span; see limitations section
AUXMONEY_OPENTRACING_DOCTRINE_USER	auxmoney_opentracing.doctrine.tag_user	`string`	`false`	whether to add a tag with the connection username to the span

Hint: you can use true, on, yes or 1 to enable an environment variable.

Usage

When querying databases using Doctrine DBAL (or higher level packages like Doctrine ORM), spans reflecting these queries are automatically generated and added to the trace. The generated tags can contain:

tag name	contains
db.statement	the executed statement
db.parameters	the parameters of the executed statement, if present
db.row_count	affected / returned rows of the executed statement; see limitations section
db.user	the username of the decorated DBAL connection

Limitations

db.row_count: the correctness of this value depends heavily on the implementation of the Doctrine\DBAL\Driver\Statement of the driver for the database. For example, if you are using a PDO driver, keep in mind: "For most databases, PDOStatement::rowCount() does not return the number of rows affected by a SELECT statement.". See the official PHP documentation for more information on this particular topic. If you are getting different results than expected, consult the documentation for the used driver.

Development

Be sure to run

    composer run-script quality

every time before you push code changes. The tools run by this script are also run in the CI pipeline.

auxmoney / opentracing-bundle-doctrine-dbal

Maintainers

Details