Home

Awesome

中文

LICENSE Releases Build Status Coverage

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

  1. Import repository

    In the project's WORKSPACE file, import the cpp-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.

  2. 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 optionsTypeValueDescription
enable_loggerboolDefault value is false.Controls whether to print Span information.
disabledboolDefault value is false.Controls whether to disable tracing data collection and reporting.
samplerMappingThe default value for "type" is "const" and the default value for "param" is 1, indicating full sampling.Sets sampling strategy.
reporter:localAgentHostPortstringDefault 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:

KeyTypeValue
span.kindTag"client"
peer.serviceTagThe name of the callee service.
peer.hostnameTagThe name of the callee container.
peer.ipv4/peer.ipv6TagThe IP address of the callee service.
peer.portTagThe port of the callee service.
_trace_ext.response.sizeTagThe size of the response packet in bytes.
_trace_ext.namespaceTagThe namespace.
_trace_ext.envnameTagThe env.
_trace_ext.retTagThe error code of the invocation.
errorTagtrue (It is only set when error occurs during the invocation)
eventLog"error" (It is only set when error occurs during the invocation)
messageLogThe 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:

KeyTypeValue
span.kindTag"server"
_trace_ext.request.sizeTagThe size of the request packet in bytes.
_trace_ext.namespaceTagThe namespace.
_trace_ext.envnameTagThe env.
_trace_ext.retTagThe error code of the invocation.
errorTagtrue (It is only set when error occurs during the invocation)
eventLog"error" (It is only set when error occurs during the invocation)
messageLogThe 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.

  1. 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;
      }
    };
    
  2. 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