Awesome
Overview
Jaeger is an open-source, distributed tracing system that follows the OpenTracing standard. To facilitate user integration with the Jaeger system, we provide a Jaeger Tracing plugin that enables convenient collection and reporting of Jaeger tracing data.
Usage
For detailed examples, please refer to the Jaeger examples.
Import dependencies
Bazel
-
Import repository
In the project's
WORKSPACE
file, import thecpp-tracing-jaeger
repository and its dependencies:load("@bazel_tools//tools/build_defs/repo:git.bzl", "git_repository") git_repository( name = "trpc_cpp", remote = "https://github.com/trpc-group/trpc-cpp.git", branch = "main", ) load("@trpc_cpp//trpc:workspace.bzl", "trpc_workspace") trpc_workspace() git_repository( name = "cpp-tracing-jaeger", remote = "https://github.com/trpc-ecosystem/cpp-tracing-jaeger.git", branch = "main", ) load("@cpp-tracing-jaeger//trpc:workspace.bzl", "tracing_jaeger_workspace") tracing_jaeger_workspace()
The jaeger-client-cpp has many dependencies on third-party libraries, and it can be cumbersome to compile it entirely from source using Bazel. To simplify the compilation process, we introduce jaeger-client-cpp (v0.9.0) and its necessary dependency library, thrift (v0.12.0-p0 version), through a local library approach. Before compiling, users need to install jaeger-client-cpp and thrift into the /usr/local directory.
-
Import plugin
Import the "
trpc/tracing/jaeger:jaeger_tracing_api
" dependency in the targets that require Jaeger. For example:cc_binary( name = "helloworld_server", srcs = ["helloworld_server.cc"], deps = [ "@cpp-tracing-jaeger//trpc/tracing/jaeger:jaeger_tracing_api", ... ], )
CMake
Not supported yet.
Plugin configuration
To use the Jaeger plugin, you must add the plugin configuration to the framework configuration file:
plugins:
tracing:
jaeger:
disabled: false
enable_logger: false
reporter:
localAgentHostPort: 127.0.0.1:6831
sampler:
type: const
param: 1
The plugin supports all yaml configuration parameters of jaeger-client-cpp v0.9.0. Here, we will only explain the configuration options specific to the plugin and some key configuration options of jaeger-client-cpp. For other configuration parameters, please refer to the configuration of jaeger-client-cpp.
Configuration options | Type | Value | Description |
---|---|---|---|
enable_logger | bool | Default value is false. | Controls whether to print Span information. |
disabled | bool | Default value is false. | Controls whether to disable tracing data collection and reporting. |
sampler | Mapping | The default value for "type" is "const" and the default value for "param" is 1, indicating full sampling. | Sets sampling strategy. |
reporter:localAgentHostPort | string | Default value is "127.0.0.1:6831". | The reporting address of tracing data |
Enable ClientFilter
Just add the Jaeger filter in the client configuration of the framework:
client:
filter:
- jaeger
The operationName
of the Span created by the ClientFilter is the name of the callee interface, which obtained from ClientContext::GetFuncName. Additionally, the filter will automatically sets the following data into the Span:
Key | Type | Value |
---|---|---|
span.kind | Tag | "client" |
peer.service | Tag | The name of the callee service. |
peer.hostname | Tag | The name of the callee container. |
peer.ipv4/peer.ipv6 | Tag | The IP address of the callee service. |
peer.port | Tag | The port of the callee service. |
_trace_ext.response.size | Tag | The size of the response packet in bytes. |
_trace_ext.namespace | Tag | The namespace. |
_trace_ext.envname | Tag | The env. |
_trace_ext.ret | Tag | The error code of the invocation. |
error | Tag | true (It is only set when error occurs during the invocation) |
event | Log | "error" (It is only set when error occurs during the invocation) |
message | Log | The error message. (It is only set when error occurs during the invocation) |
Enable ServerFilter
Just add the Jaeger filter in the server configuration of the framework:
server:
filter:
- jaeger
The operationName
of the Span created by the ServerFilter is the name of the callee interface, which obtained from ServerContext::GetFuncName. Additionally, the filter will automatically sets the following data into the Span:
Key | Type | Value |
---|---|---|
span.kind | Tag | "server" |
_trace_ext.request.size | Tag | The size of the request packet in bytes. |
_trace_ext.namespace | Tag | The namespace. |
_trace_ext.envname | Tag | The env. |
_trace_ext.ret | Tag | The error code of the invocation. |
error | Tag | true (It is only set when error occurs during the invocation) |
event | Log | "error" (It is only set when error occurs during the invocation) |
message | Log | The error message. (It is only set when error occurs during the invocation) |
Initialization
The Jaeger plugin provides an interface for registering plugin and filters called ::trpc::jaeger::Init
. Users need to call this interface for initialization before starting the framework.
-
For server scenarios, users need to call it in the
TrpcApp::RegisterPlugins
function during service startup:#include "trpc/tracing/jaeger/jaeger_tracing_api.h" class HelloworldServer : public ::trpc::TrpcApp { public: ... int RegisterPlugins() override { ::trpc::jaeger::Init(); return 0; } };
-
For pure client scenarios, it needs to be called after initializing the framework configuration but before starting other modules of the framework:
#include "trpc/tracing/jaeger/jaeger_tracing_api.h" int main(int argc, char* argv[]) { ParseClientConfig(argc, argv); ::trpc::jaeger::Init(); return ::trpc::RunInTrpcRuntime([]() { return Run(); }); }
Other features
In addition to the initialization interface, the Jaeger plugin provides several other interfaces for user usage, which are defined in the "Jaeger API" file.
Customize span content
You can retrieve the current Span from the ServerContext using the ::trpc::jaeger::GetSpan
interface:
using JaegerTracingSpanPtr = std::shared_ptr<::opentracing::Span>;
/// @brief Gets the span.
/// @param context server context
/// @return Return the span saved in the context. Note that nullptr will be returned when there is no valid span in the
/// context.
JaegerTracingSpanPtr GetSpan(const ServerContextPtr& context);
After obtaining the Span, you can use the native OpenTracing API to setup the span. For example:
::trpc::jaeger::JaegerTracingSpanPtr span = ::trpc::jaeger::GetSpan(context);
if (span) {
span->SetTag("id", "1");
span->Log({{"message1", "this is log content 0"}, {"message2", "this is log content 2"}});
}
Notice
- In the proxy mode, it is necessary to invoke the framework's
MakeClientContext
interface to construct theClientContext
based on theServerContext
. Otherwise, the call relationship between the server and client will be lost, and a complete call chain cannot be formed.