Download the PHP package vinelab/tracing-laravel without Composer

On this page you can find all versions of the php package vinelab/tracing-laravel. It is possible to download/install these versions without Composer. Possible dependencies are resolved automatically.

FAQ

After the download, you have to make one include require_once('vendor/autoload.php');. After that you have to import the classes with use statements.

Example:
If you use only one package a project is not needed. But if you use more then one package, without a project it is not possible to import the classes with use statements.

In general, it is recommended to use always a project to download your libraries. In an application normally there is more than one library needed.
Some PHP packages are not free to download and because of that hosted in private repositories. In this case some credentials are needed to access such packages. Please use the auth.json textarea to insert credentials, if a package is coming from a private repository. You can look here for more information.

  • Some hosting areas are not accessible by a terminal or SSH. Then it is not possible to use Composer.
  • To use Composer is sometimes complicated. Especially for beginners.
  • Composer needs much resources. Sometimes they are not available on a simple webspace.
  • If you are using private repositories you don't need to share your credentials. You can set up everything on our site and then you provide a simple download link to your team member.
  • Simplify your Composer build process. Use our own command line tool to download the vendor folder as binary. This makes your build process faster and you don't need to expose your credentials for private repositories.
Please rate this library. Is it a good library?

Informations about the package tracing-laravel

Laravel Tracing

Introduction

Distributed tracing is the process of tracking the activity resulting from a request to an application. With this feature, you can:

Simply put, distributed tracing is a knowledge tool. One of the most important perks of having it in your project is that deveopers can learn the system by simply following the traces it makes.

See how Uber is using distributed tracing to make sense of large number of microservices and interactions within their product:

A distributed trace is composed of multiple spans, which represent time spent in services or resources of those services.

Each Span has the following:

Spans are typically displayed for your view as a time axis where each span can be unfolded to inpect additional details:

image

The Tracer interface (available via Trace facade) creates Spans and understands how to Inject (serialize) and Extract (deserialize) them across process boundaries.

See OpenTracing spec for more details on semantics behind distributed tracing.

Requirements

This package requires PHP >= 7.1 and Laravel 5.5 or later. We also offer limited Lumen support (basic tracing and http middleware).

Installation

First, install the package via Composer:

After installation, you can publish the package configuration using the vendor:publish command. This command will publish the tracing.php configuration file to your config directory:

You may configure the driver and service name in your .env file:

You should also add credentials for your respective driver as described in the section below.

For Lumen, see dedicated section with installation instructions.

Driver Prerequisites

Zipkin

Use the following environment variables to configure Zipkin:

If the collector is unreachable via a given hostname, you might see debug messages about that printed with each request. If you want to ignore these in production, simply edit your logging configuration to omit debug level messages.

Jaeger

Jaeger is not "officially" supported because of the lack of stable instrumentation for PHP.

However, you can still post spans to Jaeger collector with Zipkin driver using Zipkin compatible HTTP endpoint. In fact, that's the recommended way to use this library since Jaeger's UI is just that much more convenient than Zipkin's.

There are some downsides, however:

We'll consider improving Jaeger support once its instrumetation matures.

Null

The package also includes null driver that discards created spans.

Usage

You will work with tracing via a Trace facade provided by this package.

Creating Spans

Starting new trace is as simple as calling startSpan method with name for a logical operation the span represents:

Often, you need to continue an existing trace which is why startSpan also accepts additional parameter for span context. SpanContext may be propagated via various channels including HTTP requests, AMQP messages, arrays or even another span:

The possibilities are limitless. Refer to Context Propagation section for more details.

Customizing Spans

Override span name:

Add tags, which may be used as lookup keys (to search span on UI) or additional details:

Retrieving Spans

You can retrieve the current span, which is also your most recently created span:

The first span you create when processing a request in the service is called a root span (not to mix with the global root span of the trace):

After you call flush, the root span is reset.

Controlling Spans

You may finish the span by calling finish on it. Span duration is derived by subtracting the start timestamp from this:

You can log additional data between span start and finish. For example, annotate creates a time-stamped event to explain latencies:

Flushing Spans

Flush refers to the process of sending all pending spans to the transport. It will also reset the state of the tracer including the active spans and UUID:

Most of the time though you don't need to explicitly call flush. Since PHP is designed to die after each request, we already handle finishing the root span and calling flush upon application shutdown for you.

It's only when processing requests continuously in a loop (e.g. AMQP channels) that you must resort to calling flush manually.

Logging

Each root span is associated with a unique identifier that can be used to lookup its trace. It is recommended you include it as part of context when reporting errors to bridge the gap between different parts of your monitoring stack:

Custom drivers may also support logging structured data (not available in Zipkin) which can be used for integrating tracing with a Log facade:

Middleware

This package includes a \Vinelab\Tracing\Middleware\TraceRequests middleware to take care of continuing the trace from incoming HTTP request.

You should register middleware class in the $middleware property of your app/Http/Kernel.php class.

The middleware adds the following tags on a root span:

Request and response body are only included for whitelisted content-types. See logging.content_types option in your config/tracing.php.

You can override the default name of the span (which is VERB /path/for/route) in the controller:

Console Commands

Lumen does not support this feature, but you can still create traces for commands manually using tracer instance.

Let your console commsands be traced by adding Vinelab\Tracing\Contracts\ShouldBeTraced interface to your class.

The container span will include the following tags:

The span will be named after the console command. You can override the default name of the span in the command itself:

Queue Jobs

Lumen does not support this feature, but you can still create traces for jobs manually using tracer instance.

Let your queue jobs be traced by adding Vinelab\Tracing\Contracts\ShouldBeTraced interface to your job class.

The container span will include the following tags:

As the name implies, job_input allows you to view your job's contructor parameters as JSON. Serialization of objects to this JSON string can be controlled by implementing one of the following interfaces: Arrayable, Jsonable, JsonSerializable, or a __toString method. A fallback behavior is to print all your object's public properties.

Constructor arguments must be saved as a class property with the same name (see ProcessPodcast example below).

The span will be named after the queue job class. You can override the default name of the span in the job itself:

Note here that the queue span may not necessarily be the root span of the trace. You would usually want the queue to continue the trace from where it left of when the job was dispatched. You can achieve this by simply giving SpanContext to the job's constructor:

The job above can be dispatched like so:

The rest will be handled automatically. Note that SpanContext will be excluded from logged job_input.

This package doesn't automatically handle tracing of queued closures and queued event listeners. You can still trace them manually by opening and closing spans. Improving support for these features might be considered for future versions of the package.

Context Propagation

As we talked about previously, the tracer understands how to inject and extract trace context across different applications (services).

We have already seen the example of extracting trace from HTTP request:

Of course, you don't need to do this manually because this package already includes a middleware to handle this for you, but the trace may not necessarily come from HTTP request.

The second parameter is a format descriptor that tells us how to deserialize tracing headers from given carrier. By default, the following formats are supported:

You may also add your own format using registerExtractionFormat method.

The injection format must implement Vinelab\Tracing\Contracts\Extractor. Refer to default Zipkin implementation for example.

Naturally, you can also inject existing trace context from the current span into a given carrier so that another service can continue the trace:

By default, the following formats are supported:

You may also add your own format using registerInjectionFormat method.

The injection format must implement Vinelab\Tracing\Contracts\Injector. Refer to default Zipkin implementation for example.

You can also use injectContext method if you need to pass span context explicitly:


IMPORTANT: You don't need to create a custom propagation format if you need to get something done quickly. You can always avail of the default TEXT_MAP format to inject or extract tracing headers from an associative array.

Custom Drivers

Writing New Driver

New drivers must adhere to Vinelab\Tracing\Contracts\Tracer contract. Refer to the default ZipkinTracer imlementation for example.

Registering New Driver

Once you have written your custom driver, you may register it using the extend method of the TracingDriverManager. You should call the extend method from the boot method of your AppServiceProvider or any other service provider used by your application. For example, if you have written a JaegerTracer, you may register it like so:

Once your driver has been registered, you may specify it as your tracing driver in your environment variables:

Usage With Lumen

You need to register service provider manually in bootstrap/app.php file:

You should also register middleware in the same file:

Add the following lines to the end of public/index.php file:

Finally, you may also want to copy over config/tracing.php from this repo if you need to customize default settings.

If you don't use facades in your Lumen project, you can resolve tracer instance from container like this:

Note that Lumen currently doesn't support automatic tracing for console commands and jobs because it doesn't dispatch some events and terminating callbacks. However, you can still create traces manually where you need them.

Integrations

Lucid Architecture

This package includes optional Vinelab\Tracing\Integration\Concerns\TracesLucidArchitecture trait to enable tracing for Lucid projects:


All versions of tracing-laravel with dependencies

PHP Build Version
Package Version
Requires php Version >=7.1.3
illuminate/bus Version >=5.5.0
illuminate/console Version >=5.5.0
illuminate/contracts Version >=5.5.0
illuminate/http Version >=5.5.0
illuminate/log Version >=5.5.0
illuminate/container Version >=5.5.0
illuminate/queue Version >=5.5.0
illuminate/routing Version >=5.5.0
illuminate/support Version >=5.5.0
openzipkin/zipkin Version ~2.0.2|~3.0
psr/http-message Version ~1.0
ramsey/uuid Version ~3.0|~4.0
Composer command for our command line client (download client) This client runs in each environment. You don't need a specific PHP version etc. The first 20 API calls are free. Standard composer command

The package vinelab/tracing-laravel contains the following files

Loading the files please wait ....