跳转至

ddtrace 常见参数用法

作者： 刘锐

前置条件

java -javaagent:D:/ddtrace/dd-java-agent-guance.jar \
-Ddd.service.name=ddtrace-server \
-Ddd.agent.port=9529 \
-jar springboot-ddtrace-server.jar

参数使用

开启 query 参数

开启 query 参数，可以更直观方便地让用户看到当前请求携带了哪些参数，更直观地还原客户真实的操作流程。默认为 false，表示为默认不开启。

但 query 开启参数只能采集到 url 上的参数，request Body 里面的参数目前尚不支持。

-Ddd.http.server.tag.query-string=TRUE

image

配置远程采集链接

dd.agent.host 默认值是localhost，所以默认推送的是本地的 DataKit。

如果想推送远程 DataKit ，则需要配置 dd.agent.host。

-Ddd.agent.host=192.168.91.11

两种添加 Tag 方式

ddtrace 提供两种添加 tag 方式，效果一样。但还是推荐使用 dd.tags 方式

1 dd.trace.span.tags

将 projectName:observable-demo 添加到每个 span 的示例：

-Ddd.trace.span.tags=projectName:observable-demo

image.png

2. dd.tags

-Ddd.tags=user_name:joy

image.png

以上两种方式都能生成 tag，效果一样，都会在meta里面展示数据。

如果确实想要把 dd.tags标记的 tag 作为观测云的 标签 ，则需要在 ddtrace.conf 配置 customer_tags

    [[inputs.ddtrace]]
      endpoints = ["/v0.3/traces", "/v0.4/traces", "/v0.5/traces"]
      customer_tags = ["projectName","user_name"]

效果如图：

image.png

显示数据库实例名称

显示数据库的名称，默认显示数据库的类型，如需要显示数据库名称，将值设置成TRUE

-Ddd.trace.db.client.split-by-instance=TRUE

以上 demo 并没有加载数据库，所以想要达到这个效果，可以选择一个引入数据库的应用添加参数 

dd.trace.db.client.split-by-instance=TRUE

效果如图：

image

类或方法注入 Trace

ddtrace 支持给方法注入 Trace ，默认情况下，ddtrace 会对所有的 API 接口动态注入 Trace。

如果想对非 API 类（方法）——— 一些重要的类和方法重点标记，可以通过 dd.trace.methods参数配置。

  • Environment Variable: DD_TRACE_METHODS
  • Default: null
  • Example: package.ClassName[method1,method2,...];AnonymousClass$1[call];package.ClassName[*]
    List of class/interface and methods to trace. Similar to adding @Trace, but without changing code.
  • Note: The wildcard method support ([*]) does not accommodate constructors, getters, setters, synthetic, toString, equals, hashcode, or finalizer method calls

如对 com.zy.observable.ddtrace.service.TestService 类的getDemo方法需要添加 Trace。

-Ddd.trace.methods="com.zy.observable.ddtrace.service.TestService[getDemo]"

部分代码所示：

    @Autowired
    private TestService testService;

    @GetMapping("/gateway")
    @ResponseBody
    public String gateway(String tag) {
        String userId = "user-" + System.currentTimeMillis();
        MDC.put(ConstantsUtils.MDC_USER_ID, userId);
        logger.info("this is tag");
        sleep();
        testService.getDemo();
        httpTemplate.getForEntity(apiUrl + "/resource", String.class).getBody();
        httpTemplate.getForEntity(apiUrl + "/auth", String.class).getBody();
        if (client) {
            httpTemplate.getForEntity("http://"+extraHost+":8081/client", String.class).getBody();
        }
        return httpTemplate.getForEntity(apiUrl + "/billing?tag=" + tag, String.class).getBody();
    }

未添加dd.trace.methods参数，上报 11 个 span ，效果如下：

image.png

通过 header 自定义业务 tag

主要是通过 header 方式，以一种非侵入式方式将业务 tag 注入到 trace 中，能够跟踪对应业务的执行情况。以 Key:value 方式进行配置，key 为原始 header 的 paramName ，value 为 key 的 rename，其中 key 可以省略。

-Ddd.trace.header.tags=user-id:userid,order-id:orderid,orderno

请求

image.png

链路效果：

image.png

Baggage，让 tag 无限透传

环境变量: DD_TRACE_HEADER_BAGGAGE

默认值: null

样例: CASE-insensitive-Header:my-baggage-name,User-ID:userId,My-Header-And-Baggage-Name

如： 

-Ddd.trace.header.baggage=userId:user_id

-Ddd.trace.header.tags 不会实现透传功能，Baggage 可以让 header 的 tag 无限透传下去。

链路效果：

image.png

开启 debug 模式

开启 debug 模式后，系统输出 ddtrace 相关日志，有利于排查 ddtrace 相关问题。

-Ddd.trace.debug=true

默认情况下 debug 日志会输出到 stdout，如果想要输出到文件，则需要配合以下参数

-Ddatadog.slf4j.simpleLogger.logFile=<NEW_LOG_FILE_PATH>
注意

-Ddd.trace.debug=true 是用来开启 ddtrace 的 debug 日志，而不是开启应用的 debug 日志。

traceId 开启 128 bit

traceId 默认是 64 bit（long型），为了能够更好的与 opentelemetry （traceId 为 128bit ）兼容，可以手动开启 128 bit。 

-Ddd.trace.128.bit.traceid.generation.enabled=true

输出 trace 信息

如果需要做一些研发相关的工作，了解 trace 上报数据结构是有必要的，默认情况下，trace 信息会通过DDAgentWriter上报到远端可观测平台，如果想在控制台输出对应的信息，可以通过配置如下参数：

-Ddd.writer.type=LoggingWriter

也可以配置多个 

-Ddd.writer.type=LoggingWriter,DDAgentWriter

开启服务名替换中间件名称

默认情况下，链路信息会按照中间件名称进行分组展示，导致如果应用只有中间件产生链路信息，则无法向上追溯到当前中间件所处的应用，可以通过调整参数将全局 tag service name 作为中间件的 service。通过以下参数进行配置：

启动参数方式注入

-Ddd.trace.span.attribute.schema=v1
可通过环境变量方式注入

export DD_TRACE_SPAN_ATTRIBUTE_SCHEMA=v1

以上两种方式二选一

最终效果，不再展示中间件服务名称【即应用服务名称替换了中间件的名称】，span 其他 tag 和数据不受影响。

替换前效果

image.png

替换后效果

image.png

传播器配置

ddtrace支持以下几种传播器，传播器类型不区分大小写。

  • Datadog ：默认传播器
  • B3 ：B3 传播是标头“b3”和以“x-b3-”开头的标头的规范。这些标头用于跨服务边界的跟踪上下文传播。B3有两种方式，分别是
    • B3SINGLE（B3_SINGLE_HEADER），对应 header 的 key 为 b3
    • B3（B3MULTI），对应 header 的 key 为 x-b3-
  • haystack
  • tracecontext:默认传播器
  • xray ： AWS 传播器
-Ddd.trace.propagation.style=B3SINGLE

或者配置环境变量

DD_TRACE_PROPAGATION_STYLE=B3SINGLE

ddtrace 1.9.0 之前使用

-Ddd.propagation.style.extract=Datadog
-Ddd.propagation.style.inject=Datadog
或 
-Ddd.propagation.style=Datadog

注意： 可以配置多个传播器，多个传播器之间使用,分割，传播器类型不区分大小写。

关于传播器更多资料可以参考链路传播（Propagate）机制及使用场景

Response 返回 TraceId 📢

此项不需要额外配置，在请求响应完成后， 追加 key 为 guance_trace_id 的 header。

Img

✔ version >= 1.25.1-guance

Header Tags 📢

把请求和响应中所有的 header 添加到链路 tag 上，请求 header 的 tag 名称为request_header，响应结果 header 的 tag 名称为 response_header。需要通过以下两种方式进行开启，二选一：

  • 启动命令

-Ddd.trace.headers.enabled：默认值为 false，即不开启。

  • 环境变量

DD_TRACE_HEADERS_ENABLED

Img

👉 目前支持 Servlet3 和 Netty4

✔ version >= 1.25.2-guance

Request body Tag 📢

把请求体添加到链路 tag 上，目前只支持 POST 请求，且 Context-Type 为 application/json 或 application/json;charset=UTF-8 - 启动命令

-Ddd.trace.request.body.enabled：默认值为 false，即不开启。

  • 环境变量

DD_TRACE_REQUEST_BODY_ENABLED

如执行以下请求

curl -X POST -H 'Content-Type: application/json' -d '{"username":"joy","age":18}' http://localhost:8090/jsonStr

Img

👉 目前支持 Servlet3

✔ version >= 1.25.2-guance

参考文档

demo 源码地址

ddtrace 启动参数

ddtrace issue

ddtrace 扩展功能📢

文档评价

文档内容是否对您有帮助？ ×