Awesome
🛑 This library is DEPRECATED!
There will be no new releases of this library.
We urge all users to migrate to OpenTelemetry. Please refer to the notice in the documentation for details.
<hr/>
jaeger-client-cpp
Jaeger SDK with OpenTracing API for C++ binding.
Contributing
Please see CONTRIBUTING.md.
Building
jaeger-client-cpp is built using CMake. It will automatically download needed dependencies using Hunter.
To build:
mkdir build
cd build
cmake ..
make
After building, the example program can be run with:
./app ../examples/config.yml
To run tests:
make test
To install the library:
make install
Generated files
This project uses Apache Thrift for wire-format protocol support code generation. It currently requires Thrift 0.11.0.
The code can be re-generated with
$ git submodule update --init
$ find idl/thrift/ -type f -name \*.thrift -exec thrift -gen cpp -out src/jaegertracing/thrift-gen {} \;
$ git apply scripts/thrift-gen.patch
Updating Agent Host and Port
The default host and port for Jaeger Agent is 127.0.0.1:6831. When the application and Jaeger Agent are running in different containers on the same host, the application's notion of localhost/127.0.0.1 it restriced to its own container, so in this case it's usually necessary to override the Agent's host/port by updating your reporter configuration:
YAML configuration:
reporter:
localAgentHostPort: jaeger-agent:6831
NOTE: It is not recommended to use a remote host for UDP connections.
Connecting directly to the Collector
In case the client should connect directly to the collector instead of going through an agent, it's necessary update the reporter configuration
reporter:
endpoint: http://${collectorhost}:${collectorport}/api/traces
Note that if both localAgentHostPort and endpoint are specified, the endpoint will be used.
Updating Sampling Server URL
The default sampling collector URL is http://127.0.0.1:5778/sampling. Similar to UDP address above, you can use a different URL by updating the sampler configuration.
sampler:
samplingServerURL: http://jaeger-agent.local:5778/sampling
Configuration via Environment
It's possible to populate the tracer configuration from the environement variables by calling jaegertracing::Config::fromEnv.
The following property names are currently available:
| Property | Description |
|---|---|
| JAEGER_SERVICE_NAME | The service name |
| JAEGER_DISABLED (not recommended) | Instructs the Configuration to return a no-op tracer |
| JAEGER_AGENT_HOST | The hostname for communicating with agent via UDP |
| JAEGER_AGENT_PORT | The port for communicating with agent via UDP |
| JAEGER_ENDPOINT | The traces endpoint, in case the client should connect directly to the Collector, like http://jaeger-collector:14268/api/traces |
| JAEGER_PROPAGATION | The propagation format used by the tracer. Supported values are jaeger and w3c |
| JAEGER_REPORTER_LOG_SPANS | Whether the reporter should also log the spans |
| JAEGER_REPORTER_MAX_QUEUE_SIZE | The reporter's maximum queue size |
| JAEGER_REPORTER_FLUSH_INTERVAL | The reporter's flush interval (ms) |
| JAEGER_SAMPLER_TYPE | The sampler type |
| JAEGER_SAMPLER_PARAM | The sampler parameter (double) |
| JAEGER_SAMPLING_ENDPOINT | The url for the remote sampling conf when using sampler type remote. Default is http://127.0.0.1:5778/sampling |
| JAEGER_TAGS | A comma separated list of name = value tracer level tags, which get added to all reported spans. The value can also refer to an environment variable using the format ${envVarName:default}, where the :default is optional, and identifies a value to be used if the environment variable cannot be found |
SelfRef
Jaeger Tracer supports an additional reference type call 'SelfRef'. It returns an opentracing::SpanReference which can be passed to Tracer::StartSpan to influence the SpanContext of the newly created span. Specifically, the new span inherits the traceID and spanID from the passed SELF reference. It can be used to pass externally generated IDs to the tracer, with the purpose of recording spans from data generated elsewhere (e.g. from logs), or by augmenting the data of the existing span (Jaeger backend will merge multiple instances of the spans with the same IDs). Must be the lone reference, can be used only for root spans.
Usage example:
jaegertracing::SpanContext customCtx { {1, 2}, 3, 0, 0, jaegertracing::SpanContext::StrMap() }; // TraceId and SpanID must be != 0
auto span = tracer->StartSpan("spanName", { jaegertracing::SelfRef(&customCtx) });