https://github.com/jonahgeorge/jaeger-client-php
Jaeger Bindings for PHP OpenTracing API
https://github.com/jonahgeorge/jaeger-client-php
distributed-tracing jaeger jaegertracing opentracing php
Last synced: 5 months ago
JSON representation
Jaeger Bindings for PHP OpenTracing API
- Host: GitHub
- URL: https://github.com/jonahgeorge/jaeger-client-php
- Owner: jonahgeorge
- License: mit
- Created: 2017-10-21T17:25:22.000Z (almost 8 years ago)
- Default Branch: master
- Last Pushed: 2025-02-24T16:33:40.000Z (7 months ago)
- Last Synced: 2025-05-13T12:08:06.255Z (5 months ago)
- Topics: distributed-tracing, jaeger, jaegertracing, opentracing, php
- Language: PHP
- Homepage: https://jaegertracing.io
- Size: 270 KB
- Stars: 145
- Watchers: 8
- Forks: 47
- Open Issues: 15
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
Awesome Lists containing this project
README
 [![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
[
'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