Trace 구성¶
Windows SDK의 Trace는 HTTP 요청에 분산 추적 헤더를 삽입하고, 생성된 trace_id, span_id를 해당 RUM Resource에 연결하는 데 사용됩니다. SDK는 독립적인 APM Span을 생성하거나 업로드하지 않습니다.
Trace 초기화 구성¶
GuanceSdk.Init(new GuanceConfig
{
DatawayUrl = "https://openway.guance.com",
ClientToken = "<client-token>",
RumAppId = "<rum-app-id>",
Trace = new TraceConfig
{
EnableAutoTrace = true,
EnableLinkRumData = true,
SampleRate = 1.0,
TraceType = TraceType.TraceParent,
ShouldTrace = uri =>
uri.Scheme == Uri.UriSchemeHttps &&
uri.Host == "api.example.com"
}
});
#include <string>
static int should_trace(const char* url, const char*, void*)
{
const std::string value = url == nullptr ? "" : url;
return value == "https://api.example.com" ||
value.rfind("https://api.example.com/", 0) == 0;
}
guance_trace_config trace;
guance_trace_config_init(&trace);
trace.enable_auto_trace = 1;
trace.enable_link_rum_data = 1;
trace.sample_rate = 1.0;
trace.trace_type = GUANCE_TRACE_TRACEPARENT;
trace.should_trace = should_trace;
if (!guance_trace_configure(rum, &trace)) {
// 구성이 잘못되어 Trace가 활성화되지 않았습니다.
}
구성 매개변수¶
| 의미 | .NET / C# | Native C/C++ | 기본값 |
|---|---|---|---|
| Trace 컨텍스트 자동 생성 | EnableAutoTrace |
enable_auto_trace |
false / 0 |
| RUM Resource 연결 | EnableLinkRumData |
enable_link_rum_data |
false / 0 |
| 전파 샘플링 비율 | SampleRate |
sample_rate |
1.0 |
| 전파 형식 | TraceType |
trace_type |
DDTrace |
| 대상 필터링 | ShouldTrace |
should_trace |
비어 있음 |
| 사용자 정의 컨텍스트 | ContextProvider |
context_provider |
비어 있음 |
| 콜백 컨텍스트 | 클로저 | user_data |
비어 있음 |
Trace 샘플링 비율은 전파 프로토콜의 샘플링된(sampled) 표시만 제어하며, RUM 세션 샘플링 비율을 대체하지 않습니다.
지원되는 전파 형식¶
| C# | Native C/C++ | Header |
|---|---|---|
TraceType.DdTrace |
GUANCE_TRACE_DDTRACE |
x-datadog-* |
TraceType.ZipkinMultiHeader |
GUANCE_TRACE_ZIPKIN_MULTI_HEADER |
X-B3-TraceId, X-B3-SpanId, X-B3-Sampled |
TraceType.ZipkinSingleHeader |
GUANCE_TRACE_ZIPKIN_SINGLE_HEADER |
b3 |
TraceType.TraceParent |
GUANCE_TRACE_TRACEPARENT |
traceparent |
TraceType.SkyWalking |
GUANCE_TRACE_SKYWALKING |
sw8 |
TraceType.Jaeger |
GUANCE_TRACE_JAEGER |
uber-trace-id |
서버 또는 Agent는 선택한 전파 형식을 지원해야 합니다.
Tracer 네트워크 분산 추적¶
HttpClient 자동 수집을 활성화하면 SDK는 요청 전송 전에 Trace 구성을 적용합니다.
GuanceSdk.EnableAutomaticInstrumentation(new AutomaticInstrumentationOptions
{
EnableHttpClient = true
});
using var http = new HttpClient();
await http.GetAsync("https://api.example.com/items");
Handler를 명시적으로 제어해야 하는 경우 다음을 사용합니다.
C++ WinHTTP 애플리케이션은 guance_rum_winhttp.hpp를 사용합니다. 어댑터는 Header를 생성하고, 요청을 완료하며, 동일한 ID를 RUM Resource에 기록합니다.
guance::rum::WinHttpResource resource(
rum,
request,
"https://api.example.com/items",
"GET");
if (resource.send()) {
resource.receive();
}
비동기 WinHTTP는 WinHttpRequestMode::asynchronous를 사용해야 하며, 종료 콜백까지 객체를 유지하고 Header를 사용할 수 있게 된 후 complete_from_response()를 호출해야 합니다.
사용자 정의 Trace 컨텍스트¶
ContextProvider는 사용자 정의 Header와 연결 식별자를 반환할 수 있습니다.
ContextProvider = request => new TraceContext(
new Dictionary<string, string>
{
["traceparent"] = CreateTraceParent()
},
traceId: currentTraceId,
spanId: currentSpanId)
Provider가 null 또는 유효하지 않은 Header를 반환하면 SDK는 이번 Trace를 건너뛰고 호스트 요청을 중단하지 않습니다.
WinHTTP가 아닌 네트워크 라이브러리는 컨텍스트를 생성하고 직접 Header에 쓸 수 있습니다.
guance_trace_context context;
guance_trace_context_init(&context);
if (guance_trace_create_context(
rum,
"https://api.example.com/items",
"GET",
&context)) {
for (uint32_t index = 0; index < context.header_count; ++index) {
const char* name = context.headers[index].name;
const char* value = context.headers[index].value;
// 현재 네트워크 라이브러리를 사용하여 Header를 작성합니다.
}
}
Resource를 직접 수집하는 경우 context.trace_id와 context.span_id를 guance_rum_stop_resource_ext()에 전달합니다. context.link_rum_data != 0인 경우에만 연결해야 합니다.
보안 경계¶
Trace Header 대상 주소 제한
대상 필터링이 구성되지 않은 경우, 자동 Trace 수집 경계 내에 들어오는 모든 절대 URL에 Trace Header가 전송될 수 있습니다. 프로덕션 환경에서는 프로토콜, 호스트 이름 및 포트를 기준으로 명확한 화이트리스트를 설정하여 링크 컨텍스트가 타사에 전송되지 않도록 해야 합니다.
Native 구성은 문자열을 복사하지만 콜백과 user_data는 그대로 유지됩니다. 이들은 재구성되거나 guance_sdk_shutdown()이 호출될 때까지 유효해야 합니다. 콜백은 여러 요청 스레드에서 동시에 호출될 수 있으므로 C++ 예외가 C ABI 경계를 넘지 않도록 해야 합니다.