open-telemetry / opentracing-shim
OpenTracing shim for OpenTelemetry
Requires
Requires (Dev)
- friendsofphp/php-cs-fixer: ^3
- guzzlehttp/guzzle: ^7.4
- nyholm/psr7: ^1.6
- open-telemetry/exporter-otlp: ^1
- open-telemetry/exporter-zipkin: ^1
- open-telemetry/sdk: >=1.0.0beta7
- phan/phan: ^5.0
- phpstan/phpstan: ^1.1
- phpstan/phpstan-phpunit: ^1.0
- phpunit/phpunit: ^9.5
- psalm/plugin-phpunit: ^0.16
- vimeo/psalm: ^4.0
Suggests
- open-telemetry/exporter-otlp: To export via the OTLP protocol
- open-telemetry/exporter-zipkin: To export via zipkin
- open-telemetry/transport-grpc: To export via gRPC
README
This package is intended to help OpenTracing users migrate to OpenTelemetry. The OpenTelemetry documentation provides guidance on how to migrate to OpenTelemetry: https://opentelemetry.io/docs/migration/opentracing/
Installation
API + SDK
This package depends on the OpenTelemetry API, but an OpenTelemetry SDK and an exporter should also be provided to enable exporting spans.
You usually need to supply a PSR-7 and PSR-18 implementation, since most exporters use HTTP to transport telemetry data (gRPC is the exception).
OTLP Exporter
Usually logs are exported to some receiver via the otlp
protocol in the protobuf
format, via http or gRPC
.
This requires:
- a
protobuf
implementation; either the protobuf extension or thegoogle/protobuf
package - the
open-telemetry/exporter-otlp
package - the
open-telemetry/transport-grpc
package, if using gRPC transport - a PSR-7 and PSR-18 implementation, if using HTTP transport
Zipkin exporter
OpenTelemetry supports exporting via the zipkin protocol, which requires the open-telemetry/exporter-zipkin
package. Traces can
be exported to a zipkin instance directly, or to any other service which supports the zipkin protocol.
Setup
To use this package, you need to create an OpenTelemetry tracer provider
, which is the only parameter used by the shim tracer:
$tracerProvider = new OpenTelemetry\SDK\Trace\TracerProvider(/*params*/); OpenTelemetry\SDK\Common\Util\ShutdownHandler::register([$tracerProvider, 'shutdown']); $tracer = new OpenTelemetry\Contrib\Shim\OpenTracing\Tracer($tracerProvider);
There are a number of ways to set up a tracer provider, please see the official documentation or the examples.
Notes
- OpenTelemetry does not support setting span kind after span creation, so adding a
span.kind
tag will not set the span's kind. An attribute will still be emitted, though. Span::log([/*$fields*/])
will use anevent
field as the log name, otherwiselog
.- errors may be logged via
Span::log
, using the keyexception
. AThrowable
should be the field's value, but a string is allowable and will be converted to an exception