auxmoney OpentracingBundle

This collection of symfony bundles provides everything needed for a symfony application to enable distributed tracing.

It utilizes the PHP implementation of the opentracing specification and wraps it in an opinionated fashion. It also aims to never disrupt your application, by not throwing exceptions and sending tracing data to the agent as late as possible in the Symfony lifecycle.

The core contains:

• kernel/console event subscribers to automatically instrument the application, adding useful tags to root spans
• convenience functions to create tracing spans manually, including logging messages and tagging spans
• automatic tracing header propagation for PSR-18 clients
• a convenience function for passing the tracing headers to PSR-7 requests or arrays manually

Additional bundles contain:

• a monolog processor to enrich log contexts with the current span context
• Guzzle client automatic spanning and header propagation
• php-http/httplug-bundle automatic spanning and header propagation
• Doctrine DBAL automatic spanning
• amqplib/RabbitMQ automatic spanning and header propagation
• eMAGTechLabs/RabbitMqBundle automatic spanning and header propagation

Installation

Choose tracer implementation

The core itself is only a library and should not be installed directly. You need to choose from different tracer implementation bundles, which will then use this library.

Jaeger

• require the dependencies:

    composer req auxmoney/opentracing-bundle-jaeger

• if not done already: spin up development jaeger instance (All in One)

Note: when setting up a reliable production environment, keep in mind using the agent approach, that Jaeger proposes. Especially having the jaeger agent ideally available on localhost will prevent you from experiencing trace or span loss due to UDP packet size limitations by the involved networks.

Zipkin

• require the dependencies:

    composer req auxmoney/opentracing-bundle-zipkin

• if not done already: spin up development zipkin instance (Docker)

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\OpentracingBundle\OpentracingBundle();

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

Configuration

You can optionally configure environment variables, however, the default configuration will run fine out of the box for a tracing agent on localhost. 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_AGENT_HOST	auxmoney_opentracing.agent.host	string	localhost	hostname or IP of the agent
AUXMONEY_OPENTRACING_AGENT_PORT	auxmoney_opentracing.agent.port	string	(depends on the chosen tracer)	port of the agent
AUXMONEY_OPENTRACING_PROJECT_NAME	auxmoney_opentracing.project.name	string	basename(kernel.project_dir)	passed to the tracer as tracer name / service name
AUXMONEY_OPENTRACING_SAMPLER_CLASS	auxmoney_opentracing.sampler.class	string	(depends on the chosen tracer)	class of the using sampler
AUXMONEY_OPENTRACING_SAMPLER_VALUE	auxmoney_opentracing.sampler.value	string	(depends on the chosen tracer and sampler)	must be a JSON decodable string, for the configuration of the chosen sampler
AUXMONEY_OPENTRACING_RESPONSE_HEADER	auxmoney_opentracing.response.header	string	true	if HTTP responses should ship the trace id as header; set to false (as string) to deactivate

Usage

Propagation of tracing headers

For PSR-18 compatible clients, this bundle provides automatic tracing header propagation.

For Guzzle clients, the Guzzle bundle provides automatic tracing header propagation.

Manual propagation of tracing headers

If you use neither PSR-18 nor Guzzle, you need to inject the trace headers into every outgoing PSR-7 compatible request. To do so, simply use

    Auxmoney\OpentracingBundle\Service\Tracing::injectTracingHeaders(Psr\Http\Message\RequestInterface $request): Psr\Http\Message\RequestInterface

on the request and use the resulting request with your favorite request client.

If you are using a request that is not PSR-7 compatible, you can inject the headers directly into an array using

    Auxmoney\OpentracingBundle\Service\Tracing::injectTracingHeadersIntoCarrier(array $carrier): array

passing the array representing the headers of your request and use the resulting array with your favorite request client.

Automatic tracing

Out of the box, the bundle will trace some spans automatically:

• span of the kernel lifecycle (from kernel.request to kernel.finish_request)
• span of controller lifecycles (from each kernel.controller to each kernel.response, including kernel.exception)
• span of the command lifecycle (from console.command to console.terminate, including console.error)

In case of exceptions thrown, it will additionally log exception types and messages to a controller/command span.

Manual tracing

You can inject the tracing service automatically (via autowiring) or use the provided service alias @auxmoney_opentracing.

Manual spanning

You can define spans manually, by using

    Auxmoney\OpentracingBundle\Service\Tracing::startActiveSpan(string $operationName, array $options = null): void

and

    Auxmoney\OpentracingBundle\Service\Tracing::finishActiveSpan(): void

respectively.

$operationName is the displayed name of the trace operation, $options is an associative array of tracing options; the main usage is $options['tags'], which is an associative array of user defined tags (key value pairs). See the documentation for starting spans for more information.

Tagging spans

You can set tags (key value pairs) to the currently active span with

    Auxmoney\OpentracingBundle\Service\Tracing::setTagOfActiveSpan(string $key, string|bool|int|float $value): void

You should respect the span conventions of the opentracing project when setting tags to spans.

Logging in spans

You can always attach logs (key value pairs) to the currently active span with

    Auxmoney\OpentracingBundle\Service\Tracing::logInActiveSpan(array $fields): void

You should respect the log conventions of the opentracing project when logging fields.

Baggage items

You can propagate baggage items (key value pairs) in-band across process boundaries with

    Auxmoney\OpentracingBundle\Service\Tracing::setBaggageItem(string $key, string $value): void

and retrieve them with

    Auxmoney\OpentracingBundle\Service\Tracing::getBaggageItem(string $key): ?string

You should use this feature thoughtfully and with care. Every key and value is copied into every local and remote child of the associated Span, and that can add up to a lot of network and cpu overhead.

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.

Doc

Various informations regarding the bundle and its usage is available in the doc section.