Skip to content

auxmoney/OpentracingBundle-Doctrine-DBAL

Repository files navigation

auxmoney OpentracingBundle - Doctrine DBAL

test GitHub release (latest SemVer) Codacy Badge Code Climate maintainability Scrutinizer code quality (GitHub/Bitbucket) GitHub

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.