本文介绍对于Java和Node.js应用如何将TraceId自动写入HTTP Response Header。
Java应用
默认情况下,TraceId只会在保存在HTTP Requst Header中,如果您需要在HTTP Response Header中设置 TraceId,可参考本文使用OpenTelemetry Java Agent Extension(扩展)以增强OpenTelemetry Java Agent的功能。
本文提供了两种方法:
方法一:开箱即用。直接使用可观测链路 OpenTelemetry 版已打包好的OpenTelemetry Java Agent扩展,简单快捷。
方法二:自行实现OpenTelemetry Java Agent扩展。如果可观测链路 OpenTelemetry 版的扩展不满足您的需求,可以参考此方法实现OpenTelemetry Java Agent扩展并打成JAR包。
方法一:开箱即用
扩展下载地址:ot-java-agent-extension-1.28.0.jar。
可观测链路 OpenTelemetry 版已经实现了简单的OpenTelemetry Java Agent扩展,在HTTP Response Header中自动添加TraceId
和SpanId
字段,只需要在启动参数中加载JAR包即可。
使用方法
在原有启动参数上添加otel.javaagent.extensions
参数:-Dotel.javaagent.extensions=/path/to/opentelemetry-java-agent-extension.jar
。
完整的启动命令示例:
java -javaagent:path/to/opentelemetry-javaagent.jar \
-Dotel.javaagent.extensions=path/to/opentelemetry-java-agent-extension.jar \
-Dotel.exporter.otlp.headers=Authentication=<token> \
-Dotel.exporter.otlp.endpoint=<endpoint> \
-Dotel.metrics.exporter=none \
-jar your-app.jar
方法二:自行实现OpenTelemetry Java Agent扩展
前提条件
已使用OpenTelemetry Java Agent。
OpenTelemetry Java Agent版本为1.24.0或以上。
编写OpenTelemetry Java Agent扩展
新建一个项目。
在pom.xml中添加依赖。
Opentelemetry-javaagent的版本需要与您使用的OpenTelemetry Java Agent版本一致。
<dependencies> <dependency> <groupId>com.google.auto.service</groupId> <artifactId>auto-service</artifactId> <version>1.1.1</version> </dependency> <dependency> <groupId>io.opentelemetry.javaagent</groupId> <artifactId>opentelemetry-javaagent</artifactId> <version>1.28.0</version> <scope>compile</scope> </dependency> </dependencies>
新建AgentHttpResponseCustomizer类,实现HttpServerResponseCustomizer接口。
package org.example; import com.google.auto.service.AutoService; import io.opentelemetry.javaagent.shaded.io.opentelemetry.api.trace.Span; import io.opentelemetry.javaagent.shaded.io.opentelemetry.api.trace.SpanContext; import io.opentelemetry.javaagent.shaded.io.opentelemetry.context.Context; import io.opentelemetry.javaagent.bootstrap.http.HttpServerResponseCustomizer; import io.opentelemetry.javaagent.bootstrap.http.HttpServerResponseMutator; @AutoService(HttpServerResponseCustomizer.class) public class AgentHttpResponseCustomizer implements HttpServerResponseCustomizer { @Override public <RESPONSE> void customize(Context context, RESPONSE response, HttpServerResponseMutator<RESPONSE> responseMutator) { SpanContext spanContext = Span.fromContext(context).getSpanContext(); String traceId = spanContext.getTraceId(); String spanId = spanContext.getSpanId(); // 在 HTTP Response Header中设置 traceId 和 spanId, Header 字段名可以自定义 responseMutator.appendHeader(response, "TraceId", traceId); responseMutator.appendHeader(response, "SpanId", spanId); } }
构建OpenTelemetry Java Agent扩展。
将程序打包成JAR包,构建后存储在target目录下。
mvn clean package
启动应用时加载OpenTelemetry Java Agent扩展。
在原有启动参数上添加 otel.javaagent.extensions 参数:
-Dotel.javaagent.extensions=/path/to/opentelemetry-java-agent-extension.jar
。完整的启动命令示例:
java -javaagent:path/to/opentelemetry-javaagent.jar \ -Dotel.javaagent.extensions=path/to/opentelemetry-java-agent-extension.jar \ -Dotel.exporter.otlp.headers=Authentication=<token> \ -Dotel.exporter.otlp.endpoint=<endpoint> \ -Dotel.metrics.exporter=none -jar yourapp.jar
Node.js应用
(可选)下载示例Demo:node.js-demo。
如果您的Node.js应用已经使用OpenTelemetry接入,则无需下载示例Demo,直接参考下一步修改Node.js应用中的代码。
修改Demo中HttpInstrumentation的创建代码。
创建HttpInstrumentation时可以设置HttpInstrumentationConfig参数,参数包括responseHook,该参数允许用户传入一个自定义方法的方法,在响应被处理之前添加自定义内容,例如在HTTP Header中添加TraceId。
... // 要被替换的内容 // registerInstrumentations({ // tracerProvider: provider, // instrumentations: [new HttpInstrumentation(), ExpressInstrumentation], // }); const httpInstrumentation = new HttpInstrumentation({ // 添加一个自定义的responseHook responseHook: (span, response) => { // 从当前上下文中获取traceId, spanId const traceId = span.spanContext().traceId; const spanId = span.spanContext().spanId; // 将traceId, spanId添加到响应标头中 response.setHeader('TraceId', traceId); response.setHeader('SpanId', spanId); // 返回响应对象 return response; }, }); registerInstrumentations({ tracerProvider: provider, instrumentations: [httpInstrumentation, ExpressInstrumentation], }); ...