Kinesis 劑 - Amazon 數據 Firehose

將亞馬遜資料 Firehose 串流交付到 Amazon S3 中的 Apache 冰山表格已處於預覽狀態，且可能會有所變更。

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

Kinesis 劑

Amazon Kinesis 代理程式是獨立的 Java 軟體應用程式，可做為參考實作，顯示如何收集資料並將其傳送至 Firehose。代理程式會持續監控一組檔案，並將新資料傳送至您的 Firehose 串流。代理程式會顯示如何處理檔案輪替、檢查點和失敗時重試。它顯示了如何以可靠，及時和簡單的方式交付數據。它還顯示如何發出 CloudWatch指標，以更好地監控和疑難排解串流程序。要了解更多信息，awslab/ amazon-kinesis-agent.

根據預設，記錄會從各個檔案根據換行符號 ('\n') 字元進行剖析。不過，代理程式也可以設定為剖析多行記錄 (請參閱用戶端組態設定)。

您可以在以 Linux 為基礎的伺服器環境安裝代理程式，例如 Web 伺服器、日誌伺服器，及資料庫伺服器。安裝代理程式之後，請指定要監視的檔案和 Firehose 串流來設定代理程式。代理程式設定完成後，會持久地從檔案收集資料，並可靠地將其傳送至 Firehose 串流。

主題

    • 您的作業系統必須是 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 資料 Firehose PutRecordBatch操作的權限，代理程式才能將資料傳送至您的 Firehose 串流。如果您啟用代理程式的 CloudWatch 監視，則還需要執行 CloudWatch PutMetricData作業的權限。如需詳細資訊，請參閱 Amazon 的使用 Amazon 資料 Firehose 控制存取監控 Kinesis 劑健康狀況、以及身份驗證和存取控制 CloudWatch。

    使用下列其中一種方法管理您的 AWS 認證：

    • 建立自訂登入資料提供者。如需詳細資訊，請參閱 建立自訂認證提供者。

    • 在啟動執行個EC2體時指定IAM角色。

    • 在設定代理程式時指定 AWS 身份證明 (請參閱下方組態表格awsSecretAccessKey中的awsAccessKeyId和項目用戶端組態設定)。

    • 編輯/etc/sysconfig/aws-kinesis-agent以指定您的 AWS 區域和 AWS 存取金鑰。

    • 如果您的EC2執行個體位於不同的 AWS 帳戶中，請建立IAM角色以提供 Amazon Data Firehose 服務的存取權。在設定代理程式時指定該角色（請參閱assumeRoleARN和 assumeRoleExternalId）。使用上述方法之一來指定其他帳戶中有權擔任此角色之使用者的 AWS 認證。

    您可以在下列組態設定中建立自訂憑證提供者，並將其類別名稱和 jar 路徑指定給 Kinesis 代理程式：userDefinedCredentialsProvider.classname 和 userDefinedCredentialsProvider.location。如需這兩個組態設定的說明，請參閱用戶端組態設定。

    若要建立自訂憑證提供者，請定義實作 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 使用者指南中的 Connect 到您的執行個體。如果連線時遇到問題，請參閱 Amazon EC2 使用者指南中的疑難排解連線至執行個體。

    然後，使用以下方法之一安裝代理程式。

    • 從 Amazon Linux 儲存器安裝代理程式

      此方法只適用於 Amazon Linux 執行個體。使用下列命令：

      
sudo yum install –y aws-kinesis-agent

      代理程式 v 2.0.0 或更新版本已安裝在具有作業系統的電腦上 Amazon Linux 2 (AL2)。此代理程式版本需要 Java 1.8 或更新版本。如果所需的 Java 版本尚不存在，則代理程式安裝程序會安裝該版本。有關 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

      使用以下命令可下載最新的 1.x.x 版代理程式：

      
sudo yum install –y https://s3.amazonaws.com/streaming-data-agent/aws-kinesis-agent-latest.amzn1.noarch.rpm

    • 若要從 GitHub存放庫設定代理程式

      1. 首先，請確定您已安裝所需的 Java 版本，具體取決於代理程式版本。

      2. 從 awslab amazon-kinesis-agent GitHub /軟體庫下載代理程式。

      3. 瀏覽到下載目錄並執行下列命令以安裝代理程式：

        
sudo ./setup --install
    • 若要在 Docker 容器中設定代理程式

      Kinesis 代理程式也可以透過 amazonlinux 容器基礎在容器中執行。使用以下 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 設定新增至組態檔案，藉此指定您區域的端點。如需詳細資訊，請參閱用戶端組態設定。

    2. 手動啟動代理程式：

      sudo service aws-kinesis-agent start

    3. (選用) 設定代理程式在系統啟動時開始執行：

      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

    以下是一般組態設定。

    組態設定 描述
    assumeRoleARN

    使用者所承擔ARN之角色的 Amazon 資源名稱 ()。如需詳細資訊，請參閱使用指南中的使用IAM角色在 AWS 帳戶之間委派存取權。IAM
    assumeRoleExternalId

    選用的識別符決定誰可以擔任此角色。若要取得更多資訊，請參閱《使用指南》中的如何使IAM用外部 ID。
    awsAccessKeyId

    AWS 覆寫預設認證的存取金鑰 ID。此設定優先於所有其他登入資料供應商。
    awsSecretAccessKey

    AWS 覆寫預設認證的密鑰。此設定優先於所有其他登入資料供應商。
    cloudwatch.emitMetrics

    啟用代理程式發出指標 (如 CloudWatch 果設定為 true)。

    預設：true
    cloudwatch.endpoint

    的區域端點 CloudWatch。

    預設：monitoring.us-east-1.amazonaws.com
    firehose.endpoint

    Amazon 數據 Firehose 的區域端點。

    預設：firehose.us-east-1.amazonaws.com
    sts.endpoint

    AWS 保安編碼器服務的地區端點。

    預設：https://sts.amazonaws.com
    userDefinedCredentialsProvider.classname 如果您定義自訂登入資料提供者，請使用此設定提供其完整類別名稱。不要在類別名稱的末尾包含 .class。
    userDefinedCredentialsProvider.location 如果您定義自訂登入資料提供者，請使用此設定來指定包含自訂登入資料提供者之 jar 的絕對路徑。代理程式也會在下列位置尋找 jar 檔案：/usr/share/aws-kinesis-agent/lib/。

    以下是流程組態設定。

    組態設定 描述
    aggregatedRecordSizeBytes

    若要讓代理程式彙總記錄，然後在一次作業中將其放入 Firehose 串流，請指定此設定。將其設定為您希望在代理程式將彙總記錄放入 Firehose 串流之前具有的大小。

    預設值：0 (無彙總)
    dataProcessingOptions

    在傳送至 Firehose 串流之前，會套用至每個已剖析記錄的處理選項清單。此處理選項會在指定的資料夾執行。如需詳細資訊，請參閱使用代理程式預先處理資料。
    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 資料串流和 Amazon 資料 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。

    代理程式可以預先處理從受監控檔案剖析的記錄，然後再將這些記錄傳送至 Firehose 串流。您可以將 dataProcessingOptions 組態設定新增到您的檔案流程以啟用此功能。可新增一個或多個處理選項，這些選項將依照指定的順序執行。

    代理程式支援以下處理選項。由於代理程式是開放原始碼，因此您可進一步開發和擴展其處理選項。您可以從 Kinesis 代理程式下載代理程式。

    處理選項
    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日誌格式。根據預設，每個日誌項目皆有以下模式：「%{timestamp} %{hostname} %{program}[%{processid}]: %{message}」。

    matchPattern

    覆寫指定日誌格式的預設模式。如果日誌項目使用自訂格式，則使用此設定從日誌項目擷取值。若您指定 matchPattern，您也必須指定 customFieldNames。

    customFieldNames

    用作每JSON個鍵值對中鍵的自定義字段名稱。您可以使用此設定來定義從 matchPattern 擷取的值的欄位名稱，或覆寫預先定義的日誌格式的預設欄位名稱。

    範例 : LOGTOJSON 配置

    以下是轉換成JSON格式的 Apache 通用記錄項目的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"}
    範例 ：使用自定義字段LOGTOJSON配置

    以下是另一個 LOGTOJSON 組態範例：

    {
    "optionName": "LOGTOJSON",
    "logFormat": "COMMONAPACHELOG",
    "customFieldNames": ["f1", "f2", "f3", "f4", "f5", "f6", "f7"]
}

    使用此組態設定時，先前範例中相同的 Apache 通用記錄項目會轉換為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"}
    範例 ：轉換 Apache Common Log 項目

    下列流程設定會以JSON格式將 Apache 通用記錄項目轉換為單行記錄：

    { 
    "flows": [
        {
            "filePattern": "/tmp/app.log*", 
            "deliveryStream": "my-delivery-stream",
            "dataProcessingOptions": [
                {
                    "optionName": "LOGTOJSON",
                    "logFormat": "COMMONAPACHELOG"
                }
            ]
        }
    ] 
}
    範例 ：轉換多列記錄

    以下流程組態剖析第一行從「[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"
                }
            ]
        }
    ] 
}
    範例 ：LOGTOJSON配置匹配模式

    以下是轉換為JSON格式的 Apache 通用記錄項目的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"}

    在系統啟動時自動啟動代理程式。

    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

    是否有適用於 Windows 的 Kinesis 代理程式？

    適用於 Windows 的 Kinesis 代理程式是不同於適用於 Linux 平台的 Kinesis 代理程式的軟體。

    為什麼 Kinesis 代理程式會減速和/或 RecordSendErrors 增加？

    這通常是由於來自 Kinesis 的限流。檢查 Kinesis Data Streams 的WriteProvisionedThroughputExceeded量度或 Firehose 串流的ThrottledRecords量度。這些指標中從 0 開始的任何增量，均表示需要提升串流限制。如需詳細資訊，請參閱 Kinesis 資料串流限制和 Firehose 串流。

    排除限流之後，請查看 Kinesis 代理程式是否設定為追蹤大量小型檔案。Kinesis 代理程式追蹤新檔案時會有延遲，因此 Kinesis 代理程式應追蹤少量較大的檔案。嘗試將日誌檔案合併至較大的檔案中。

    為什麼我會遇到 java.lang.OutOfMemoryError 例外狀況？

    Kinesis 代理程式沒有足夠的記憶體可以處理其目前的工作負載。嘗試增加 /usr/bin/start-aws-kinesis-agent 中的 JAVA_START_HEAP 和 JAVA_MAX_HEAP 並重新啟動代理程式。

    為什麼我會遇到 IllegalStateException : connection pool shut down 例外狀況？

    Kinesis 代理程式沒有足夠的連線可以處理其目前的工作負載。嘗試在位於 /etc/aws-kinesis/agent.json 的一般代理程式組態設定中增加 maxConnections 和 maxSendingThreads。這些欄位的預設值是可用執行期處理器的 12 倍。如需進階用戶端組態設定的詳細資訊，請參閱 AgentConfiguration.java。

    如何使用 Kinesis 代理程式對另一個問題進行偵錯？

    可以在 /etc/aws-kinesis/log4j.xml 中啟用 DEBUG 層級日誌。

    我應該如何對 Kinesis Agent 進行設定？

    maxBufferSizeBytes 越小，Kinesis 代理程式傳送資料的頻率就越高。這可能很好，因為這樣會減少記錄的交付時間，但也增加了 Kinesis 的每秒請求。

    為什麼 Kinesis 代理程式傳送重複的日誌？

    發生這種情況是由於檔案追蹤組態錯誤。請確保每個 fileFlow’s filePattern 僅與一個檔案相符。如果正在 copytruncate 模式中使用 logrotate 模式下，也可能發生這種情況。嘗試將模式變更為預設模式，或建立模式以避免重複。如需有關處理重複記錄的詳細資訊，請參閱處理重複記錄。