建立資料來源的自訂連接器 - Amazon CloudWatch
使用範本 從頭開始建立自訂資料來源

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

建立資料來源的自訂連接器

若要將自訂資料來源連線到 CloudWatch，您有兩種選擇：

  • 使用提供的範例範本開始使 CloudWatch 用。您可以使用任何一個 JavaScript 或 Python 與此模板。這些範本包含範例 Lambda 程式碼，這些程式碼在您建立 Lambda 函數時很有用。然後，可以從範本中修改 Lambda 函數，以連線到自訂資料來源。

  • 從頭開始建立 AWS Lambda 函數，以實作資料來源連接器、資料查詢以及準備供使用的時間序列 CloudWatch。如果需要，此函數必須預先彙總或合併資料點，並對齊要與之相容的週期和時間戳記。 CloudWatch

使用範本

使用範本可建立範例 Lambda 函數，並協助您更快地建置自訂連接器。這些範例函數為建置自訂連接器所涉及的許多常見案例提供範例程式碼。可以在使用範本建立連接器之後檢查 Lambda 程式碼，然後修改它以用於連線至資料來源。

此外，如果您使用範本，請注 CloudWatch 意建立 Lambda 許可政策，並將資源標籤附加至 Lambda 函數。

使用範本建立自訂資料來源的連接器

  1. 請在以下位置開啟 CloudWatch 主控台。 https://console.aws.amazon.com/cloudwatch/

  2. 在導覽窗格中，選擇設定。

  3. 選擇指標資料來源索引標籤。

  4. 選擇 Create data source (建立資料來源)。

  5. 選擇自訂 - 開始使用範本的選項按鈕，然後選擇下一步。

  6. 輸入資料來源的名稱。

  7. 選取列出的其中一個範本。

  8. 選擇 Node.js 或 Python。

  9. 選擇 Create data source (建立資料來源)。

    在 AWS CloudFormation 堆疊完成建立之前，您剛新增的新自訂來源才會出現。若要檢查進度，您可以選擇 [檢視我的 CloudFormation 堆疊狀態]。或者，可以選擇重新整理圖示來更新此清單。

    當新資料來源出現在此清單中時，就可以在主控台中進行測試並修改。

  10. (選用) 若要在主控台中查詢來自此來源的測試資料，請遵循 從另一個資料來源建立指標圖表 中的指示。

  11. 根據需求修改 Lambda 函數。

    1. 在導覽窗格中，選擇設定。

    2. 選擇指標資料來源索引標籤。

    3. 針對您想要修改的來源，選擇在 Lambda 主控台中檢視。

    您現在可以修改函數以存取資料來源。如需詳細資訊，請參閱 步驟 1：建立函數。

    注意

    透過使用範本，當您撰寫 Lambda 函數時，無需遵循 步驟 2：建立 Lambda 許可政策 或 步驟 3：將資源標籤附接至 Lambda 函數 中的指示。這些步驟是由執行的， CloudWatch 因為您使用了範本。

從頭開始建立自訂資料來源

請依照本節中的步驟建立連線 CloudWatch 至資料來源的 Lambda 函數。

步驟 1：建立函數

自訂資料來源連接器必須支援來自的GetMetricData事件 CloudWatch。或者，您也可以實作DescribeGetMetricData事件，以便在 CloudWatch 主控台中向使用者提供如何使用連接器的說明文件。DescribeGetMetricData回應也可以用來設 CloudWatch 定自訂查詢建置器中使用的預設值。

CloudWatch 提供程式碼片段做為範例，以協助您開始使用。如需詳細資訊，請參閱 https://github.com/aws-samples/ 的範例儲存庫cloudwatch-data-source-samples。

限制條件

  • 來自 Lambda 的回應必須小於 6 Mb。如果回應超過 6 Mb，則 GetMetricData 回應會將 Lambda 函數標記為 InternalError，且不會傳回任何資料。

  • Lambda 函數必須在 10 秒內完成其執行，以達到視覺化和儀表板目的；或在 4.5 秒內完成執行，起到警示作用。如果執行時間超過該時間，則 GetMetricData 回應會將 Lambda 函數標記為 InternalError，且不會傳回任何資料。

  • Lambda 函數必須使用 Epoch 時間戳記 (以秒為單位) 來傳送其輸出。

  • 如果 Lambda 函數未重新取樣資料，而是傳回與 CloudWatch 使用者要求的開始時間和週期長度不相符的資料，則會忽略該資料。 CloudWatch會從任何視覺效果或警示中捨棄額外資料。任何非開始時間和結束時間之間的資料也會被捨棄。

    例如，如果使用者需要間隔為 5 分鐘從上午 10 點到 11 點之間的資料，則傳回資料的有效時間範圍為「10:00:00 到 10:04:59」和「10:05:00 到 10:09:59」。必須傳回包含 10:00 value1、10:05 value2 等的時間序列。例如，如果函數傳回 10:03 valueX，它會被丟棄，因為 10:03 與請求的開始時間和間隔不符。

  • CloudWatch 資料來源連接器不支援多行查詢。執行查詢時，或當您使用查詢建立警示或儀表板小工具時，每個換行符都會取代為空格。在某些情況下，這可能會使查詢無效。

GetMetricData 事件

請求承載

以下是作為 Lambda 函數的輸入而傳送的 GetMetricData 請求承載範例。

{
  "EventType": "GetMetricData",
  "GetMetricDataRequest": {
    "StartTime": 1697060700,
    "EndTime": 1697061600,
    "Period": 300,
    "Arguments": ["serviceregistry_external_http_requests{host_cluster!=\"prod\"}"] 
  }
}

  • StartTime— 指定要傳回之最早資料的時間戳記。類型是時間戳記 Epoch 秒。

  • EndTime— 指定要傳回之最新資料的時間戳記。類型是時間戳記 Epoch 秒。

  • 間隔 – 指標資料的每個彙總所代表的秒數。最小值為 60 秒。類型為秒。

  • 引數 – 傳遞至 Lambda 指標數學運算式的引數陣列。如需有關傳遞引數的詳細資訊，請參閱 如何將引數傳遞給 Lambda 函數。

回應承載

以下是 Lambda 函數傳回的 GetMetricData 回應承載範例。

{
   "MetricDataResults": [
      {
         "StatusCode": "Complete",
         "Label": "CPUUtilization",
         "Timestamps": [ 1697060700, 1697061000, 1697061300 ],
         "Values": [ 15000, 14000, 16000 ]
      }
   ]
}

回應承載將包含 MetricDataResults 欄位或 Error 欄位，但不能同時包含兩者。

MetricDataResults 欄位是一系列 MetricDataResult 類型的時間序列欄位。每個時間序列欄位可以包含下列欄位。

  • StatusCode— (選用) Complete 表示傳回要求時間範圍內的所有資料點。 PartialData表示傳回一組不完整的資料點。若省略，則預設值為 Complete。

    有效值：Complete | InternalError | PartialData | Forbidden

  • 訊息 – 可選訊息清單，其中包含有關傳回資料的其他資訊。

    類型：具有Code和Value字符串的MessageData對象數組。

  • 標籤 – 與資料相關聯的人類可讀標籤。

    類型：字串

  • 時間戳記 – 資料點的時間戳記，格式為 Epoch 時間。時間戳記的數目始終符合值的數目，而且 Timestamps[x] 的值為 Values[x]。

    類型：時間戳記陣列

  • 值 – 指標的資料點值，對應於 Timestamps。值的數目始終符合時間戳記的數目，而且 Timestamps[x] 的值為 Values[x]。

    類型：雙精度陣列

如需有關 Error 物件的詳細資訊，請參閱下列各節。

錯誤回應格式

您可以選擇使用錯誤回應來提供有關錯誤的詳細資訊。建議您在發生驗證錯誤時傳回「程式碼驗證」錯誤，例如當參數遺失或類型錯誤時。

以下是 Lambda 函數想要引發 GetMetricData 驗證例外狀況時的回應範例。

{
   "Error": {
      "Code": "Validation",
      "Value": "Invalid Prometheus cluster"
   }
}

以下是當 Lambda 函數指出由於存取問題而無法傳回資料時的回應範例。回應會轉譯成單一時間序列，且狀態碼為 Forbidden。

{
   "Error": {
      "Code": "Forbidden",
      "Value": "Unable to access ..."
   }
}

以下是 Lambda 函數引發整體 InternalError 例外狀況時的範例，它會轉譯為單一時間序列，且具有狀態碼 InternalError 和訊息。每當錯誤代碼具有Validation或以外的值時Forbidden， CloudWatch 假設它是一個通用的內部錯誤。

{
   "Error": {
      "Code": "PrometheusClusterUnreachable",
      "Value": "Unable to communicate with the cluster"
   }
}

DescribeGetMetricData 事件

請求承載

以下是 DescribeGetMetricData 請求承載的範例。

{
  "EventType": "DescribeGetMetricData"
}

回應承載

以下是 DescribeGetMetricData 回應承載的範例。

{
    "Description": "Data source connector",
    "ArgumentDefaults": [{
        Value: "default value"
     }]
}

  • 描述 – 如何使用資料來源連接器的描述。此說明將出現在 CloudWatch 控制台中。支援 Markdown。

    類型：字串

  • ArgumentDefaults— 使用預先填入自訂資料來源建置器的可選引數預設值陣列。

    如果返回[{ Value: "default value 1"}, { Value: 10}]，則 CloudWatch 控制台中的查詢生成器顯示兩個輸入，第一個輸入為「默認值 1」，第二個輸入為 10。

    如果未提供 ArgumentDefaults，則會顯示單一輸入，且類型預設為 String。

    類型：包含「值」和「類型」的物件陣列。

  • 錯誤 – (選用) 錯誤欄位可包含在任何回應中。可在 GetMetricData 事件 中看到範例。

CloudWatch 警報的重要注意事項

如果您要使用資料來源設定 CloudWatch 警示，則應將其設定為每分鐘將時間戳記報告資料至 CloudWatch。如需有關從連線的資料來源中建立指標警示的詳細資訊和其他考量，請參閱 根據連線的資料來源建立警示。

(選擇性) 用 AWS Secrets Manager 來儲存認證

如果您的 Lambda 函數需要使用認證來存取資料來源，建議您使 AWS Secrets Manager 用儲存這些認證，而不是將其硬式編碼到 Lambda 函數中。如需 AWS Secrets Manager 搭配 Lambda 搭配使用的詳細資訊，請參閱在 AWS Lambda 函數中使用 AWS Secrets Manager 密碼。

(選用) 連線至 VPC 中的資料來源

如果資料來源位於 Amazon Virtual Private Cloud 所管理的 VPC 中，則必須設定 Lambda 函數才能存取它。如需詳細資訊，請參閱將傳出網路連線至 VPC 中的資源。

可能還需要設定 VPC 服務端點，才能存取諸如 AWS Secrets Manager等服務。如需詳細資訊，請參閱使用介面 VPC 端點存取 AWS 服務。

步驟 2：建立 Lambda 許可政策

您必須使用建立政策陳述式來 CloudWatch 授與使用您所建立之 Lambda 函數的權限。您可以使用 AWS CLI 或 Lambda 主控台建立政策陳述式。

若要使用 AWS CLI 建立政策陳述式

  • 輸入以下命令。將 123456789012 取代為您的帳戶識別碼、以您的 Lambda 函數my-data-source-function的名稱取代，並以任意唯一值取代 MyDataSource-DataSourcePermission 12 34。

    aws lambda add-permission --function-name my-data-source-function --statement-id MyDataSource-DataSourcePermission1234 --action lambda:InvokeFunction --principal lambda.datasource.cloudwatch.amazonaws.com --source-account 123456789012

步驟 3：將資源標籤附接至 Lambda 函數

主 CloudWatch 控台會使用標籤來判斷哪些 Lambda 函數是資料來源連接器。當您使用其中一個精靈建立資料來源時，標籤會由設定該資料來源的 AWS CloudFormation 堆疊自動套用。當您自行建立資料來源時，可以針對 Lambda 函數使用下列標籤。這會讓您的連接器在您查詢指標時出現在 CloudWatch 主控台的 [資料來源] 下拉式清單中。

  • 索引鍵為 cloudwatch:datasource 和值為 custom 的標籤。