Trace 구성¶
Trace 초기화 구성¶
| 메서드 이름 | 유형 | 필수 | 의미 |
|---|---|---|---|
| setTraceSamplingRate | Float | 아니요 | 샘플링 비율(%), 범위 [0,100], 기본값 100입니다. 소수를 지원하며 예를 들어 0.1은 0.1%를 의미합니다. 0은 수집하지 않음, 100은 전체 수집을 의미합니다. 새 필드를 명시적으로 설정하면 설정 순서와 관계없이 기존 필드보다 우선합니다. ft-sdk >= 1.7.6에서 지원됩니다. |
| setSamplingRate | Float | 아니요 | ft-sdk 1.7.6부터 더 이상 사용되지 않으며 호환성을 위해 유지됩니다. 샘플링 비율을 설정합니다. 범위는 [0,1]이며 0은 수집하지 않음, 1은 전체 수집을 의미하고 기본값은 1입니다. |
| setTraceType | TraceType | 아니요 | 분산 추적 유형을 설정합니다. 기본값은 DDTrace이며 현재 Zipkin, Jaeger, DDTrace, Skywalking (8.0+), TraceParent (W3C)를 지원합니다. OpenTelemetry를 연동할 때 해당 Trace 유형을 선택하는 경우 지원 유형 및 agent 관련 구성을 확인하세요. |
| setEnableLinkRUMData | Boolean | 아니요 | RUM 데이터와 연결할지 여부를 설정합니다. 기본값은 false입니다. |
| setEnableAutoTrace | Boolean | 아니요 | 자동 HTTP Trace 활성화 여부를 설정합니다. 기본값은 false입니다. 자동 계측은 ft-plugin에 의존하며 OkHttp를 지원합니다. ft-sdk >= 1.7.6-alpha03에서 ft-plugin >= 1.3.9-alpha01을 함께 사용하고 URLConnection Resource 수집을 활성화하면 HttpURLConnection / HttpsURLConnection도 지원합니다. 자세한 내용은 URLConnection Trace를 참조하세요. |
| setOkHttpTraceHeaderHandler | Callback | 아니요 | ASM으로 전역 FTTraceInterceptor.HeaderHandler를 설정합니다. 기본적으로 설정되지 않으며 ft-sdk 1.6.8 이상에서 지원됩니다. ft-sdk 1.6.17부터 getTraceContext(Request) 재정의를 우선 지원하며 Header, traceId, spanId를 한 번에 반환할 수 있습니다. 예제는 Trace 사용자 지정을 참조하세요. |
HttpURLConnection / HttpsURLConnection Trace¶
ft-sdk >= 1.7.6-alpha03과 ft-plugin >= 1.3.9-alpha01을 함께 사용하는 경우 먼저 URLConnection 자동 수집에 따라 setEnableTraceUserResource(true)와 setEnableHttpURLConnectionResource(true)를 활성화한 다음 FTTraceConfig.setEnableAutoTrace(true)로 Trace Header 주입을 활성화합니다. Trace 스위치만 켜면 URLConnection 래핑이 활성화되지 않습니다. Resource URL 필터링도 해당 경로의 Trace 주입을 제외합니다.
전파 형식과 샘플링 결정은 FTTraceConfig의 Trace 유형 및 샘플링 비율 구성을 따릅니다. setEnableLinkRUMData(true)를 활성화하면 성공적으로 주입된 trace_id / span_id가 해당 Resource에 연결됩니다. 위의 Trace 초기화 예제는 RUM 구성과 함께 사용할 수 있습니다.
URLConnection은 선택한 전파 형식의 기존 Trace Header를 대체합니다. 요청이 이미 다른 SDK 또는 JS 레이어에서 분산 추적 정보를 주입한 경우 중복으로 활성화하지 마십시오. Resource의 Trace 정보가 서버에서 수신한 Header와 일치하지 않을 수 있습니다. setOkHttpTraceHeaderHandler는 OkHttp에만 적용되며 URLConnection의 Trace Header를 사용자 지정하는 데 사용되지 않습니다.
Tracer 네트워크 분산 추적¶
FTTraceConfig 구성에서 enableAutoTrace를 활성화하여 트레이스 데이터를 자동으로 추가하거나, FTTraceManager를 직접 사용하여 HTTP 요청에 Propagation Header를 추가할 수 있습니다. 예는 다음과 같습니다.
String url = "https://request.url";
String uuid = "uuid";
// 분산 추적 헤더 매개변수 가져오기
Map<String, String> headers = FTTraceManager.get().getTraceHeader(uuid, url);
OkHttpClient client = new OkHttpClient.Builder().addInterceptor(chain -> {
Request original = chain.request();
Request.Builder requestBuilder = original.newBuilder();
// 요청에 분산 추적 헤더 매개변수 추가
for (String key : headers.keySet()) {
requestBuilder.header(key, headers.get(key));
}
Request request = requestBuilder.build();
Response response = chain.proceed(request);
if (response != null) {
Map<String, String> requestHeaderMap = new HashMap<>();
Map<String, String> responseHeaderMap = new HashMap<>();
for (Pair<String, String> header : response.request().headers()) {
requestHeaderMap.put(header.first, header.second);
}
for (Pair<String, String> header : response.headers()) {
responseHeaderMap.put(header.first, header.second);
}
}
return response;
}).build();
Request.Builder builder = new Request.Builder().url(url).method(RequestMethod.GET.name(), null);
client.newCall(builder.build()).execute();
val url = "https://request.url"
val uuid = "uuid"
// 분산 추적 헤더 매개변수 가져오기
val headers = FTTraceManager.get().getTraceHeader(uuid, url)
val client: OkHttpClient = OkHttpClient.Builder().addInterceptor { chain ->
val original = chain.request()
val requestBuilder = original.newBuilder()
// 요청에 분산 추적 헤더 매개변수 추가
for (key in headers.keys) {
requestBuilder.header(key!!, headers[key]!!)
}
val request = requestBuilder.build()
val response = chain.proceed(request)
if (response != null) {
val requestHeaderMap = HashMap<String, String>()
val responseHeaderMap = HashMap<String, String>()
request.headers.forEach {
requestHeaderMap[it.first] = it.second
}
response.headers.forEach {
responseHeaderMap[it.first] = it.second
}
}
response
}.build()
val builder: Request.Builder = Request.Builder().url(url).method(RequestMethod.GET.name, null)
client.newCall(builder.build()).execute()
OkHttp Interceptor로 Resource 및 TraceHeader 사용자 지정¶
Resource¶
FTRUMConfig.setEnableTraceUserResource(true) 또는 FTRUMConfig.setOkHttpResourceContentHandler(...)를 활성화하면 OkHttp에서 사용자 지정 Interceptor가 우선 로드됩니다.
new OkHttpClient.Builder()
.addInterceptor(new FTTraceInterceptor())
.addInterceptor(new FTResourceInterceptor(new FTResourceInterceptor.ContentHandlerHelper() {
@Override
public void onRequest(Request request, HashMap<String, Object> extraData) {
String contentType = request.header("Content-Type");
extraData.put("df_request_header", request.headers().toString());
if ("application/json".equals(contentType) ||
"application/x-www-form-urlencoded".equals(contentType) ||
"application/xml".equals(contentType)) {
extraData.put("df_request_body", request.body());
}
}
@Override
public void onResponse(Response response, HashMap<String, Object> extraData) throws IOException {
String contentType = response.header("Content-Type");
extraData.put("df_response_header", response.headers().toString());
if ("application/json".equals(contentType) ||
"application/xml".equals(contentType)) {
// 일부 body를 복사해 읽어 대용량 데이터 처리 소모를 방지합니다
ResponseBody body = response.peekBody(33554432);
extraData.put("df_response_body", body.string());
}
}
@Override
public void onException(Exception e, HashMap<String, Object> extraData) {
}
}))
.eventListenerFactory(new FTResourceEventListener.FTFactory())
.build();
OkHttpClient.Builder()
.addInterceptor(FTTraceInterceptor())
.addInterceptor(FTResourceInterceptor(object : FTResourceInterceptor.ContentHandlerHelper {
override fun onRequest(request: Request, extraData: HashMap<String, Any>) {
val contentType = request.header("Content-Type")
extraData["df_request_header"] = request.headers().toString()
if ("application/json" == contentType ||
"application/x-www-form-urlencoded" == contentType ||
"application/xml" == contentType) {
extraData["df_request_body"] = request.body()
}
}
override fun onResponse(response: Response, extraData: HashMap<String, Any>) {
val contentType = response.header("Content-Type")
extraData["df_response_header"] = response.headers().toString()
if ("application/json" == contentType ||
"application/xml" == contentType) {
// 일부 응답 본문을 복사하여 대용량 데이터 소모를 방지합니다
val body = response.peekBody(33554432)
extraData["df_response_body"] = body.string()
}
}
override fun onException(e: Exception, extraData: HashMap<String, Any>) {
// 예외 상황 처리
}
}))
.eventListenerFactory(FTResourceEventListener.FTFactory())
.build()
TraceHeader¶
FTTraceConfig.setEnableAutoTrace(true) 또는 FTTraceConfig.setOkHttpTraceHeaderHandler(...)를 활성화하면 OkHttp에서 사용자 지정 Interceptor가 우선 로드됩니다. 아래는 W3C Trace Context를 예로 듭니다.
ft-sdk < 1.4.1에서는
FTTraceConfig.setEnableAutoTrace(false)로 비활성화해야 합니다. ft-sdk > 1.6.7에서 사용자 지정 Trace Header와 RUM 데이터 연결을 지원합니다. ft-sdk >= 1.6.17에서getTraceContext(Request)가 새로 추가되어 요청 Header,traceId,spanId를 한 번에 반환할 수 있습니다. 이 방식을 우선 사용하는 것을 권장합니다.
권장 방식: getTraceContext(Request) 사용¶
new OkHttpClient.Builder()
.addInterceptor(new FTTraceInterceptor(new FTTraceInterceptor.HeaderHandler() {
@Override
public TraceContext getTraceContext(Request request) {
HashMap<String, String> headers = FTTraceManager.get()
.getTraceHeader(request.url().toString());
return TraceContext.Simple.fromTraceType(headers);
}
}))
.addInterceptor(new FTResourceInterceptor())
.eventListenerFactory(new FTResourceEventListener.FTFactory())
.build();
OkHttpClient.Builder()
.addInterceptor(
FTTraceInterceptor(object : FTTraceInterceptor.HeaderHandler() {
override fun getTraceContext(request: Request): TraceContext? {
val headers = FTTraceManager.get().getTraceHeader(request.url.toString())
return TraceContext.Simple.fromTraceType(headers)
}
})
)
.addInterceptor(FTResourceInterceptor())
.eventListenerFactory(FTResourceEventListener.FTFactory())
.build()
기존 방식 호환: getTraceHeader / getTraceID / getSpanID 각각 구현¶
new OkHttpClient.Builder()
.addInterceptor(new FTTraceInterceptor(new FTTraceInterceptor.HeaderHandler() {
private String[] splits;
@Override
public HashMap<String, String> getTraceHeader(Request request) {
HashMap<String, String> map = new HashMap<>();
String headerString = FTTraceManager.get()
.getTraceHeader(request.url().toString())
// header에서 propagation header를 가져옵니다
.get(FTTraceHandler.W3C_TRACEPARENT_KEY);
splits = headerString.split("-");
map.put(W3C_TRACEPARENT_KEY, headerString);
return map;
}
@Override
public String getSpanID() {
if (splits != null) {
return splits[2];
}
return null;
}
@Override
public String getTraceID() {
if (splits != null) {
return splits[1];
}
return null;
}
}))
.addInterceptor(new FTResourceInterceptor())
.eventListenerFactory(new FTResourceEventListener.FTFactory())
.build();
OkHttpClient.Builder()
.addInterceptor(
FTTraceInterceptor(object : FTTraceInterceptor.HeaderHandler {
private var splits: Array<String>? = null
override fun getTraceHeader(request: Request): HashMap<String, String> {
val map = HashMap<String, String>()
val headerString = FTTraceManager.get()
.getTraceHeader(request.url.toString())
// header에서 propagation header를 가져옵니다
.get(FTTraceHandler.W3C_TRACEPARENT_KEY)
splits = headerString?.split("-")?.toTypedArray()
headerString?.let {
map[W3C_TRACEPARENT_KEY] = it
}
return map
}
override fun getSpanID(): String? {
return splits?.getOrNull(2)
}
override fun getTraceID(): String? {
return splits?.getOrNull(1)
}
})
)
.addInterceptor(FTResourceInterceptor())
.eventListenerFactory(FTResourceEventListener.FTFactory())
.build()
OkHttp에 ResourceID 추가¶
OkHttp Request에 uuid를 추가합니다. 동일한 요청이 높은 빈도로 동시에 발생하는 시나리오라면 활성화를 권장합니다. ft-plugin 1.3.5 이상, ft-sdk 1.6.10 이상에서 FTSDKConfig.setEnableOkhttpRequestTag(true)를 활성화하면 Request에 ResourceID를 자동으로 추가할 수 있습니다.