本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。 # 將資料傳送至 Firehose 串流 本節說明如何使用不同的資料來源將資料傳送至 Firehose 串流。如果您是初次使用 Amazon Data Firehose，請花一些時間熟悉 中介紹的概念和術語[什麼是 Amazon Data Firehose？](what-is-this-service.md)。 **注意** 有些 AWS 服務只能傳送訊息和事件到位於相同區域的 Firehose 串流。當您為 Amazon CloudWatch Logs、CloudWatch Events 設定目標時，如果您的 Firehose 串流未顯示為選項 AWS IoT，或確認您的 Firehose 串流與其他服務位於相同的區域。如需每個區域服務端點的資訊，請參閱 [Amazon Data Firehose 端點](https://docs.aws.amazon.com/general/latest/gr/fh.html#fh_region)。 您可以從下列資料來源將資料傳送至 Firehose 串流。 **Topics** + [ # 設定 Kinesis 代理程式以傳送資料 ](writing-with-agents.md) + [ # 使用 AWS SDK 傳送資料 ](writing-with-sdk.md) + [ # 將 CloudWatch Logs 傳送至 Firehose ](writing-with-cloudwatch-logs.md) + [ # 將 CloudWatch 事件傳送至 Firehose ](writing-with-cloudwatch-events.md) + [ # 設定 AWS IoT 將資料傳送至 Firehose ](writing-with-iot.md) # 設定 Kinesis 代理程式以傳送資料 Amazon Kinesis 代理程式是一種獨立的 Java 軟體應用程式，可做為參考實作，示範如何收集資料並將其傳送至 Firehose。代理程式會持續監控一組檔案，並將新資料傳送至 Firehose 串流。代理程式會顯示如何處理檔案輪換、檢查點和失敗時的重試。它顯示如何以可靠、及時且簡單的方式交付資料。它還顯示如何發出 CloudWatch 指標，以更好地監控和疑難排解串流程序。若要進一步了解，請參閱 [awslabs/amazon-kinesis-agent](https://github.com/awslabs/amazon-kinesis-agent)。 根據預設，記錄會從各個檔案根據換行符號 (`'\n'`) 字元進行剖析。不過，代理程式也可以設定為剖析多行記錄 (請參閱[指定代理程式組態設定](agent-config-settings.md))。 您可以在以 Linux 為基礎的伺服器環境安裝代理程式，例如 Web 伺服器、日誌伺服器，及資料庫伺服器。安裝代理程式後，透過指定要監控的檔案和資料的 Firehose 串流來設定代理程式。設定代理程式之後，它會持久地從檔案收集資料，並可靠地將其傳送至 Firehose 串流。 ## 先決條件 開始使用 Kinesis Agent 之前，請確定您符合下列先決條件。 + 您的作業系統必須是 Amazon Linux，或 Red Hat Enterprise Linux 版本 7 或更新版本。 + 2.0.0 版或更新版本代理程式執行時使用的是 JRE 1.8 版或更新版本。1.1.x 版代理程式執行時使用的是 JRE 1.7 或更新版本。 + 如果您使用 Amazon EC2 執行您的代理程式，則請啟動您的 EC2 執行個體。 + 您指定的 IAM 角色或 AWS 登入資料必須具有執行 Amazon Data Firehose [PutRecordBatch](https://docs.aws.amazon.com/firehose/latest/APIReference/API_PutRecordBatch.html) 操作的許可，代理程式才能將資料傳送至 Firehose 串流。若您啟用 CloudWatch 監控代理程式，則另需具備執行 CloudWatch [PutMetricData](https://docs.aws.amazon.com/AmazonCloudWatch/latest/APIReference/API_PutMetricData.html) 操作的許可。如需詳細資訊，請參閱 [使用 Amazon Data Firehose 控制存取](controlling-access.md)、[監控 Kinesis 代理程式運作狀態](agent-health.md) 和 [Amazon CloudWatch 身分驗證與存取控制](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/auth-and-access-control-cw.html)。 # 管理 AWS 登入資料 使用下列其中一種方法來管理您的 AWS 登入資料： + 建立自訂登入資料提供者。如需詳細資訊，請參閱[建立自訂登入資料提供者](custom-cred-provider.md)。 + 當您啟動 EC2 執行個體時，指定 IAM 角色。 + 設定代理程式時指定 AWS 登入資料 （請參閱 下組態資料表`awsSecretAccessKey`中的 `awsAccessKeyId`和 項目[指定代理程式組態設定](agent-config-settings.md))。 + 編輯 `/etc/sysconfig/aws-kinesis-agent` 以指定您的 AWS 區域和 AWS 存取金鑰。 + 如果您的 EC2 執行個體位於不同的 AWS 帳戶中，請建立 IAM 角色以提供 Amazon Data Firehose 服務的存取權。並在設定代理程式時指定該角色 (請參閱 [assumeRoleARN](agent-config-settings.md#assumeRoleARN) 和 [assumeRoleExternalId](agent-config-settings.md#assumeRoleExternalId))。使用上述其中一種方法來指定其他帳戶中具有擔任此角色許可之使用者的 AWS 登入資料。 # 建立自訂登入資料提供者 您可以在下列組態設定中建立自訂憑證提供者，並將其類別名稱和 jar 路徑指定給 Kinesis 代理程式：`userDefinedCredentialsProvider.classname` 和 `userDefinedCredentialsProvider.location`。如需這兩個組態設定的說明，請參閱[指定代理程式組態設定](agent-config-settings.md)。 若要建立自訂憑證提供者，請定義實作 `AWS CredentialsProvider` 介面的類別，如下列範例所示。 ``` import com.amazonaws.auth.AWSCredentials; import com.amazonaws.auth.AWSCredentialsProvider; import com.amazonaws.auth.BasicAWSCredentials; public class YourClassName implements AWSCredentialsProvider { public YourClassName() { } public AWSCredentials getCredentials() { return new BasicAWSCredentials("key1", "key2"); } public void refresh() { } } ``` 您的類別必須有一個不帶引數的建構函數。 AWS 會定期叫用重新整理方法，以取得更新的登入資料。如果您希望憑證提供者在其整個生命週期內提供不同的憑證，則請在此方法中包含重新整理憑證的程式碼。或者，如果您希望憑證提供者提供靜態 (不變更) 憑證，則可以將此方法保留為空。 # 下載並安裝 代理程式 首先，連接至您的執行個體。如需詳細資訊，請參閱《*Amazon EC2 使用者指南*》中的[連線至您的執行個體](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2-connect-to-instance-linux.html)。如果您在連線時遇到問題，請參閱《*Amazon EC2 使用者指南*》中的[連線至執行個體的故障診斷](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/TroubleshootingInstancesConnecting.html)。 然後，使用以下方法之一安裝代理程式。 + **從 Amazon Linux 儲存器安裝代理程式** 此方法只適用於 Amazon Linux 執行個體。使用下列命令： ``` sudo yum install –y aws-kinesis-agent ``` 2.0.0 版或更新版本代理程式安裝在具有 Amazon Linux 2 (AL2) 作業系統的電腦上。此代理程式版本需要 Java 1.8 或更新版本。如果所需的 Java 版本尚不存在，則代理程式安裝程序會安裝該版本。如需 Amazon Linux 2 的詳細資訊，請參閱 [https://aws.amazon.com/amazon-linux-2/](https://aws.amazon.com/amazon-linux-2/)。 + **從 Amazon S3 儲存器安裝代理程式** 此方法適用於 Red Hat Enterprise Linux 以及 Amazon Linux 2 執行個體，因為其會從公開的儲存器安裝代理程式。使用下列命令來下載並安裝最新版的代理程式版本 2.x.x： ``` sudo yum install –y https://s3.amazonaws.com/streaming-data-agent/aws-kinesis-agent-latest.amzn2.noarch.rpm ``` 若要安裝特定版本的代理程式，請在命令中指定版本號碼。例如，下列命令會安裝代理程式 v 2.0.1。 ``` sudo yum install –y https://streaming-data-agent.s3.amazonaws.com/aws-kinesis-agent-2.0.1-1.amzn1.noarch.rpm ``` 如果您有 Java 1.7 且不想將其升級，則可下載與 Java 1.7 相容的 1.x.x 版代理程式。例如，若要下載 1.1.6 版代理程式，您可以使用以下命令： ``` sudo yum install –y https://s3.amazonaws.com/streaming-data-agent/aws-kinesis-agent-1.1.6-1.amzn1.noarch.rpm ``` 您可以使用下列命令下載最新的代理程式 ``` sudo yum install -y https://s3.amazonaws.com/streaming-data-agent/aws-kinesis-agent-latest.amzn2.noarch.rpm ``` + **從 GitHub 儲存器安裝代理程式** 1. 首先，請確定您已安裝所需的 Java 版本，具體取決於代理程式版本。 1. 從 [awslabs/amazon-kinesis-agent](https://github.com/awslabs/amazon-kinesis-agent) GitHub 儲存器下載代理程式。 1. 瀏覽到下載目錄並執行下列命令以安裝代理程式： ``` sudo ./setup --install ``` + **若要在 Docker 容器中設定代理程式** Kinesis 代理程式也可以透過 [amazonlinux](https://docs.aws.amazon.com/AmazonECR/latest/userguide/amazon_linux_container_image.html) 容器基礎在容器中執行。使用以下 Dockerfile，然後執行 `docker build`。 ``` FROM amazonlinux RUN yum install -y aws-kinesis-agent which findutils COPY agent.json /etc/aws-kinesis/agent.json CMD ["start-aws-kinesis-agent"] ``` # 設定和啟動 代理程式 **設定和啟動代理程式** 1. 開啟並編輯組態檔案 (如果使用預設檔案存取許可，即以超級使用者身分執行)：`/etc/aws-kinesis/agent.json` 在此組態檔案中，指定代理程式收集資料的檔案 `"filePattern"` ()，以及代理程式傳送資料的 Firehose 串流名稱 `"deliveryStream"` ()。檔案名稱具備一種模式，可讓代理程式辨識檔案輪換。您可以輪換檔案或建立新的檔案，每秒不超過一次。代理程式會使用檔案建立時間戳記，來判斷要追蹤哪些檔案並結尾至 Firehose 串流。如果建立新檔案或輪換檔案的頻率超過每秒一次，將導致代理程式無法正確區分這些檔案。 ``` { "flows": [ { "filePattern": "/tmp/app.log*", "deliveryStream": "yourdeliverystream" } ] } ``` 預設 AWS 區域為 `us-east-1`。如果您使用不同的區域，請將 `firehose.endpoint` 設定新增至組態檔案，藉此指定您區域的端點。如需詳細資訊，請參閱[指定代理程式組態設定](agent-config-settings.md)。 1. 手動啟動代理程式： ``` sudo service aws-kinesis-agent start ``` 1. (選用) 設定代理程式在系統啟動時開始執行： ``` sudo chkconfig aws-kinesis-agent on ``` 代理程式現在已做為系統服務在背景執行。它會持續監控指定的檔案，並將資料傳送至指定的 Firehose 串流。代理程式的活動記錄於 `/var/log/aws-kinesis-agent/aws-kinesis-agent.log`。 # 指定代理程式組態設定 代理程式支援兩種必要的組態設定 `filePattern` 和 `deliveryStream`，以及用於其他功能的選用組態設定。您可以在 `/etc/aws-kinesis/agent.json` 指定必要及選用的組態設定。 當您變更組態檔案時，必須使用下列命令停止及啟動代理程式： ``` sudo service aws-kinesis-agent stop sudo service aws-kinesis-agent start ``` 或者，您可以使用下列命令： ``` sudo service aws-kinesis-agent restart ``` 以下是一般組態設定。 | 組態設定 | Description | | --- | --- | | assumeRoleARN | 使用者欲擔任角色的 Amazon Resource Name (ARN)。如需詳細資訊，請參閱《[IAM 使用者指南》中的使用 IAM 角色跨 AWS 帳戶委派存取權](https://docs.aws.amazon.com/IAM/latest/UserGuide/tutorial_cross-account-with-roles.html)。 ** | | assumeRoleExternalId | 選用的識別符決定誰可以擔任此角色。如需詳細資訊，請參閱《IAM 使用者指南》**中的[如何使用外部 ID](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_create_for-user_externalid.html)。 | | awsAccessKeyId | AWS 會覆寫預設登入資料的存取金鑰 ID。此設定優先於所有其他登入資料供應商。 | | awsSecretAccessKey | AWS 覆寫預設登入資料的私密金鑰。此設定優先於所有其他登入資料供應商。 | | cloudwatch.emitMetrics | 如設定為 (true)，將啟用代理程式發出指標至 CloudWatch。 預設：true | | cloudwatch.endpoint | 適用於 CloudWatch 的區域端點。 預設：`monitoring.us-east-1.amazonaws.com` | | firehose.endpoint | Amazon Data Firehose 的區域端點。 預設：`firehose.us-east-1.amazonaws.com` | | sts.endpoint | Security AWS Token Service 的區域端點。 預設：`https://sts.amazonaws.com` | | userDefinedCredentialsProvider.classname | 如果您定義自訂登入資料提供者，請使用此設定提供其完整類別名稱。不要在類別名稱的末尾包含 .class。 | | userDefinedCredentialsProvider.location | 如果您定義自訂登入資料提供者，請使用此設定來指定包含自訂登入資料提供者之 jar 的絕對路徑。代理程式也會在下列位置尋找 jar 檔案：/usr/share/aws-kinesis-agent/lib/。 | 以下是流程組態設定。 | 組態設定 | Description | | --- | --- | | aggregatedRecordSizeBytes | 若要建立代理程式彙總記錄，然後將其放入 Firehose 串流，請指定此設定。將其設定為您希望彙總記錄在代理程式將其放入 Firehose 串流之前擁有的大小。 預設值：0 (無彙總) | | dataProcessingOptions | 在傳送至 Firehose 串流之前，套用至每個剖析記錄的處理選項清單。此處理選項會在指定的資料夾執行。如需詳細資訊，請參閱[使用 代理程式預先處理資料](pre-processing.md)。 | | deliveryStream | 【必要】 Firehose 串流的名稱。 | | filePattern | [必要] 需要代理程式監控的檔案部分。符合此模式的任何檔案將由代理程式自動挑選及監控。對於符合此模式的所有檔案，請將讀取許可授與 `aws-kinesis-agent-user`。對於包含檔案的目錄，請將讀取和執行許可授與 `aws-kinesis-agent-user`。 代理程式會挑選符合此模式的任何檔案。若要確保代理程式不會挑選意外的記錄，請小心選擇此模式。 | | initialPosition | 檔案開始進行剖析的初始位置。有效值為 `START_OF_FILE` 和 `END_OF_FILE`。 預設：`END_OF_FILE` | | maxBufferAgeMillis | 代理程式在將資料傳送到 Firehose 串流之前緩衝資料的最長時間，以毫秒為單位。 數值範圍：1,000–900,000 (1 秒到 15 分鐘) 預設：60,000 (1 分鐘) | | maxBufferSizeBytes | 代理程式在將資料傳送到 Firehose 串流之前緩衝資料的大小上限，以位元組為單位。 數值範圍：1–4,194,304 (4 MB) 預設：4,194,304 (4 MB) | | maxBufferSizeRecords | 代理程式在將資料傳送到 Firehose 串流之前緩衝資料的記錄數目上限。 數值範圍：1–500 預設：500 | | minTimeBetweenFilePollsMillis | 代理程式輪詢和剖析檔案以找出新資料的時間間隔 (以毫秒為單位)。 數值範圍：1 或以上 預設：100 | | multiLineStartPattern | 用於識別記錄開始處的模式。記錄是由符合模式的一列及不符合模式的任何幾列所組成。有效值為常規運算式。根據預設，每個新日誌檔中的新列會剖析為一筆記錄。 | | skipHeaderLines | 代理程式剖析監控檔案開頭部分時略過的列數。 數值範圍：0 或以上 預設：0 (零) | | truncatedRecordTerminator | 當記錄大小超過 Amazon Data Firehose 記錄大小限制時，代理程式用來截斷已剖析記錄的字串。(1,000 KB) 預設：`'\n'` (換行符號) | # 設定多個檔案目錄和串流 透過指定多個流程組態設定，您可以設定代理程式來監控多個檔案目錄，然後將資料傳送到多個串流。在下列組態範例中，代理程式會監控兩個檔案目錄，並分別將資料傳送至 Kinesis 資料串流和 Firehose 串流。您可以為 Kinesis Data Streams 和 Amazon Data Firehose 指定不同的端點，以便您的資料串流和 Firehose 串流不需要位於相同的區域。 ``` { "cloudwatch.emitMetrics": true, "kinesis.endpoint": "https://your/kinesis/endpoint", "firehose.endpoint": "https://your/firehose/endpoint", "flows": [ { "filePattern": "/tmp/app1.log*", "kinesisStream": "yourkinesisstream" }, { "filePattern": "/tmp/app2.log*", "deliveryStream": "yourfirehosedeliverystream" } ] } ``` 如需將代理程式與 Amazon Kinesis Data Streams 搭配使用的詳細資訊，請參閱[使用 Kinesis 代理程式寫入 Amazon Kinesis Data Streams](https://docs.aws.amazon.com/kinesis/latest/dev/writing-with-agents.html)。 # 使用 代理程式預先處理資料 代理程式可以預先處理從受監控檔案剖析的記錄，然後再將其傳送到 Firehose 串流。您可以將 `dataProcessingOptions` 組態設定新增到您的檔案流程以啟用此功能。可新增一個或多個處理選項，這些選項將依照指定的順序執行。 代理程式支援以下處理選項。由於代理程式是開放原始碼，因此您可進一步開發和擴展其處理選項。您可以從 [Kinesis 代理程式](https://github.com/awslabs/amazon-kinesis-agent)下載代理程式。處理選項 `SINGLELINE` 移除換行字元、前方空格及結尾空格，藉此將多列記錄轉換為單列記錄。 ``` { "optionName": "SINGLELINE" } ``` `CSVTOJSON` 將記錄從分隔符號區隔格式轉換為 JSON 格式。 ``` { "optionName": "CSVTOJSON", "customFieldNames": [ "field1", "field2", ... ], "delimiter": "yourdelimiter" } ``` `customFieldNames` [必要] 欄位名稱在每個 JSON 鍵值對中做為鍵。例如，如果您指定 `["f1", "f2"]`，記錄「v1、v2」將轉換為 `{"f1":"v1","f2":"v2"}`。 `delimiter` 在記錄做為分隔符號的字串。預設為逗號 (,)。 `LOGTOJSON` 將記錄從日誌格式轉換為 JSON 格式。支援的日誌格式為 **Apache Common Log**、**Apache Combined Log**、**Apache Error Log**、以及 **RFC3164 Syslog**。 ``` { "optionName": "LOGTOJSON", "logFormat": "logformat", "matchPattern": "yourregexpattern", "customFieldNames": [ "field1", "field2", … ] } ``` `logFormat` [必要] 日誌項目格式。以下是可能的值： + `COMMONAPACHELOG` – Apache Common Log 格式。根據預設，每個日誌項目皆有以下模式：「`%{host} %{ident} %{authuser} [%{datetime}] \"%{request}\" %{response} %{bytes}`」。 + `COMBINEDAPACHELOG` – Apache Combined Log 格式。根據預設，每個日誌項目皆有以下模式：「`%{host} %{ident} %{authuser} [%{datetime}] \"%{request}\" %{response} %{bytes} %{referrer} %{agent}`」。 + `APACHEERRORLOG` – Apache Error Log 格式。根據預設，每個日誌項目皆有以下模式：「`[%{timestamp}] [%{module}:%{severity}] [pid %{processid}:tid %{threadid}] [client: %{client}] %{message}`」。 + `SYSLOG` – RFC3164 Syslog 格式。根據預設，每個日誌項目皆有以下模式：「`%{timestamp} %{hostname} %{program}[%{processid}]: %{message}`」。 `matchPattern` 覆寫指定日誌格式的預設模式。如果日誌項目使用自訂格式，則使用此設定從日誌項目擷取值。若您指定 `matchPattern`，您也必須指定 `customFieldNames`。 `customFieldNames` 自訂欄位名稱在每個 JSON 鍵值對中做為鍵。您可以使用此設定來定義從 `matchPattern` 擷取的值的欄位名稱，或覆寫預先定義的日誌格式的預設欄位名稱。 **Example ：LOGTOJSON 組態** 這裡提供一個 Apache Common Log 項目轉換為 JSON 格式的 `LOGTOJSON` 組態範例： ``` { "optionName": "LOGTOJSON", "logFormat": "COMMONAPACHELOG" } ``` 轉換前： ``` 64.242.88.10 - - [07/Mar/2004:16:10:02 -0800] "GET /mailman/listinfo/hsdivision HTTP/1.1" 200 6291 ``` 轉換後： ``` {"host":"64.242.88.10","ident":null,"authuser":null,"datetime":"07/Mar/2004:16:10:02 -0800","request":"GET /mailman/listinfo/hsdivision HTTP/1.1","response":"200","bytes":"6291"} ``` **Example ：使用自訂欄位的 LOGTOJSON 組態** 以下是另一個 `LOGTOJSON` 組態範例： ``` { "optionName": "LOGTOJSON", "logFormat": "COMMONAPACHELOG", "customFieldNames": ["f1", "f2", "f3", "f4", "f5", "f6", "f7"] } ``` 使用此組態設定，前一個範例的相同 Apache Common Log 項目轉換為 JSON 格式如下： ``` {"f1":"64.242.88.10","f2":null,"f3":null,"f4":"07/Mar/2004:16:10:02 -0800","f5":"GET /mailman/listinfo/hsdivision HTTP/1.1","f6":"200","f7":"6291"} ``` **Example ：轉換 Apache Common Log 項目** 下列流程組態將 Apache Common Log 項目轉換為 JSON 格式的單列記錄： ``` { "flows": [ { "filePattern": "/tmp/app.log*", "deliveryStream": "my-delivery-stream", "dataProcessingOptions": [ { "optionName": "LOGTOJSON", "logFormat": "COMMONAPACHELOG" } ] } ] } ``` **Example ：轉換多列記錄** 以下流程組態剖析第一行從「`[SEQUENCE=`」開始的多列記錄。每筆記錄都會先轉換為單列記錄。然後，根據定位鍵分隔符號從記錄中擷取值。擷取的值會對應到指定的 `customFieldNames` 值以形成 JSON 格式的單列記錄。 ``` { "flows": [ { "filePattern": "/tmp/app.log*", "deliveryStream": "my-delivery-stream", "multiLineStartPattern": "\\[SEQUENCE=", "dataProcessingOptions": [ { "optionName": "SINGLELINE" }, { "optionName": "CSVTOJSON", "customFieldNames": [ "field1", "field2", "field3" ], "delimiter": "\\t" } ] } ] } ``` **Example ：使用匹配模式的 LOGTOJSON 組態** 以下是 Apache Common Log 項目轉換為 JSON 格式的 `LOGTOJSON` 組態範例，省略最後欄位 (位元組)： ``` { "optionName": "LOGTOJSON", "logFormat": "COMMONAPACHELOG", "matchPattern": "^([\\d.]+) (\\S+) (\\S+) \\[([\\w:/]+\\s[+\\-]\\d{4})\\] \"(.+?)\" (\\d{3})", "customFieldNames": ["host", "ident", "authuser", "datetime", "request", "response"] } ``` 轉換前： ``` 123.45.67.89 - - [27/Oct/2000:09:27:09 -0400] "GET /java/javaResources.html HTTP/1.0" 200 ``` 轉換後： ``` {"host":"123.45.67.89","ident":null,"authuser":null,"datetime":"27/Oct/2000:09:27:09 -0400","request":"GET /java/javaResources.html HTTP/1.0","response":"200"} ``` # 使用常見的 Agent CLI 命令 下表提供一組常用案例和對應的命令，用於使用 AWS Kinesis 代理程式。 | 使用案例 | 命令 | | --- | --- | | 在系統啟動時自動啟動代理程式 | 
sudo chkconfig aws-kinesis-agent on
| | 檢查客服人員的狀態 | 
sudo service aws-kinesis-agent status
| | 停止代理程式 | 
sudo service aws-kinesis-agent stop
| | 從此位置讀取代理程式的日誌檔案 | 
/var/log/aws-kinesis-agent/aws-kinesis-agent.log
| | 解除安裝代理程式 | 
sudo yum remove aws-kinesis-agent
| # 從 Kinesis Agent 傳送時的問題故障診斷 此表格針對使用 Amazon Kinesis Agent 時遇到的常見問題，提供疑難排解資訊和解決方案。 | 問題 | 解決方案 | | --- | --- | | 為什麼 Kinesis 代理程式無法在 Windows 上運作？ | [適用於 Windows 的 Kinesis 代理程式](https://docs.aws.amazon.com/kinesis-agent-windows/latest/userguide/what-is-kinesis-agent-windows.html)是不同於適用於 Linux 平台的 Kinesis 代理程式的軟體。 | | 為什麼 Kinesis 代理程式會減速和/或 RecordSendErrors 增加？ | 這通常是由於來自 Kinesis 的限流。檢查 Kinesis Data Streams 的 `WriteProvisionedThroughputExceeded` 指標或 Firehose 串流的 `ThrottledRecords` 指標。這些指標中從 0 開始的任何增量，均表示需要提升串流限制。如需詳細資訊，請參閱 [Kinesis Data Stream 限制](https://docs.aws.amazon.com/streams/latest/dev/service-sizes-and-limits.html)和 [Firehose 串流](https://docs.aws.amazon.com/firehose/latest/dev/limits.html)。 排除限流之後，請查看 Kinesis 代理程式是否設定為追蹤大量小型檔案。Kinesis 代理程式追蹤新檔案時會有延遲，因此 Kinesis 代理程式應追蹤少量較大的檔案。嘗試將日誌檔案合併至較大的檔案中。 | | 如何解決java.lang.OutOfMemoryError例外狀況？ | 當 Kinesis Agent 沒有足夠的記憶體來處理其目前的工作負載時，就會發生這種情況。嘗試增加 /usr/bin/start-aws-kinesis-agent 中的 JAVA\$1START\$1HEAP 和 JAVA\$1MAX\$1HEAP 並重新啟動代理程式。 | | 如何解決IllegalStateException : connection pool shut down例外狀況？ | Kinesis 代理程式沒有足夠的連線可以處理其目前的工作負載。嘗試在位於 /etc/aws-kinesis/agent.json 的一般代理程式組態設定中增加 maxConnections 和 maxSendingThreads。這些欄位的預設值是可用執行期處理器的 12 倍。如需進階代理程式組態設定的詳細資訊，請參閱 [AgentConfiguration.java](https://github.com/awslabs/amazon-kinesis-agent/blob/master/src/com/amazon/kinesis/streaming/agent/config/AgentConfiguration.java)。 | | 如何使用 Kinesis 代理程式對另一個問題進行偵錯？ | 可以在 /etc/aws-kinesis/log4j.xml 中啟用 DEBUG 層級日誌。 | | 我應該如何對 Kinesis Agent 進行設定？ | maxBufferSizeBytes 越小，Kinesis 代理程式傳送資料的頻率就越高。這可能很好，因為這樣會減少記錄的交付時間，但也增加了 Kinesis 的每秒請求。 | | 為什麼 Kinesis 代理程式傳送重複的日誌？ | 發生這種情況是由於檔案追蹤組態錯誤。請確保每個 fileFlow’s filePattern 僅與一個檔案相符。如果正在 copytruncate 模式中使用 logrotate 模式下，也可能發生這種情況。嘗試將模式變更為預設模式，或建立模式以避免重複。如需有關處理重複記錄的詳細資訊，請參閱[處理重複記錄](https://docs.aws.amazon.com/streams/latest/dev/kinesis-record-processor-duplicates.html)。 | # 使用 AWS SDK 傳送資料 您可以使用 [Amazon Data Firehose API](https://docs.aws.amazon.com/firehose/latest/APIReference/)，使用[AWS 適用於 Java](https://aws.amazon.com/sdk-for-java/)、.[NET](https://aws.amazon.com/sdk-for-net/)、[Node.js](https://aws.amazon.com/sdk-for-javascript/)、[Python](https://aws.amazon.com/sdk-for-python/) 或 [Ruby](https://aws.amazon.com/sdk-for-ruby/) 的 SDK 將資料傳送至 Firehose 串流。如果您是初次使用 Amazon Data Firehose，請花一些時間熟悉 中介紹的概念和術語[什麼是 Amazon Data Firehose？](what-is-this-service.md)。如需詳細資訊，請參閱 [Amazon Web Services 開發功能入門](https://aws.amazon.com/developers/getting-started/)。 這些範例不代表可立即生產的程式碼，無法檢查出所有可能的例外狀況，也不可視為任何潛在安全或效能疑慮的原因。 Amazon Data Firehose API 提供兩個將資料傳送至 Firehose 串流的操作：[PutRecord](https://docs.aws.amazon.com/firehose/latest/APIReference/API_PutRecord.html) 和 [PutRecordBatch](https://docs.aws.amazon.com/firehose/latest/APIReference/API_PutRecordBatch.html)。 會在一次呼叫中`PutRecord()`傳送一個資料記錄，而且`PutRecordBatch()`可以在一次呼叫中傳送多個資料記錄。 ## 使用 PutRecord 的單一寫入操作 放置資料只需要 Firehose 串流名稱和位元組緩衝區 (<=1000 KB)。由於 Amazon Data Firehose 會在將檔案載入 Amazon S3 之前批次處理多個記錄，因此您可能想要新增記錄分隔符號。若要將資料一次一個記錄放入 Firehose 串流，請使用下列程式碼： ``` PutRecordRequest putRecordRequest = new PutRecordRequest(); putRecordRequest.setDeliveryStreamName(deliveryStreamName); String data = line + "\n"; Record record = new Record().withData(ByteBuffer.wrap(data.getBytes())); putRecordRequest.setRecord(record); // Put record into the DeliveryStream firehoseClient.putRecord(putRecordRequest); ``` 如需更多程式碼內容，請參閱 AWS SDK 中包含的範例程式碼。如需有關請求和回應語法的資訊，請參閱 [Firehose API Operations](https://docs.aws.amazon.com/firehose/latest/APIReference/API_Operations.html) 中的相關主題。 ## 使用 PutRecordBatch 的批次寫入操作 放置資料只需要 Firehose 串流名稱和記錄清單。由於 Amazon Data Firehose 會在將檔案載入 Amazon S3 之前批次處理多個記錄，因此您可能想要新增記錄分隔符號。若要將批次資料記錄放入 Firehose 串流，請使用下列程式碼： ``` PutRecordBatchRequest putRecordBatchRequest = new PutRecordBatchRequest(); putRecordBatchRequest.setDeliveryStreamName(deliveryStreamName); putRecordBatchRequest.setRecords(recordList); // Put Record Batch records. Max No.Of Records we can put in a // single put record batch request is 500 firehoseClient.putRecordBatch(putRecordBatchRequest); recordList.clear(); ``` 如需更多程式碼內容，請參閱 AWS SDK 中包含的範例程式碼。如需請求和回應語法的相關資訊，請參閱 [Firehose API Operations](https://docs.aws.amazon.com/firehose/latest/APIReference/API_Operations.html) 中的相關主題。 # 將 CloudWatch Logs 傳送至 Firehose CloudWatch Logs 事件可以使用 CloudWatch 訂閱篩選條件傳送至 Firehose。如需詳細資訊，請參閱[使用 Amazon Data Firehose 訂閱篩選條件](https://docs.aws.amazon.com/AmazonCloudWatch/latest/logs/SubscriptionFilters.html#FirehoseExample)。 CloudWatch Logs 事件會以壓縮的 gzip 格式傳送至 Firehose。如果您想要將解壓縮的日誌事件交付至 Firehose 目的地，您可以使用 Firehose 中的解壓縮功能自動解壓縮 CloudWatch Logs。 **重要** 目前，Firehose 不支援將 CloudWatch Logs 交付至 Amazon OpenSearch Service 目的地，因為 Amazon CloudWatch 將多個日誌事件合併為一個 Firehose 記錄，Amazon OpenSearch Service 無法接受一個記錄中的多個日誌事件。作為替代方案，您可以考慮[在 CloudWatch Logs 中使用 Amazon OpenSearch Service 的訂閱篩選條件](https://docs.aws.amazon.com/AmazonCloudWatch/latest/logs/CWL_OpenSearch_Stream.html)。 # 解壓縮 CloudWatch Logs 如果您使用 Firehose 交付 CloudWatch Logs 並想要將解壓縮的資料交付至 Firehose 串流目的地，請使用 Firehose [Data Format Conversion](https://docs.aws.amazon.com/firehose/latest/dev/data-transformation.html) (Parquet、ORC) 或[動態分割](https://docs.aws.amazon.com/firehose/latest/dev/dynamic-partitioning.html)。您必須為 Firehose 串流啟用解壓縮。 您可以使用 AWS 管理主控台 AWS Command Line Interface 或 AWS SDKs啟用解壓縮。 **注意** 如果您在串流上啟用解壓縮功能，請僅將該串流用於 CloudWatch Logs 訂閱篩選條件，而不是用於已取代的日誌。如果您在用來同時擷取 CloudWatch Logs 和 Vended Logs 的串流上啟用解壓縮功能，則 Vended Logs 擷取至 Firehose 失敗。此解壓縮功能僅適用於 CloudWatch Logs。 # 解壓縮 CloudWatch Logs 後擷取訊息 當您啟用解壓縮時，您也可以選擇啟用訊息擷取。使用訊息擷取時，Firehose 會從解壓縮的 CloudWatch Logs 記錄中篩選掉所有中繼資料，例如擁有者、日誌群組、日誌串流和其他中繼資料，並僅傳遞訊息欄位中的內容。如果您要將資料交付至 Splunk 目的地，您必須開啟訊息擷取，Splunk 才能剖析資料。以下是使用和不使用訊息擷取解壓縮後的範例輸出。 圖 1：解壓縮後未擷取訊息的範例輸出： ``` { "owner": "111111111111", "logGroup": "CloudTrail/logs", "logStream": "111111111111_CloudTrail/logs_us-east-1", "subscriptionFilters": [ "Destination" ], "messageType": "DATA_MESSAGE", "logEvents": [ { "id": "31953106606966983378809025079804211143289615424298221568", "timestamp": 1432826855000, "message": "{\"eventVersion\":\"1.03\",\"userIdentity\":{\"type\":\"Root1\"}" }, { "id": "31953106606966983378809025079804211143289615424298221569", "timestamp": 1432826855000, "message": "{\"eventVersion\":\"1.03\",\"userIdentity\":{\"type\":\"Root2\"}" }, { "id": "31953106606966983378809025079804211143289615424298221570", "timestamp": 1432826855000, "message": "{\"eventVersion\":\"1.03\",\"userIdentity\":{\"type\":\"Root3\"}" } ] } ``` 圖 2：使用訊息擷取解壓縮後的範例輸出： ``` {"eventVersion":"1.03","userIdentity":{"type":"Root1"} {"eventVersion":"1.03","userIdentity":{"type":"Root2"} {"eventVersion":"1.03","userIdentity":{"type":"Root3"} ``` # 從主控台對新的 Firehose 串流啟用解壓縮 **使用 在新的 Firehose 串流上啟用解壓縮 AWS 管理主控台** 1. 登入 AWS 管理主控台 並開啟位於 https：//[https://console.aws.amazon.com/kinesis](https://console.aws.amazon.com/kinesis) 的 Kinesis 主控台。 1. 在導覽窗格中選擇 **Amazon Data Firehose**。 1. 選擇**建立 Firehose 串流**。 1. 在**選擇來源和目的地**下 ****來源**** Firehose 串流的來源。選擇下列其中一個來源： + **直接 PUT** – 選擇此選項可建立生產者應用程式直接寫入的 Firehose 串流。如需與 Firehose 中的 Direct PUT 整合的 服務和代理程式和開放原始碼服務清單 AWS ，請參閱[本節](create-name.md)。 + **Kinesis 串流：**選擇此選項可設定使用 Kinesis 資料串流做為資料來源的 Firehose 串流。然後，您可以使用 Firehose 輕鬆從現有的 Kinesis 資料串流讀取資料，並將其載入目的地。如需詳細資訊，請參閱[使用 Kinesis Data Streams 寫入 Firehose](https://docs.aws.amazon.com/firehose/latest/dev/writing-with-kinesis-streams.html) ****目的地**** Firehose 串流的目的地。選擇下列其中一項： + Amazon S3 + Splunk 1. 在 **Firehose 串流名稱**下，輸入串流的名稱。 1. （選用） 在**轉換記錄**下： + 在**從 Amazon CloudWatch Logs 解壓縮來源記錄**區段中，選擇**開啟解壓縮**。 + 如果您想要在解壓縮後使用訊息擷取，請選擇**開啟訊息擷取**。 # 在現有的 Firehose 串流上啟用解壓縮 本節提供在現有 Firehose 串流上啟用解壓縮的指示。它涵蓋兩個案例：已停用 Lambda 處理的串流，以及已啟用 Lambda 處理的串流。以下各節概述每個案例的step-by-step程序，包括 Lambda 函數的建立或修改、更新 Firehose 設定，以及監控 CloudWatch 指標，以確保成功實作內建的 Firehose 解壓縮功能。 ## 停用 Lambda 處理時啟用解壓縮 若要在停用 Lambda 處理的現有 Firehose 串流上啟用解壓縮，您必須先啟用 Lambda 處理。此條件僅適用於現有的串流。下列步驟顯示如何在未啟用 Lambda 處理的現有串流上啟用解壓縮。 1. 建立 Lambda 函式。您可以建立傳遞的虛擬記錄，也可以使用此[藍圖](https://github.com/aws-samples/aws-kinesis-firehose-resources/tree/main/blueprints/kinesis-firehose-cloudwatch-logs-processor)建立新的 Lambda 函數。 1. 更新您目前的 Firehose 串流以啟用 Lambda 處理，並使用您建立用於處理的 Lambda 函數。 1. 使用新的 Lambda 函數更新串流後，請返回 Firehose 主控台並啟用解壓縮。 1. 停用您在步驟 1 中啟用的 Lambda 處理。您現在可以刪除您在步驟 1 中建立的函數。 ## 啟用 Lambda 處理時啟用解壓縮 如果您已有具有 Lambda 函數的 Firehose 串流，若要執行解壓縮，您可以將其取代為 Firehose 解壓縮功能。在繼續之前，請檢閱您的 Lambda 函數程式碼，以確認其僅執行解壓縮或訊息擷取。Lambda 函數的輸出看起來應該類似於[圖 1 或圖 2 ](Message_extraction.md)所示的範例。如果輸出看起來類似，您可以使用下列步驟取代 Lambda 函數。 1. 使用此[藍圖](https://github.com/aws-samples/aws-kinesis-firehose-resources/tree/main/blueprints/kinesis-firehose-cloudwatch-logs-processor)取代您目前的 Lambda 函數。新的藍圖 Lambda 函數會自動偵測傳入的資料是壓縮還是解壓縮。只有在壓縮其輸入資料時，才會執行解壓縮。 1. 使用內建的 Firehose 選項開啟解壓縮以解壓縮。 1. 如果尚未啟用，請為您的 Firehose 串流啟用 CloudWatch 指標。監控指標`CloudWatchProcessorLambda_IncomingCompressedData`並等到此指標變更為零。這會確認傳送至 Lambda 函數的所有輸入資料都已解壓縮，而且不再需要 Lambda 函數。 1. 移除 Lambda 資料轉換，因為您不再需要它來解壓縮串流。 # 在 Firehose 串流上停用解壓縮 **** 使用 在資料串流上停用解壓縮 AWS 管理主控台 1. 登入 AWS 管理主控台 並開啟位於 https：//[https://console.aws.amazon.com/kinesis](https://console.aws.amazon.com/kinesis) 的 Kinesis 主控台。 1. 在導覽窗格中選擇 **Amazon Data Firehose**。 1. 選擇您要編輯的 Firehose 串流。 1. 在 **Firehose 串流詳細資訊**頁面上，選擇**組態**索引標籤。 1. 在**轉換和轉換記錄**區段中，選擇**編輯**。 1. **在從 Amazon CloudWatch Logs 解壓縮來源記錄**下，清除**開啟解壓縮**，然後選擇**儲存變更**。 # 針對 Firehose 中的解壓縮進行故障診斷 下表顯示 Firehose 在資料解壓縮和處理期間如何處理錯誤，包括將記錄交付至錯誤 S3 儲存貯體、記錄錯誤和發出指標。它還說明針對未經授權的資料放置操作傳回的錯誤訊息。 | 問題 | 解決方案 | | --- | --- | | 如果在解壓縮期間發生錯誤，來源資料會發生什麼情況？ | 如果 Amazon Data Firehose 無法解壓縮記錄，記錄會依原狀 （壓縮格式） 交付，以便在 Firehose 串流建立時間期間指定的 S3 儲存貯體發生錯誤。除了記錄之外，交付的物件也包含錯誤碼和錯誤訊息，而且這些物件會交付到名為 的 S3 儲存貯體字首`decompression-failed`。Firehose 會在記錄解壓縮失敗後繼續處理其他記錄。 | | 如果成功解壓縮後處理管道發生錯誤，來源資料會發生什麼情況？ | 如果在解壓縮如動態分割和資料格式轉換等處理步驟中，Amazon Data Firehose 發生錯誤，記錄會以壓縮格式交付到您在 Firehose 串流建立時間期間指定的錯誤 S3 儲存貯體。除了記錄之外，交付的物件也包含錯誤碼和錯誤訊息。 | | 如果發生錯誤或例外狀況，您會如何收到通知？ | 如果在解壓縮期間發生錯誤或例外狀況，如果您設定 CloudWatch Logs，Firehose 會將錯誤訊息記錄到 CloudWatch Logs。此外，Firehose 會將指標傳送至您可以監控的 CloudWatch 指標。您也可以根據 Firehose 發出的指標選擇性地建立警示。 | | 當put操作不是來自 CloudWatch Logs 時會發生什麼情況？ | 當客戶puts不是來自 CloudWatch Logs 時，會傳回下列錯誤訊息：
Put to Firehose failed for AccountId: , FirehoseName:   because the request is not originating from allowed source types.
| | Firehose 針對解壓縮功能發出哪些指標？ | Firehose 會發出每個記錄的解壓縮指標。您應該選取期間 (1 分鐘）、統計資料 （總和）、日期範圍，以取得DecompressedRecords失敗、成功或DecompressedBytes失敗或成功的數量。如需詳細資訊，請參閱[CloudWatch Logs 解壓縮指標](monitoring-with-cloudwatch-metrics.md#decompression-metrics-cw)。 | # 將 CloudWatch 事件傳送至 Firehose 您可以將目標新增至 Amazon CloudWatch CloudWatch 將事件傳送至 Firehose 串流。 **為將事件傳送至現有 Firehose 串流的 CloudWatch Events 規則建立目標** 1. 登入 AWS 管理主控台 ，並在 https：//[https://console.aws.amazon.com/cloudwatch/](https://console.aws.amazon.com/cloudwatch/) 開啟 CloudWatch 主控台。 1. 選擇**建立規則**。 1. 在**步驟 1：建立規則**頁面上，針對**目標**選擇**新增目標**，然後選擇 **Firehose 串流**。 1. 選擇現有的 **Firehose 串流**。 如需建立 CloudWatch Events 規則的詳細資訊，請參閱 [Amazon CloudWatch Events 入門](https://docs.aws.amazon.com/AmazonCloudWatch/latest/events/CWE_GettingStarted.html)。 # 設定 AWS IoT 將資料傳送至 Firehose 您可以藉由新增 動作 AWS IoT ，將 設定為將資訊傳送至 Firehose 串流。 **建立將事件傳送至現有 Firehose 串流的動作** 1. 在 AWS IoT 主控台中建立規則時，請在**建立規則**頁面**的設定一或多個動作**下，選擇**新增動作**。 1. 選擇**將訊息傳送至 Amazon Kinesis Firehose 串流**。 1. 選擇 **Configure action (設定動作)**。 1. 針對**串流名稱**，選擇現有的 Firehose 串流。 1. 在 **Separator (分隔符號)** 的部分，選擇欲插入記錄間的分隔符號字元。 1. 對於 **IAM 角色名稱**，選擇現有 IAM 角色或選擇**建立新角色**。 1. 選擇**新增動作**。 如需建立 AWS IoT 規則的詳細資訊，請參閱 [AWS IoT 規則教學課程](https://docs.aws.amazon.com/iot/latest/developerguide/iot-rules-tutorial.html)。