アプリケーション トレーシング スキル

概要

Dynatrace の分散トレースはスパンで構成されており、スパンは作業単位を表す基本的な要素です。Grail の Traces では、すべてのスパンに DQL でアクセス可能で、すべての属性の全文検索ができます。このスキルは、トレース の基礎、一般的な分析パターン、スパンタイプ固有のクエリをカバーします。

---

ユースケース

1. 低速リクエストの調査

• 目的: レイテンシ閾値を超えるリクエストを見つけて診断する
• トリガー: 「低速リクエスト」、「高レイテンシ」、「p99 レスポンスタイム」、「5秒以上のトレースを検索」
• 完了: 期間、エンドポイント、サービス、トレース ID を含む低速トレースのリスト

2. リクエスト失敗の分析

• 目的: 失敗したリクエスト、失敗理由、例外パターンを特定する
• トリガー: 「失敗したスパン」、「HTTP 500 エラー」、「例外分析」、「サービス別失敗率」
• 完了: 失敗理由（HTTP コード、例外、gRPC ステータス）別の内訳と、例示的なトレース

3. サービス依存関係のマッピング

• 目的: サービス間通信パターンと外部 API 呼び出しを理解する
• トリガー: 「サービス依存関係」、「X がどのサービスを呼び出すか」、「発信 HTTP 呼び出し」
• 完了: サービス間の呼び出し数、レイテンシ、エラー率を示す依存関係マップ

---

コア概念

トレースとスパンの理解

スパンは分散トレースの論理的な作業単位を表します:

• HTTP リクエスト、RPC 呼び出し、データベース操作
• メッセージングシステム相互作用
• 内部関数呼び出し
• カスタムインストルメンテーションポイント

スパンの種類:

• span.kind: server - サービスへの受信呼び出し
• span.kind: client - サービスからの発信呼び出し
• span.kind: consumer - サービスへのメッセージ受信呼び出し
• span.kind: producer - サービスからのメッセージ送信呼び出し
• span.kind: internal - サービス内の内部操作

ルートスパン: リクエストルートスパン (request.is_root_span == true) はサービスへの受信呼び出しを表します。エンドツーエンドのリクエスト性能を分析するために使用します。

キートレース属性

トレース分析に不可欠な属性:

属性	説明
trace.id	一意のトレース識別子
span.id	一意のスパン識別子
span.parent_id	親スパン ID（ルートスパンの場合は null）
request.is_root_span	ブール値、リクエストエントリーポイントの場合は真
request.is_failed	ブール値、リクエスト失敗の場合は真
duration	ナノ秒単位のスパン期間
span.timing.cpu	スパン全体の CPU 時間（安定）
span.timing.cpu_self	子スパンを除く CPU 時間（安定）
dt.smartscape.service	サービス Smartscape ノード ID
dt.service.name	サービス検出ルールから派生した Dynatrace サービス名。Smartscape サービスノード名と同じです。
endpoint.name	エンドポイント/ルート名

サービスコンテキスト

スパンは Smartscape ノード ID と検出されたサービス名 dt.service.name を介してサービスを参照します。これはすべてのスパンに存在します。

fetch spans
| summarize spans=count(), by: { dt.smartscape.service, dt.service.name }

ノード関数:

• getNodeName(dt.smartscape.service) - dt.smartscape.service.name フィールドを追加します（人間が読める形式のサービス名）
• getNodeField(dt.smartscape.service, "attribute_name") - 特定のノード属性にアクセス

📖 詳細情報: Entity Lookups を参照して、高度なエンティティセレクタ、インフラストラクチャ相関、ハードウェア分析を確認してください。

サンプリングと外挿

1 つのスパンは複数の実際の操作を表すことがあります:

• 集計: 1 つのスパンに複数の操作（aggregation.count）
• ATM（Adaptive Traffic Management）: エージェントによるヘッドベースのサンプリング
• ALR（Adaptive Load Reduction）: サーバー側のサンプリング
• 読み取りサンプリング: samplingRatio パラメータによるクエリ時のサンプリング

外挿する場合: 実際の操作数をカウントする場合は常に外挿します（スパン数ではなく）。多重度係数を使用します:

fetch spans
| fieldsAdd sampling.probability = (power(2, 56) - coalesce(sampling.threshold, 0)) * power(2, -56)
| fieldsAdd sampling.multiplicity = 1 / sampling.probability
| fieldsAdd multiplicity = coalesce(sampling.multiplicity, 1)
                         * coalesce(aggregation.count, 1)
                         * dt.system.sampling_ratio
| summarize operation_count = sum(multiplicity)

📖 詳細情報: Sampling and Extrapolation を参照して、詳細な式と例を確認してください。

一般的なクエリパターン

基本的なスパンアクセス

スパンを取得してタイプ別に探索:

fetch spans | limit 1

関数とタイプ別にスパンを探索:

fetch spans
| summarize count(), by: { span.kind, code.namespace, code.function }

リクエストルートフィルタリング

リクエストルートスパン（受信サービス呼び出し）をリストアップ:

fetch spans
| filter request.is_root_span == true
| fields trace.id, span.id, start_time, response_time = duration, endpoint.name
| limit 100

サービス性能サマリー

エラー率を含むサービス性能を分析:

fetch spans
| filter request.is_root_span == true
| summarize
    total_requests = count(),
    failed_requests = countIf(request.is_failed == true),
    avg_duration = avg(duration),
    p95_duration = percentile(duration, 95),
    by: {dt.service.name}
| fieldsAdd error_rate = (failed_requests * 100.0) / total_requests
| sort error_rate desc

トレース ID ルックアップ

特定のトレース内のすべてのスパンを検索:

fetch spans
| filter trace.id == toUid("abc123def456")
| fields span.name, duration, dt.service.name

パフォーマンス分析

レスポンスタイムパーセンタイル

エンドポイント別にパーセンタイルを計算:

fetch spans
| filter request.is_root_span == true
| summarize {
    requests=count(),
    avg_duration=avg(duration),
    p95=percentile(duration, 95),
    p99=percentile(duration, 99)
  }, by: { endpoint.name }
| sort p99 desc

💡 ベストプラクティス: パフォーマンス分析には、平均値よりもパーセンタイル（p95、p99）を使用します。

低速トレース検出

閾値を超えるリクエストを検索:

fetch spans, from:now() - 2h
| filter request.is_root_span == true
| filter duration > 5s
| fields trace.id, span.name, dt.service.name, duration
| sort duration desc
| limit 50

期間バケットと例示的スパン

fetch spans, from:now() - 24h
| filter http.route == "/api/v1/storage/findByISBN"
| summarize {
    spans=count(),
    trace=takeAny(record(start_time, trace.id))
  }, by: { bin(duration, 10ms) }
| fields `bin(duration, 10ms)`, spans, trace.id=trace[trace.id], start_time=trace[start_time]

パフォーマンスタイムシリーズ

レスポンスタイムをタイムシリーズとして抽出:

fetch spans, from:now() - 24h
| filter request.is_root_span == true
| makeTimeseries {
    requests=count(),
    avg_duration=avg(duration),
    p95=percentile(duration, 95),
    p99=percentile(duration, 99)
  }, by: { endpoint.name }

📖 詳細情報: Performance Analysis を参照して、高度なパターンとタイムシリーズ技術を確認してください。

失敗調査

失敗リクエストサマリー

サービス別に失敗をサマリー化:

fetch spans
| filter request.is_root_span == true
| summarize
    total = count(),
    failed = countIf(request.is_failed == true),
  by: { dt.service.name }
| fieldsAdd failure_rate = (failed * 100.0) / total
| sort failure_rate desc

失敗理由分析

失敗検出理由別に内訳:

fetch spans
| filter request.is_failed == true and isNotNull(dt.failure_detection.results)
| expand dt.failure_detection.results
| summarize count(), by: { dt.failure_detection.results[reason] }

失敗理由:

• http_code - HTTP レスポンスコードが失敗をトリガー
• grpc_code - gRPC ステータスコードが失敗をトリガー
• exception - 例外が失敗を引き起こした
• span_status - スパンステータスが失敗を示した
• custom_rule - カスタム失敗検出ルールがマッチ

HTTP コード失敗

HTTP ステータスコード別に失敗を検索:

fetch spans
| filter request.is_failed == true
| filter iAny(dt.failure_detection.results[][reason] == "http_code")
| summarize count(), by: { http.response.status_code, endpoint.name }
| sort `count()` desc

最近の失敗リクエスト

詳細を含む最近の失敗をリストアップ:

fetch spans
| filter request.is_root_span == true and request.is_failed == true
| fields
    start_time,
    trace.id,
    endpoint.name,
    http.response.status_code,
    duration
| sort start_time desc
| limit 100

📖 詳細情報: Failure Detection を参照して、例外分析とカスタムルール調査を確認してください。

サービス依存関係

サービス間分析

サービス通信パターンを分析:

fetch spans, from:now() - 1h
| filter isNotNull(server.address)
| fieldsAdd
    remote_side = server.address
| summarize
    call_count = count(),
    avg_duration = avg(duration),
    by: {dt.service.name, remote_side}
| sort call_count desc

発信 HTTP 呼び出し

外部 API 依存関係を特定:

fetch spans
| filter span.kind == "client" and isNotNull(http.request.method)
| summarize
    calls = count(),
    avg_latency = avg(duration),
    p99_latency = percentile(duration, 99),
  by: { dt.service.name, server.address, server.port }
| sort calls desc

トレース集計

完全なトレース分析

トレース内のすべてのスパンを集計して、完全なリクエストフローを理解:

fetch spans, from:now() - 30m
| summarize {
    spans = count(),
    client_spans = countIf(span.kind == "client"),

    // トレースに含まれるエンドポイント
    endpoints = toString(arrayRemoveNulls(collectDistinct(endpoint.name))),

    // トレース内の最初のリクエストルートを抽出
    trace_root = takeMin(record(
        root_detection_helper = coalesce(
            if(request.is_root_span, 1),
            if(isNull(span.parent_id), 2),
            3),
        start_time, endpoint.name, duration
      ))
}, by: { trace.id }

| fieldsFlatten trace_root
| fieldsRemove trace_root.root_detection_helper, trace_root

| fields
    start_time = trace_root.start_time,
    endpoint = trace_root.endpoint.name,
    response_time = trace_root.duration,
    spans,
    client_spans,
    endpoints,
    trace.id
| sort start_time
| limit 100

ルート検出戦略: takeMin(record(...)) と検出ヘルパーを使用してルートリクエストを確実に検出:

1. 優先度 1: request.is_root_span == true を持つスパン
2. 優先度 2: 親がないスパン（ルートスパン）
3. 優先度 3: その他すべてのスパン

マルチサービストレース

複数のサービスに及ぶトレースを検索:

fetch spans, from:now() - 1h
| summarize {
    services = collectDistinct(dt.service.name),
    trace_root = takeMin(record(root_detection_helper = coalesce(if(request.is_root_span, 1), 2), endpoint.name))
}, by: { trace.id }
| fieldsAdd service_count = arraySize(services)
| filter service_count > 1
| fields endpoint = trace_root[endpoint.name], service_count, services = toString(services), trace.id
| sort service_count desc
| limit 50

リクエストレベル分析

リクエスト属性

OneAgent によってリクエストルートスパンでキャプチャされたカスタムリクエスト属性にアクセス:

fetch spans
| filter request.is_root_span == true
| filter isNotNull(request_attribute.PaidAmount)
| makeTimeseries sum(request_attribute.PaidAmount)

フィールドパターン: request_attribute.<name>、captured_attribute.<name>（常に配列）

→ Request Attributes — リクエスト属性、キャプチャ属性、リクエスト ID 集計の完全なパターン

スパンタイプ

スパンタイプ	検出	キーフィールド	リファレンス
HTTP サーバー（受信）	span.kind == "server" and isNotNull(http.request.method)	http.route、http.request.method、http.response.status_code	http-spans.md
HTTP クライアント（発信）	span.kind == "client" and isNotNull(http.request.method)	server.address、server.port	http-spans.md
データベース	span.kind == "client" and isNotNull(db.system)	db.system、db.namespace、db.statement	database-spans.md
メッセージング	isNotNull(messaging.system)	messaging.system、messaging.destination.name、messaging.operation.type	messaging-spans.md
RPC / gRPC	isNotNull(rpc.system)	rpc.system、rpc.service、rpc.method、rpc.grpc.status_code	rpc-spans.md
サーバーレス / FaaS	isNotNull(faas.name) and span.kind == "server"	faas.name、faas.trigger.type、cloud.provider	serverless-spans.md

⚠️ データベーススパン: 集計される場合があります（1 つのスパン = 複数の呼び出し）。操作数の正確なカウントのために常に aggregation.count 外挿を使用します。

📖 スパンタイプごとの詳細パターン: 上記のリファレンスファイルを参照してください。

高度なトピック

例外分析

例外はスパン内で span.events として保存されます:

fetch spans
| filter iAny(span.events[][span_event.name] == "exception")
| expand span.events
| fieldsFlatten span.events, fields: { exception.type }
| summarize {
    count(),
    trace=takeAny(record(start_time, trace.id))
  }, by: { exception.type }
| fields exception.type, `count()`, trace.id=trace[trace.id], start_time=trace[start_time]

💡 ヒント: iAny() を使用してスパンイベント配列内の条件をチェックします。

→ Logs Correlation — ログとトレースの結合、ログコンテンツ別のトレースフィルタリング → Network Analysis — クライアント IP、DNS 解決、サブネット分析

ベストプラクティス

分野	ルール
フィルタリング	request.is_root_span == true とエンドポイントフィルタを最初に適用
サンプリング	samplingRatio を使用（例：100 = 1% を読み取り）
パーセンタイル	パフォーマンス分析には平均値ではなく p95/p99 を使用
ルートスパン	エンドツーエンド分析には request.is_root_span == true を使用
トレースグループ化	完全なトレースメトリクスのために trace.id でグループ化
リクエストグループ化	OneAgent のみのリクエストメトリクスのために request.id でグループ化
外挿	操作数のカウント正確性のために常に多重度を適用
例示的スパン	UI ドリルダウンを有効にするために takeAny(record(start_time, trace.id)) を使用

---

トラブルシューティング

問題	原因	解決策
期間値が間違っている（大きすぎる）	duration はナノ秒単位（ミリ秒ではない）	1000000 で割るか 5s（DQL 期間リテラル）と比較
スパン数が期待されるリクエスト量と一致しない	サンプリングまたは集計を考慮していない	多重度外挿を使用 — Sampling and Extrapolation リファレンスを参照
getNodeName(dt.smartscape.service) が null を返す	サービスがまだ解決されていないか OneAgent が監視していない	OneAgent がサービスを監視していることを確認；エンティティ解決に短い遅延がある場合があります
request.is_root_span フィルタが何も返さない	OneAgent なしの OpenTelemetry のみのトレースをクエリしている	ルートスパン検出のフォールバックとして isNull(span.parent_id) を使用
trace.id フィルタが結果を返さない	トレース ID が UID 形式に変換されていない	文字列ベースのトレース ID に filter trace.id == toUid("abc123...") を使用
データベーススパン数が低すぎる	データベーススパンが集計されている（1 つのスパン = N 回の呼び出し）	データベース操作数のカウントのために常に aggregation.count 外挿を使用

関連スキル

• dt-dql-essentials — トレースデータをクエリするための DQL コア構文
• dt-app-dashboards — トレースクエリをダッシュボードに埋め込む
• dt-migration — Smartscape エンティティモデルと関係ナビゲーション

---

リファレンス

特定のトピックに関する詳細ドキュメント:

• Performance Analysis - 高度なタイムシリーズ、期間バケット、エンドポイントランキング
• Failure Detection - 失敗理由、例外調査、カスタムルール
• Sampling and Extrapolation - 多重度計算、データベース外挿
• Request Attributes - リクエスト属性、キャプチャ属性、リクエスト ID 集計
• Entity Lookups - 高度なノードルックアップ、インフラストラクチャ相関、ハードウェア分析
• HTTP Span Analysis - ステータスコード、ペイロード分析、クライアント IP
• Database Span Analysis - 外挿カウント、遅いクエリ、ステートメント分析
• Messaging Span Analysis - Kafka、RabbitMQ、SQS スループットとレイテンシ
• RPC Span Analysis - gRPC、SOAP、サービス依存関係
• Serverless Span Analysis - Lambda、Azure Functions、コールドスタート分析
• Logs Correlation - ログとトレースの結合、相関パターン
• Network Analysis - IP アドレス、DNS 解決、通信マッピング