diff --git a/README.md b/README.md index e93c763..20636e4 100644 --- a/README.md +++ b/README.md @@ -42,7 +42,7 @@ The simplest starting point is to set the global tracer. As early as possible, d ### Creating a Span given an existing Request -To start a new `Span`, you can use the `StartSpanFromContext` method. +To start a new `Span`, you can use the `startActiveSpan` method. ```php use Psr\Http\Message\RequestInterface; @@ -57,9 +57,7 @@ To start a new `Span`, you can use the `StartSpanFromContext` method. function doSomething(SpanContext $spanContext, ...) { ... - $span = GlobalTracer::get()->startSpan('my_span', [ - 'child_of' => $spanContext, - ]); + $span = GlobalTracer::get()->startManualSpan('my_span', ['child_of' => $spanContext]); ... @@ -75,35 +73,52 @@ To start a new `Span`, you can use the `StartSpanFromContext` method. ### Starting an empty trace by creating a "root span" -It's always possible to create a "root" `Span` with no parent or other causal -reference. +It's always possible to create a "root" `Span` with no parent or other causal reference. ```php - $span = $tracer->startSpan('my_span'); + $span = $tracer->startActiveSpan('my_first_span'); ... $span->finish(); ``` -### Creating a (child) Span given an existing (parent) Span +#### Creating a child span assigning parent manually ```php - function xyz(Span $parentSpan, ...) { - ... - $span = GlobalTracer::get()->startSpan( - 'my_span', - [ - 'child_of' => $spanContext, - ] - ); - - $span->finish(); - ... - } + use OpenTracing\SpanReference\ChildOf; + + $parent = GlobalTracer::get()->startManualSpan('parent'); + + $child = GlobalTracer::get()->startManualSpan('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->finish(); + ... + $parent->finish(); ``` ### Serializing to the wire ```php + use GuzzleHttp\Client; + use GuzzleHttp\Psr7\Request; use OpenTracing\Carriers\HttpHeaders as HttpHeadersCarrier; use OpenTracing\Context; use OpenTracing\GlobalTracer; @@ -118,11 +133,11 @@ reference. ); try { - $span = $tracer->startSpan('my_span', ['child_of' => $spanContext]); + $span = $tracer->startManualSpan('my_span', ['child_of' => $spanContext]); - $client = new GuzzleHttp\Client; + $client = new Client; - $request = new \GuzzleHttp\Psr7\Request('GET', 'http://myservice'); + $request = new Request('GET', 'http://myservice'); $tracer->inject( $span->context(), @@ -140,7 +155,7 @@ reference. ### Deserializing from the wire -When using http header for context propagation you can use either the `Request` or the `$_SERVER` variable: +When using http header for context propagation you can use the `Request` for example: ```php use OpenTracing\Carriers\HttpHeaders; @@ -163,11 +178,8 @@ 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 -run(); fastcgi_finish_request(); @@ -179,7 +191,6 @@ $tracer->flush(); // release buffer to backend 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 Span Options Passing options to the pass can be done using either an array or the @@ -191,8 +202,6 @@ SpanOptions wrapper object. The following keys are valid: - `tags` is an array with string keys and scalar values that represent OpenTracing tags. ```php -createSpan('my_span', [ @@ -221,5 +230,5 @@ Tracers will throw an exception if the requested format is not handled by 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) +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. diff --git a/src/OpenTracing/ActiveSpanSource.php b/src/OpenTracing/ActiveSpanSource.php new file mode 100644 index 0000000..0ea3eff --- /dev/null +++ b/src/OpenTracing/ActiveSpanSource.php @@ -0,0 +1,40 @@ +deactivate() -> the span is not active but still "running" + * - $span->finish() -> the span is finished and deactivated + * + * @param Span $span + */ + public function deactivate(Span $span); +} diff --git a/src/OpenTracing/GlobalTracer.php b/src/OpenTracing/GlobalTracer.php index 87e5e3d..c3f7c56 100644 --- a/src/OpenTracing/GlobalTracer.php +++ b/src/OpenTracing/GlobalTracer.php @@ -14,7 +14,7 @@ final class GlobalTracer * Those who use GlobalTracer (rather than directly manage a Tracer instance) * should call GlobalTracer::set as early as possible in bootstrap, prior to * start a new span. Prior to calling GlobalTracer::set, any Spans started - * via the `Tracer::startSpan` (etc) globals are noops. + * via the `Tracer::startActiveSpan` (etc) globals are noops. * * @param Tracer $tracer */ diff --git a/src/OpenTracing/NoopActiveSpanSource.php b/src/OpenTracing/NoopActiveSpanSource.php new file mode 100644 index 0000000..5a02671 --- /dev/null +++ b/src/OpenTracing/NoopActiveSpanSource.php @@ -0,0 +1,24 @@ +tracer->startActiveSpan('request.handler'); + * $user = $this->repository->getUser($userId); + * } + * + * function getUser($userId) + * { + * // `$childSpan` has `$rootSpan` as parent. + * $childSpan = $this->tracer->startActiveSpan('db.query'); + * } + * * @param string $operationName * @param array|SpanOptions $options * @return Span * @throws InvalidSpanOption for invalid option * @throws InvalidReferencesSet for invalid references set */ - public function startSpan($operationName, $options); + public function startActiveSpan($operationName, $options = []); + + /** + * @param string $operationName + * @param array|SpanOptions $options + * @return Span + * @throws InvalidSpanOption for invalid option + * @throws InvalidReferencesSet for invalid references set + */ + public function startManualSpan($operationName, $options = []); + + /** + * @return ActiveSpanSource + */ + public function getActiveSpanSource(); + + /** + * @return Span + */ + public function getActiveSpan(); /** * @param SpanContext $spanContext