1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
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
|
