AWS X-Ray 區段文件 - AWS X-Ray
區段欄位子區段HTTP 請求資料註釋中繼資料AWS 資源資料錯誤和例外狀況SQL 查詢

本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

AWS X-Ray 區段文件

追蹤區段是您應用程式所處理請求的 JSON 表示。追蹤區段會記錄原始要求的相關資訊、應用程式在本機執行之工作的相關資訊，以及子區段，其中包含應用程式對 AWS 資源、HTTP API 和 SQL 資料庫進行之下游呼叫的相關資訊。

區段文件會將有關區段的資訊傳達至 X-Ray。區段文件最多可達 64 kB，且包含具有子區段的整個區段、指出要求正在進行的區段片段，或是個別傳送的單一子區段。您可以使用 PutTraceSegmentsAPI 將區段文件直接傳送至 X-Ray。

X-Ray 會編譯和處理區段文件，以產生可查詢的追蹤摘要和完整追蹤，您可以分別使用GetTraceSummaries和 BatchGetTracesAPI 存取這些摘要。除了您傳送至 X-Ray 的區段和子區段之外，服務還會使用子區段中的資訊來產生推斷的區段，並將其新增至完整追蹤。推斷的區段代表追蹤對映中的下游服務和資源。

X-Ray 提供區段文件的 JSON 結構定義。您可以在此處下載架構：xray-segmentdocument-schema-v1.0.0。以下章節會更詳細的說明結構描述中所列出的欄位和物件。

區段欄位的子集會由 X-Ray 編製索引，以便與篩選運算式搭配使用。例如，如果您將區段上的user欄位設定為唯一識別碼，您可以在 X-Ray 主控台或使用 GetTraceSummaries API 搜尋與特定使用者相關聯的區段。如需詳細資訊，請參閱 使用篩選運算式。

當您使用 X-Ray SDK 檢測應用程式時，SDK 會為您產生區段文件。SDK 不會將區段文件直接傳送至 X-Ray，而是透過本機 UDP 連接埠將它們傳送至 X-Ray 精靈。如需詳細資訊，請參閱 將區段文件傳送至 X-Ray 精靈。

區段欄位

區段會記錄您應用程式所處理請求的相關追蹤資訊。區段最少會記錄請求的名稱、ID、開始時間、追蹤 ID 及結束時間。

範例 最小的完成區段
{
  "name" : "example.com",
  "id" : "70de5b6f19ff9a0a",
  "start_time" : 1.478293361271E9,
  "trace_id" : "1-581cf771-a006649127e371903a2de979",
  "end_time" : 1.478293361449E9
}

以下欄位為區段的必要項目或條件式必要項目。

注意

除非另有說明，否則值必須為字串 (最多 250 個字元)。

必要的區段欄位

  • name— 處理要求之服務的邏輯名稱，最多 200 個字元。例如，您應用程式的名稱或網域名稱。名稱可包含 Unicode 字母、數字、空格和下列符號：_、.、:、/、%、&、#、=、+、\、-、@

  • id— 區段的 64 位元識別碼，在相同軌跡中的區段中唯一，以 16 個十六進位數字表示。

  • trace_id— 連接源自單一用戶端要求的所有區段和子區段的唯一識別碼。

    X-Ray 軌跡 ID 格式

    X-Ray trace_id 由三個用連字符分隔的數字組成。例如 1-58406520-a006649127e371903a2de979。其中包含：

    • 版本號碼，也就是1。

    • 原始請求的時間在 Unix 紀元時間使用 8 個十六進制數字。

      例如，2016 年 12 月 1 日上午 10:00 PST (以紀元時間表示) 為1480615200秒或十六進58406520位數字。

    • 追蹤的全域唯一 96 位元識別碼，以 24 個十六進位數字顯示。

    注意

    X-Ray 現在支援使用以 OpenTelemetry 及符合 W3C 追蹤上下文規格的任何其他架構建立的追蹤 ID。傳送至 X-Ray 時，W3C 追蹤識別碼必須格式化為 X-Ray 追蹤 ID 格式。例如，W3C 追蹤識別碼4efaaf4d1e8720b39541901950019ee5應格式化為傳送至 X-Ray 1-4efaaf4d-1e8720b39541901950019ee5 時。X-Ray 跟踪 ID 包括 Unix 紀元時間中的原始請求時間戳，但是當以 X-Ray 格式發送 W3C 跟踪 ID 時，這不是必需的。

    追蹤 ID 安全

    您可在回應標頭中取得追蹤 ID。使用安全的隨機演算法產生追蹤 ID，以確保攻擊者無法計算未來的追蹤 ID，並使用這些 ID 傳送請求到您的應用程式。

  • start_time— 數字，表示區段建立的時間，以紀元時間為單位的浮點秒數。例如 1480615200.010 或 1.480615200010E9。視需要使用任意小數位數。建議盡可能使用毫秒解析度。

  • end_time-數字，即段被關閉的時間。例如 1480615200.090 或 1.480615200090E9。指定 end_time 或 in_progress。

  • in_progress— 布林值，設定為true而非指定end_time以記錄區段已啟動但未完成。應用程式收到的請求需要很長時間時，請傳送進行中區段，以追蹤請求的接收情況。回應已傳送時，請傳送完成區段以覆寫進行中的區段。針對每個請求，請只傳送一個完成區段，以及一或零個進行中區段。

服務名稱

區段name應與產生區段之服務的網域名稱或邏輯名稱相符。但是，這不是強制執行的。具有PutTraceSegments可傳送任何名稱之區段之權限的任何應用程式。

以下欄位是區段的選擇性欄位。

選擇性區段欄位

  • service— 包含應用程式相關資訊的物件。

    • version— 字串，用來識別提供要求的應用程式版本。

  • user— 識別傳送要求之使用者的字串。

  • origin— 執行應用程式的 AWS 資源類型。

    支援值

    • AWS::EC2::Instance— 一個 Amazon EC2 實例。

    • AWS::ECS::Container— Amazon ECS 容器.

    • AWS::ElasticBeanstalk::Environment— Elastic Beanstalk 環境。

    當有多個值適用您的應用程式時，請使用最具指定性的。例如，多容器泊塢視窗 Elastic Beanstalk 環境會在 Amazon ECS 容器上執行您的應用程式，然後在 Amazon EC2 執行個體上執行。在此案例中，您會將來源設為 AWS::ElasticBeanstalk::Environment，因為環境是其他兩個資源的父系。

  • parent_id— 您指定的子區段 ID 是否來自已檢測的應用程式的要求。X-Ray SDK 會將父子區段識別碼新增至追蹤標頭，以供下游 HTTP 呼叫使用。在巢狀子區段的情況下，子區段可以有一個區段或子區段作為其父項。

  • http— 包含原始 HTTP 要求相關資訊的http物件。

  • aws— aws含有應用程式提供要求之 AWS 資源相關資訊的物件。

  • error、throttlefault、和 cause — 錯誤欄位，指出發生錯誤，其中包含造成錯誤之例外狀況的相關資訊。

  • annotations— 具有您希望 X-Ray 索引以進行搜尋的索引鍵值配對的annotations物件。

  • metadata— metadata含有您要儲存在區段中的任何其他資料的物件。

  • subsegments— subsegment物件陣列。

子區段

您可以建立子區段，以記錄您使用 AWS SDK 進行的呼叫 AWS 服務 和資源、呼叫內部或外部 HTTP Web API 或 SQL 資料庫查詢。您也可以建立子區段，除錯或標註您應用程式中的程式碼區塊。子區段可包含其他子區段，因此記錄內部函數呼叫中繼資料的自訂子區段可包含其他自訂子區段及下游呼叫的子區段。

子區段會從呼叫該呼叫的服務的角度記錄下游呼叫。X-Ray 使用子區段來識別不傳送區段的下游服務，並在服務圖上為其建立項目。

子區段可內嵌在完整區段文件中，或是分別傳送。將子區段分別傳送，來非同步追蹤長時間執行請求的下游呼叫，或是避免超過區段文件大小上限。

範例 具有內嵌子區段的區段

獨立子區段具備 subsegment 的 type，以及可識別父區段的 parent_id。

{
  "trace_id"   : "1-5759e988-bd862e3fe1be46a994272793",
  "id"         : "defdfd9912dc5a56",
  "start_time" : 1461096053.37518,
  "end_time"   : 1461096053.4042,
  "name"       : "www.example.com",
  "http"       : {
    "request"  : {
      "url"        : "https://www.example.com/health",
      "method"     : "GET",
      "user_agent" : "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_11_6) AppleWebKit/601.7.7",
      "client_ip"  : "11.0.3.111"
    },
    "response" : {
      "status"         : 200,
      "content_length" : 86
    }
  },
  "subsegments" : [
    {
      "id"         : "53995c3f42cd8ad8",
      "name"       : "api.example.com",
      "start_time" : 1461096053.37769,
      "end_time"   : 1461096053.40379,
      "namespace"  : "remote",
      "http"       : {
        "request"  : {
          "url"    : "https://api.example.com/health",
          "method" : "POST",
          "traced" : true
        },
        "response" : {
          "status"         : 200,
          "content_length" : 861
        }
      }
    }
  ]
}

對於長時間執行的請求，您可以傳送進行中的區段，通知 X-Ray 已收到請求，然後在完成原始請求之前分別傳送子區段以追蹤它們。

範例 進行中的區段
{
  "name" : "example.com",
  "id" : "70de5b6f19ff9a0b",
  "start_time" : 1.478293361271E9,
  "trace_id" : "1-581cf771-a006649127e371903a2de979",
  "in_progress": true
}
範例 獨立子區段

獨立子區段具備 subsegment 的 type、trace_id 及 parent_id，可識別父區段。

{
  "name" : "api.example.com",
  "id" : "53995c3f42cd8ad8",
  "start_time" : 1.478293361271E9,
  "end_time" : 1.478293361449E9,
  "type" : "subsegment",
  "trace_id" : "1-581cf771-a006649127e371903a2de979"
  "parent_id" : "defdfd9912dc5a56",
  "namespace"  : "remote",
  "http"       : {
      "request"  : {
          "url"    : "https://api.example.com/health",
          "method" : "POST",
          "traced" : true
      },
      "response" : {
          "status"         : 200,
          "content_length" : 861
      }
  }
}

當請求完成時，透過使用 end_time 重新傳送它來關閉區段。完整區段會覆寫正在進行中的區段。

您也可以為觸發非同步工作流程的已完成請求分別傳送子區段。例如，web API 可能會在開始使用者請求的工作前立即傳回 OK 200 回應。您可以在傳送回應後立即將完整區段傳送至 X-Ray，接著再傳送子區段以供稍後完成的工作。與區段相同，您也可以傳送子區段片段來記錄子區段已啟動，然後在完成下游呼叫時使用完整的子區段覆寫它。

以下欄位為子區段的必要項目或條件式必要項目。

注意

除非另有說明，否則值必須為字串 (最多 250 個字元)。

必要的子區段欄位

  • id— 子區段的 64 位元識別碼，在相同軌跡中的區段中唯一，以 16 個十六進位數字表示。

  • name— 子區段的邏輯名稱。針對下游呼叫，請在呼叫資源或服務後命名子區段。針對自訂子區段，請在其檢測的程式碼 (例如函數名稱) 之後命名子區段。

  • start_time— 數字，即創建子段的時間，以時代時間為單位的浮點秒，精確到毫秒。例如 1480615200.010 或 1.480615200010E9。

  • end_time-數字，即子段關閉的時間。例如 1480615200.090 或 1.480615200090E9。指定 end_time 或 in_progress。

  • in_progress— 設定為true而非指定以記錄子區段已啟動但未完成的布林值。end_time針對每個下游請求，請只傳送一個完成子區段，以及一或零個進行中子區段。

  • trace_id— 子區段父區段的追蹤 ID。僅在分別傳送子區段時才為必要項目。

    X-Ray 軌跡 ID 格式

    X-Ray trace_id 由三個用連字符分隔的數字組成。例如 1-58406520-a006649127e371903a2de979。其中包含：

    • 版本號碼，也就是1。

    • 原始請求的時間在 Unix 紀元時間使用 8 個十六進制數字。

      例如，2016 年 12 月 1 日上午 10:00 PST (以紀元時間表示) 為1480615200秒或十六進58406520位數字。

    • 追蹤的全域唯一 96 位元識別碼，以 24 個十六進位數字顯示。

    注意

    X-Ray 現在支援使用以 OpenTelemetry 及符合 W3C 追蹤上下文規格的任何其他架構建立的追蹤 ID。傳送至 X-Ray 時，W3C 追蹤識別碼必須格式化為 X-Ray 追蹤 ID 格式。例如，W3C 追蹤識別碼4efaaf4d1e8720b39541901950019ee5應格式化為傳送至 X-Ray 1-4efaaf4d-1e8720b39541901950019ee5 時。X-Ray 跟踪 ID 包括 Unix 紀元時間中的原始請求時間戳，但是當以 X-Ray 格式發送 W3C 跟踪 ID 時，這不是必需的。

  • parent_id— 子區段父項區段的區段 ID。僅在分別傳送子區段時才為必要項目。在巢狀子區段的情況下，子區段可以有一個區段或子區段作為其父項。

  • type—subsegment. 僅在分別傳送子區段時才需要。

以下欄位是子區段的選擇性欄位。

選擇性子區段欄位

  • namespace— aws 適用於 AWS 開發套件呼叫；remote適用於其他下游呼叫。

  • http— 包http含傳出 HTTP 呼叫相關資訊的物件。

  • aws— 包含應用程式呼叫之下游 AWS 資源相關資訊的aws物件。

  • error、throttlefault、和 cause — 錯誤欄位，指出發生錯誤，其中包含造成錯誤之例外狀況的相關資訊。

  • annotations— 具有您希望 X-Ray 索引以進行搜尋的索引鍵值配對的annotations物件。

  • metadata— metadata含有您要儲存在區段中的任何其他資料的物件。

  • subsegments— subsegment物件陣列。

  • precursor_ids— 子區段 ID 陣列，可識別在此子區段之前完成的相同父項的子區段。

HTTP 請求資料

使用 HTTP 區塊來記錄您應用程式所處理的 HTTP 請求相關詳細資訊 (位於區段中)，或是您應用程式對下游 HTTP API 所發出請求的相關詳細資訊 (位於子區段中)。此物件中大部分的欄位都會映射到 HTTP 請求和回應中找到的資訊。

http

所有欄位都是選擇性的。

  • request— 有關請求的資訊。

    • method— 請求方法。例如 GET。

    • url— 請求的完整 URL，從請求的協議，主機名和路徑編譯。

    • user_agent— 來自請求者用戶端的使用者代理程式字串。

    • client_ip— 要求者的 IP 位址。可從 IP 封包的 Source Address 擷取，或是針對轉送的請求，則從 X-Forwarded-For 標頭擷取。

    • x_forwarded_for— (僅限區段) 布林值，表示client_ip已從X-Forwarded-For標頭讀取且不可靠，因為它可能已偽造。

    • traced— (僅限子區段) 布林值，表示下游呼叫是至另一個追蹤服務。如果將此欄位設定為true，X-Ray 會將追蹤視為中斷，直到下游服務上傳符合包含此區塊id之子區段的區段為止。parent_id

  • response— 有關響應的信息。

    • status— 整數，表示回應的 HTTP 狀態。

    • content_length— 整數，指出以位元組為單位的回應主體長度。

當您檢測對下游 Web API 的呼叫時，請記錄一個子區段，其中包含 HTTP 要求和回應的相關資訊。X-Ray 會使用子區段來產生遠端 API 的推斷區段。

範例 在 Amazon EC2 上執行之應用程式提供的 HTTP 呼叫區段
{
  "id": "6b55dcc497934f1a",
  "start_time": 1484789387.126,
  "end_time": 1484789387.535,
  "trace_id": "1-5880168b-fd5158284b67678a3bb5a78c",
  "name": "www.example.com",
  "origin": "AWS::EC2::Instance",
  "aws": {
    "ec2": {
      "availability_zone": "us-west-2c",
      "instance_id": "i-0b5a4678fc325bg98"
    },
    "xray": {
        "sdk_version": "2.11.0 for Java"
    },
  },
  "http": {
    "request": {
      "method": "POST",
      "client_ip": "78.255.233.48",
      "url": "http://www.example.com/api/user",
      "user_agent": "Mozilla/5.0 (Windows NT 6.1; WOW64; rv:45.0) Gecko/20100101 Firefox/45.0",
      "x_forwarded_for": true
    },
    "response": {
      "status": 200
    }
  }
範例 下游 HTTP 呼叫的子區段
{
  "id": "004f72be19cddc2a",
  "start_time": 1484786387.131,
  "end_time": 1484786387.501,
  "name": "names.example.com",
  "namespace": "remote",
  "http": {
    "request": {
      "method": "GET",
      "url": "https://names.example.com/"
    },
    "response": {
      "content_length": -1,
      "status": 200
    }
  }
}
範例 下游 HTTP 呼叫的推斷區段
{
  "id": "168416dc2ea97781",
  "name": "names.example.com",
  "trace_id": "1-62be1272-1b71c4274f39f122afa64eab",
  "start_time": 1484786387.131,
  "end_time": 1484786387.501,
  "parent_id": "004f72be19cddc2a",
  "http": {
    "request": {
      "method": "GET",
      "url": "https://names.example.com/"
    },
    "response": {
      "content_length": -1,
      "status": 200
    }
  },
  "inferred": true
}

註釋

區段和子區段可包含一個annotations物件，其中包含 X-Ray 索引的一個或多個欄位，以便與篩選運算式搭配使用。欄位可以有字串、數字或布林值 (沒有物件或陣列)。X-Ray 索引每個軌跡最多 50 個註釋。

範例 HTTP 呼叫區段與標註
{
  "id": "6b55dcc497932f1a",
  "start_time": 1484789187.126,
  "end_time": 1484789187.535,
  "trace_id": "1-5880168b-fd515828bs07678a3bb5a78c",
  "name": "www.example.com",
  "origin": "AWS::EC2::Instance",
  "aws": {
    "ec2": {
      "availability_zone": "us-west-2c",
      "instance_id": "i-0b5a4678fc325bg98"
    },
    "xray": {
        "sdk_version": "2.11.0 for Java"
    },
  },
  "annotations": {
    "customer_category" : 124,
    "zip_code" : 98101,
    "country" : "United States",
    "internal" : false
  },
  "http": {
    "request": {
      "method": "POST",
      "client_ip": "78.255.233.48",
      "url": "http://www.example.com/api/user",
      "user_agent": "Mozilla/5.0 (Windows NT 6.1; WOW64; rv:45.0) Gecko/20100101 Firefox/45.0",
      "x_forwarded_for": true
    },
    "response": {
      "status": 200
    }
  }

鍵必須為英數字元，才能使用篩選條件。允許使用底線。不允許使用其他符號和空格。

中繼資料

區段和子區段可以包含一或多個欄位的metadata物件，其中包含任何類型的值，包括物件和陣列。X-Ray 不會為中繼資料建立索引，而且值可以是任何大小，只要區段文件不超過最大大小 (64 kB) 即可。您可以在 BatchGetTraces API 傳回的完整區段文件中檢視中繼資料。以開頭的欄位金鑰 (debug在下列範例中) AWS. 會保留給 AWS提供的 SDK 和用戶端使用。

範例 使用中繼資料的自訂子區段
{
  "id": "0e58d2918e9038e8",
  "start_time": 1484789387.502,
  "end_time": 1484789387.534,
  "name": "## UserModel.saveUser",
  "metadata": {
    "debug": {
      "test": "Metadata string from UserModel.saveUser"
    }
  },
  "subsegments": [
    {
      "id": "0f910026178b71eb",
      "start_time": 1484789387.502,
      "end_time": 1484789387.534,
      "name": "DynamoDB",
      "namespace": "aws",
      "http": {
        "response": {
          "content_length": 58,
          "status": 200
        }
      },
      "aws": {
        "table_name": "scorekeep-user",
        "operation": "UpdateItem",
        "request_id": "3AIENM5J4ELQ3SPODHKBIRVIC3VV4KQNSO5AEMVJF66Q9ASUAAJG",
        "resource_names": [
          "scorekeep-user"
        ]
      }
    }
  ]
}

AWS 資源資料

針對區段，aws 物件包含您應用程式於其上執行的資源相關資訊。可將多個欄位套用至單一資源。例如，在 Elastic Beanstalk 上的多容器 Docker 環境中執行的應用程式可能具有關於 Amazon EC2 執行個體、在執行個體上執行的 Amazon ECS 容器，以及 Elastic Beanstalk 環境本身的相關資訊。

aws (區段)

所有欄位都是選擇性的。

  • account_id— 如果您的應用程式將區段傳送至其他區段 AWS 帳戶，請記錄執行應用程式的帳戶 ID。

  • cloudwatch_logs— 描述單一 CloudWatch 記錄群組的物件陣列。

    • log_group—「記 CloudWatch 錄群組」名稱。

    • arn— 記 CloudWatch 錄群組 ARN。

  • ec2— 有關 Amazon EC2 執行個體的資訊。

    • instance_id— EC2 執行個體的執行個體識別碼。

    • instance_size— EC2 執行個體的類型。

    • ami_id— Amazon 機器圖像 ID.

    • availability_zone— 執行執行個體所在的可用區域。

  • ecs— 有關 Amazon ECS 容器的信息。

    • container— 容器的主機名稱。

    • container_id— 容器的完整容器 ID。

    • container_arn— 容器執行個體的 ARN。

  • eks— 有關 Amazon EKS 集群的信息。

    • pod— 您的 EKS 網繭的主機名稱。

    • cluster_name— EKS 叢集名稱。

    • container_id— 容器的完整容器 ID。

  • elastic_beanstalk— 有關 Elastic Beanstalk 環境的信息。您可以在最新的 Elastic Beanstalk 平台/var/elasticbeanstalk/xray/environment.conf上命名的文件中找到此信息。

    • environment_name - 環境名稱。

    • version_label— 目前部署至提供要求之執行個體的應用程式版本名稱。

    • deployment_id— 代表上次成功部署至提供要求之執行個體的識別碼的數字。

  • xray— 有關所使用儀器類型和版本的中繼資料。

    • auto_instrumentation— 布林值，指出是否使用自動分析 (例如，Java 代理程式)。

    • sdk_version— 所使用的 SDK 或代理程式版本。

    • sdk— SDK 的類型。

範例 AWS 阻止與插件
"aws":{
   "elastic_beanstalk":{
      "version_label":"app-5a56-170119_190650-stage-170119_190650",
      "deployment_id":32,
      "environment_name":"scorekeep"
   },
   "ec2":{
      "availability_zone":"us-west-2c",
      "instance_id":"i-075ad396f12bc325a",
      "ami_id":
   },
   "cloudwatch_logs":[
      {
         "log_group":"my-cw-log-group",
         "arn":"arn:aws:logs:us-west-2:012345678912:log-group:my-cw-log-group"
      }
   ],
   "xray":{
      "auto_instrumentation":false,
      "sdk":"X-Ray for Java",
      "sdk_version":"2.8.0"
   }
}

對於子區段，請記錄應用程式存取的 AWS 服務 和資源的相關資訊。X-Ray 會使用此資訊來建立表示服務對映中下游服務的推論區段。

aws (子區段)

所有欄位都是選擇性的。

  • operation— 針對 AWS 服務 或資源叫用的 API 動作名稱。

  • account_id— 如果您的應用程式存取不同帳戶中的資源，或將區段傳送至其他帳戶，請記錄擁有應用程式存取之 AWS 資源的帳號 ID。

  • region— 如果資源位於與您的應用程式不同的區域，請記錄該區域。例如 us-west-2。

  • request_id— 要求的唯一識別碼。

  • queue_url— 對於 Amazon SQS 佇列上的操作，則為佇列的 URL。

  • table_name— 對於 DynamoDB 資料表上的作業，則為資料表的名稱。

範例 呼叫 DynamoDB 以儲存項目的子區段
{
  "id": "24756640c0d0978a",
  "start_time": 1.480305974194E9,
  "end_time": 1.4803059742E9,
  "name": "DynamoDB",
  "namespace": "aws",
  "http": {
    "response": {
      "content_length": 60,
      "status": 200
    }
  },
  "aws": {
    "table_name": "scorekeep-user",
    "operation": "UpdateItem",
    "request_id": "UBQNSO5AEM8T4FDA4RQDEB94OVTDRVV4K4HIRGVJF66Q9ASUAAJG",
  }
}

錯誤和例外狀況

當發生錯誤時，您可以記錄錯誤及其產生異常的相關詳細資訊。在您應用程式將錯誤傳回使用者時於區段中記錄錯誤，或是在下游呼叫傳回錯誤時於子區段中記錄錯誤。

錯誤類型

將一或多個以下欄位設為 true 來指出發生錯誤。若錯誤發生複合，則可套用多個類型。例如，來自下游呼叫的 429 Too Many Requests 錯誤可能會造成您的應用程式傳回 500 Internal Server Error；在這種情況下，即會套用三種類型。

  • error— 布林值，表示發生用戶端錯誤 (回應狀態碼為 4XX 用戶端錯誤)。

  • throttle— 布林值，表示要求已限制 (回應狀態碼為 429 要求太多)。

  • fault— 布林值，表示發生伺服器錯誤 (回應狀態碼為 5XX 伺服器錯誤)。

透過在區段或子區段中包含一個原因 (cause) 物件來指出錯誤的原因。

cause

原因可以是 16 字元的異常 ID，或是具備以下欄位的物件：

  • working_directory— 發生異常時工作目錄的完整路徑。

  • paths— 發生例外狀況時所使用的程式庫或模組的路徑陣列。

  • exceptions— 例外狀況物件的陣列。

在一或多個異常 (exception) 物件中包含錯誤的詳細資訊。

exception

所有欄位都是選擇性的。

  • id— 例外狀況的 64 位元識別碼，在相同追蹤中的區段中是唯一的，以 16 個十六進位數字表示。

  • message— 例外狀況訊息。

  • type— 例外狀況類型。

  • remote— 布林值，表示例外狀況是由下游服務傳回的錯誤所造成。

  • truncated— 整數，表示從省略的堆疊影格數目stack。

  • skipped— 整數，表示在此例外狀況與其子系之間略過的例外狀況數目，也就是它所造成的例外狀況。

  • cause— 例外父項的例外狀況識別碼，也就是造成此例外狀況的例外狀況。

  • stack— stackFrame 物件的陣列。

若可用的話，在 stackFrame 物件中記錄呼叫堆疊的相關資訊。

stackFrame

所有欄位都是選擇性的。

  • path— 檔案的相對路徑。

  • line— 檔案中的行。

  • label— 函數或方法名稱。

SQL 查詢

您可以建立為您應用程式對 SQL 資料庫發出的查詢建立子區段。

sql

所有欄位都是選擇性的。

  • connection_string— 對於不使用 URL 連接字串的 SQL Server 或其他資料庫連線，請記錄連接字串 (不包括密碼)。

  • url— 對於使用 URL 連線字串的資料庫連線，請記錄 URL，但不包括密碼。

  • sanitized_query— 資料庫查詢，其中任何使用者提供的值會移除或取代為預留位置。

  • database_type— 資料庫引擎的名稱。

  • database_version— 資料庫引擎的版本號碼。

  • driver_version— 應用程式使用的資料庫引擎驅動程式的名稱和版本號碼。

  • user— 資料庫使用者名稱。

  • preparation— call 如果查詢使用了PreparedCall；statement如果查詢使用PreparedStatement.

範例 使用 SQL 查詢的子區段
{
  "id": "3fd8634e78ca9560",
  "start_time": 1484872218.696,
  "end_time": 1484872218.697,
  "name": "ebdb@aawijb5u25wdoy.cpamxznpdoq8.us-west-2.rds.amazonaws.com",
  "namespace": "remote",
  "sql" : {
    "url": "jdbc:postgresql://aawijb5u25wdoy.cpamxznpdoq8.us-west-2.rds.amazonaws.com:5432/ebdb",
    "preparation": "statement",
    "database_type": "PostgreSQL",
    "database_version": "9.5.4",
    "driver_version": "PostgreSQL 9.4.1211.jre7",
    "user" : "dbuser",
    "sanitized_query" : "SELECT  *  FROM  customers  WHERE  customer_id=?;"
  }
}