diff options
Diffstat (limited to 'vendor/jonahgeorge/jaeger-client-php/README.md')
| -rw-r--r-- | vendor/jonahgeorge/jaeger-client-php/README.md | 219 |
1 files changed, 219 insertions, 0 deletions
diff --git a/vendor/jonahgeorge/jaeger-client-php/README.md b/vendor/jonahgeorge/jaeger-client-php/README.md new file mode 100644 index 000000000..6396bb70f --- /dev/null +++ b/vendor/jonahgeorge/jaeger-client-php/README.md @@ -0,0 +1,219 @@ + [![PHP version][packagist-img]][packagist] + +# Jaeger Bindings for PHP OpenTracing API + +This is a client-side library that can be used to instrument PHP apps for distributed trace collection, +and to send those traces to Jaeger. See the [OpenTracing PHP API](https://github.com/opentracing/opentracing-php) +for additional detail. + +## Contributing and Developing + +Please see [CONTRIBUTING.md](./CONTRIBUTING.md). + +## Installation + +Jaeger client can be installed via Composer: + +```bash +composer require jonahgeorge/jaeger-client-php +``` + +## Getting Started + +```php +<?php + +require_once 'vendor/autoload.php'; + +use Jaeger\Config; +use OpenTracing\GlobalTracer; + +$config = new Config( + [ + 'sampler' => [ + 'type' => Jaeger\SAMPLER_TYPE_CONST, + 'param' => true, + ], + 'logging' => true, + ], + 'your-app-name' +); +$config->initializeTracer(); + +$tracer = GlobalTracer::get(); + +$scope = $tracer->startActiveSpan('TestSpan', []); +$scope->close(); + +$tracer->flush(); +``` + +### Samplers + +List of supported samplers, for more info about samplers, please read [Jaeger Sampling](https://www.jaegertracing.io/docs/1.9/sampling/) guide. + +#### Const sampler +This sampler either samples everything, or nothing. + +##### Configuration +``` +'sampler' => [ + 'type' => Jaeger\SAMPLER_TYPE_CONST, + 'param' => true, // boolean wheter to trace or not +], +``` + +#### Probabilistic sampler +This sampler samples request by given rate. + +##### Configuration +``` +'sampler' => [ + 'type' => Jaeger\SAMPLER_TYPE_PROBABILISTIC, + 'param' => 0.5, // float [0.0, 1.0] +], +``` + +#### Rate limiting sampler +Samples maximum specified number of traces (requests) per second. + +##### Requirements +* `psr/cache` PSR-6 cache component to store and retrieve sampler state between requests. +Cache component is passed to `Jaeger\Config` trough its constructor. +* `hrtime()` function, that can retrieve time in nanoseconds. You need either `php 7.3` or [PECL/hrtime](http://pecl.php.net/package/hrtime) extension. + +##### Configuration +``` +'sampler' => [ + 'type' => Jaeger\SAMPLER_TYPE_RATE_LIMITING, + 'param' => 100 // integer maximum number of traces per second, + 'cache' => [ + 'currentBalanceKey' => 'rate.currentBalance' // string + 'lastTickKey' => 'rate.lastTick' // string + ] +], +``` +## Dispatch mode + +The library supports 3 ways of sending data to Jaeger Agent: + +1. `Zipkin.thrift` over Compact protocol (socket - UDP) - default +2. `Jaeger.thrift` over Binary protocol (socket - UDP) +2. `Jaeger.thrift` over Binary protocol (HTTP) + +If you want to enable "`Jaeger.thrift` over Binary protocol" one or other, than +you need to set `dispatch_mode` config option or `JAEGER_DISPATCH_MODE` env +variable. + +Allowed values for `dispatch_mode` are: +- `jaeger_over_binary_udp` +- `jaeger_over_binary_http` +- `zipkin_over_compact_udp` + +There are 3 constants available, so it is better to use them: +```php +class Config +{ + const ZIPKIN_OVER_COMPACT_UDP = "zipkin_over_compact_udp"; + const JAEGER_OVER_BINARY_UDP = "jaeger_over_binary_udp"; + const JAEGER_OVER_BINARY_HTTP = "jaeger_over_binary_http"; + ... +} +``` + +A possible config with custom `dispatch_mode` can look like this: +```php +// config.php + +use Jaeger\Config; + +return [ + 'sampler' => [ + 'type' => Jaeger\SAMPLER_TYPE_CONST, + 'param' => true, + ], + 'logging' => true, + "tags" => [ + // process. prefix works only with JAEGER_OVER_HTTP, JAEGER_OVER_BINARY + // otherwise it will be shown as simple global tag + "process.process-tag-key-1" => "process-value-1", // all tags with `process.` prefix goes to process section + "process.process-tag-key-2" => "process-value-2", // all tags with `process.` prefix goes to process section + "global-tag-key-1" => "global-tag-value-1", // this tag will be appended to all spans + "global-tag-key-2" => "global-tag-value-2", // this tag will be appended to all spans + ], + "local_agent" => [ + "reporting_host" => "localhost", +// You can override port by setting local_agent.reporting_port value + "reporting_port" => 6832 + ], +// Different ways to send data to Jaeger. Config::ZIPKIN_OVER_COMPACT - default): + 'dispatch_mode' => Config::JAEGER_OVER_BINARY_UDP, +]; +``` +The full example you can see at `examples` directory. + +By default, for each `dispatch_mode` there is default `reporting_port` config value. Table with +default values you can see below: + +`dispatch_mode` | default `reporting_port` +------------------------ | ---------------- +ZIPKIN_OVER_COMPACT_UDP | 5775 +JAEGER_OVER_BINARY_UDP | 6832 +JAEGER_OVER_BINARY_HTTP | 14268 + +## IPv6 + +In case you need IPv6 support you need to set `ip_version` Config variable. +By default, IPv4 is used. There is an alias `Config::IP_VERSION` which you can use +as an alternative to raw `ip_version`. + +Example: + +```php +use Jaeger\Config; + +$config = new Config( + [ + "ip_version" => Config::IPV6, // <-- or use Config::IP_VERSION constant + 'logging' => true, + 'dispatch_mode' => Config::JAEGER_OVER_BINARY_UDP, + ], + 'serviceNameExample', +); +$config->initializeTracer(); +``` +or + +```php +use Jaeger\Config; + +$config = new Config( + [ + Config::IP_VERSION => Config::IPV6, // <-- + 'logging' => true, + 'dispatch_mode' => Config::JAEGER_OVER_BINARY_UDP, + ], + 'serviceNameExample', +); +$config->initializeTracer(); +``` + + +## Testing + +Tests are located in the `tests` directory. See [tests/README.md](./tests/README.md). + +## Roadmap + +- [Support Span baggage](https://github.com/jonahgeorge/jaeger-client-php/issues/5) +- [Support Tracer metrics](https://github.com/jonahgeorge/jaeger-client-php/issues/12) +- [Support Tracer error reporting](https://github.com/jonahgeorge/jaeger-client-php/issues/13) + +## License + +[MIT License](./LICENSE). + +[ci-img]: https://travis-ci.org/jonahgeorge/jaeger-client-php.svg?branch=travis +[ci]: https://travis-ci.org/jonahgeorge/jaeger-client-php +[packagist-img]: https://badge.fury.io/ph/jonahgeorge%2Fjaeger-client-php.svg +[packagist]: https://badge.fury.io/ph/jonahgeorge%2Fjaeger-client-php |