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 Session のサンプリングレートを置き換えるものではありません。
対応する伝搬形式¶
| 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 を使用します。アダプターはヘッダーを生成し、リクエストを完了して、同じ ID を RUM Resource に書き込みます：
guance::rum::WinHttpResource resource(
rum,
request,
"https://api.example.com/items",
"GET");
if (resource.send()) {
resource.receive();
}
非同期 WinHTTP では、WinHttpRequestMode::asynchronous を使用し、オブジェクトを終了コールバックまで生存させ、ヘッダーが利用可能になったら complete_from_response() を呼び出す必要があります。
カスタム Trace コンテキスト¶
ContextProvider は、カスタムヘッダーと関連する識別子を返すことができます：
ContextProvider = request => new TraceContext(
new Dictionary<string, string>
{
["traceparent"] = CreateTraceParent()
},
traceId: currentTraceId,
spanId: currentSpanId)
Provider が null または無効なヘッダーを返した場合、SDK は今回の Trace をスキップし、ホストのリクエストを中断しません。
WinHTTP 以外のネットワークライブラリは、コンテキストを生成してヘッダーを自身で書き込むことができます：
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;
// 現在のネットワークライブラリを使用してヘッダーを書き込みます。
}
}
Resource を独自に収集する場合は、context.trace_id と context.span_id を guance_rum_stop_resource_ext() に渡します。関連付けは、context.link_rum_data != 0 の場合にのみ行ってください。
セキュリティ境界¶
Trace Header の送信先アドレスを制限する
ターゲットフィルタリングを設定していない場合、自動 Trace 収集の境界に入るすべての絶対 URL が Trace Header を受け取る可能性があります。本番環境では、プロトコル、ホスト名、ポートに基づいて明示的なホワイトリストを設定し、Trace コンテキストを第三者に送信しないようにしてください。
Native 設定は文字列をコピーしますが、コールバックと user_data は保持されます。これらは、再設定または guance_sdk_shutdown() まで有効に保つ必要があります。コールバックは複数のリクエストスレッドから並行して呼び出される可能性があるため、C++ の例外が C ABI を越えないようにしてください。