diff options
Diffstat (limited to 'vendor/opentracing/opentracing/README.md')
| -rw-r--r-- | vendor/opentracing/opentracing/README.md | 306 |
1 files changed, 0 insertions, 306 deletions
diff --git a/vendor/opentracing/opentracing/README.md b/vendor/opentracing/opentracing/README.md deleted file mode 100644 index ce03bc951..000000000 --- a/vendor/opentracing/opentracing/README.md +++ /dev/null @@ -1,306 +0,0 @@ -# OpenTracing API for PHP - -[](https://github.com/opentracing/opentracing-php/actions/workflows/ci.yml) -[](http://opentracing.io) -[](https://packagist.org/packages/opentracing/opentracing) -[](https://php.net/) -[](https://github.com/opentracing/opentracing-php/blob/master/LICENSE) -[](https://gitter.im/opentracing/opentracing-php?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge) - -PHP library for the OpenTracing's API. - -## Required Reading - -In order to understand the library, one must first be familiar with the -[OpenTracing project](http://opentracing.io) and -[specification](http://opentracing.io/documentation/pages/spec.html) more specifically. - -## Installation - -OpenTracing-PHP can be installed via Composer: - -```bash -composer require opentracing/opentracing -``` - -## Usage - -When consuming this library one really only need to worry about a couple of key -abstractions: the `Tracer::startActiveSpan` and `Tracer::startSpan` method, -the `Span` interface, the `Scope` interface and binding a `Tracer` at bootstrap time. Here are code snippets -demonstrating some important use cases: - -### Singleton initialization - -The simplest starting point is to set the global tracer. As early as possible, do: - -```php -use OpenTracing\GlobalTracer; - -GlobalTracer::set(new MyTracerImplementation()); -``` - -### Creating a Span given an existing Request - -To start a new `Span`, you can use the `startSpan` method. - -```php -use OpenTracing\Formats; -use OpenTracing\GlobalTracer; - -... - -// extract the span context -$spanContext = GlobalTracer::get()->extract( - Formats\HTTP_HEADERS, - getallheaders() -); - -function doSomething() { - ... - - // start a new span called 'my_span' and make it a child of the $spanContext - $span = GlobalTracer::get()->startSpan('my_span', ['child_of' => $spanContext]); - - ... - - // add some logs to the span - $span->log([ - 'event' => 'soft error', - 'type' => 'cache timeout', - 'waiter.millis' => 1500, - ]) - - // finish the the span - $span->finish(); -} -``` - -### Starting a new trace by creating a "root span" - -It's always possible to create a "root" `Span` with no parent or other causal reference. - -```php -$span = $tracer->startSpan('my_first_span'); -... -$span->finish(); -``` - -### Active Spans and Scope Manager - -For most use cases, it is recommended that you use the `Tracer::startActiveSpan` function for -creating new spans. - -An example of a linear, two level deep span tree using active spans looks like -this in PHP code: -```php -// At dispatcher level -$scope = $tracer->startActiveSpan('request'); -... -$scope->close(); -``` -```php -// At controller level -$scope = $tracer->startActiveSpan('controller'); -... -$scope->close(); -``` - -```php -// At RPC calls level -$scope = $tracer->startActiveSpan('http'); -file_get_contents('http://php.net'); -$scope->close(); -``` - -When using the `Tracer::startActiveSpan` function the underlying tracer uses an -abstraction called scope manager to keep track of the currently active span. - -Starting an active span will always use the currently active span as a parent. -If no parent is available, then the newly created span is considered to be the -root span of the trace. - -Unless you are using asynchronous code that tracks multiple spans at the same -time, such as when using cURL Multi Exec or MySQLi Polling it is recommended that you -use `Tracer::startActiveSpan` everywhere in your application. - -The currently active span gets automatically finished when you call `$scope->close()` -as you can see in the previous examples. - -If you don't want a span to automatically close when `$scope->close()` is called -then you must specify `'finish_span_on_close'=> false,` in the `$options` -argument of `startActiveSpan`. - -#### Creating a child span assigning parent manually - -```php -$parent = GlobalTracer::get()->startSpan('parent'); - -$child = GlobalTracer::get()->startSpan('child', [ - 'child_of' => $parent -]); - -... - -$child->finish(); - -... - -$parent->finish(); -``` - -#### Creating a child span using automatic active span management - -Every new span will take the active span as parent and it will take its spot. - -```php -$parent = GlobalTracer::get()->startActiveSpan('parent'); - -... - -/* - * Since the parent span has been created by using startActiveSpan we don't need - * to pass a reference for this child span - */ -$child = GlobalTracer::get()->startActiveSpan('my_second_span'); - -... - -$child->close(); - -... - -$parent->close(); -``` - -### Serializing to the wire - -```php -use GuzzleHttp\Client; -use OpenTracing\Formats; - -... - -$tracer = GlobalTracer::get(); - -$spanContext = $tracer->extract( - Formats\HTTP_HEADERS, - getallheaders() -); - -try { - $span = $tracer->startSpan('my_span', ['child_of' => $spanContext]); - - $client = new Client; - - $headers = []; - - $tracer->inject( - $span->getContext(), - Formats\HTTP_HEADERS, - $headers - ); - - $request = new \GuzzleHttp\Psr7\Request('GET', 'http://myservice', $headers); - $client->send($request); - ... - -} catch (\Exception $e) { - ... -} -... -``` - -### Deserializing from the wire - -When using http header for context propagation you can use either the `Request` or the `$_SERVER` -variable: - -```php -use OpenTracing\GlobalTracer; -use OpenTracing\Formats; - -$tracer = GlobalTracer::get(); -$spanContext = $tracer->extract(Formats\HTTP_HEADERS, getallheaders()); -$tracer->startSpan('my_span', [ - 'child_of' => $spanContext, -]); -``` - -### Flushing Spans - -PHP as a request scoped language has no simple means to pass the collected spans -data to a background process without blocking the main request thread/process. -The OpenTracing API makes no assumptions about this, but for PHP that might -cause problems for Tracer implementations. This is why the PHP API contains a -`flush` method that allows to trigger a span sending out of process. - -```php -use OpenTracing\GlobalTracer; - -$application->run(); - -register_shutdown_function(function() { - /* Flush the tracer to the backend */ - $tracer = GlobalTracer::get(); - $tracer->flush(); -}); -``` - -This is optional, tracers can decide to immediately send finished spans to a -backend. The flush call can be implemented as a NO-OP for these tracers. - -### Using `StartSpanOptions` - -Passing options to the pass can be done using either an array or the -SpanOptions wrapper object. The following keys are valid: - -- `start_time` is a float, int or `\DateTime` representing a timestamp with arbitrary precision. -- `child_of` is an object of type `OpenTracing\SpanContext` or `OpenTracing\Span`. -- `references` is an array of `OpenTracing\Reference`. -- `tags` is an array with string keys and scalar values that represent OpenTracing tags. -- `finish_span_on_close` is a boolean that determines whether a span should be finished or not when the -scope is closed. - -```php -$span = $tracer->startActiveSpan('my_span', [ - 'child_of' => $spanContext, - 'tags' => ['foo' => 'bar'], - 'start_time' => time(), -]); -``` - -### Propagation Formats - -The propagation formats should be implemented consistently across all tracers. -If you want to implement your own format, then don't reuse the existing constants. -Tracers will throw an exception if the requested format is not handled by them. - -- `Tracer::FORMAT_TEXT_MAP` should represent the span context as a key value map. There is no - assumption about the semantics where the context is coming from and sent to. - -- `Tracer::FORMAT_HTTP_HEADERS` should represent the span context as HTTP header lines - in an array list. For two context details "Span-Id" and "Trace-Id", the - result would be `['Span-Id: abc123', 'Trace-Id: def456']`. This definition can be - passed directly to `curl` and `file_get_contents`. - -- `Tracer::FORMAT_BINARY` makes no assumptions about the data format other than it is - proprietary and each Tracer can handle it as it wants. - -## Mock implementation - -OpenTracing PHP comes with a mock implementation, it has three purposes: - -1. Helps to iron the API. -2. Works as a reference implementation. -3. Enhances vendor agnostic unit testing as it allows developers to inspect the tracing objects -in order to do assertions about them. - -## Coding Style - -OpenTracing PHP follows the [PSR-2](https://github.com/php-fig/fig-standards/blob/master/accepted/PSR-2-coding-style-guide.md) -coding standard and the [PSR-4](https://github.com/php-fig/fig-standards/blob/master/accepted/PSR-4-autoloader.md) autoloading standard. - -## License - -All the open source contributions are under the terms of the [Apache-2.0 License](https://opensource.org/licenses/Apache-2.0). |