將亞馬遜資料 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 { publicYourClassName
() { } 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存放庫設定代理程式
-
首先,請確定您已安裝所需的 Java 版本,具體取決於代理程式版本。
-
從 awslab amazon-kinesis-agent
GitHub /軟體庫下載代理程式。 -
瀏覽到下載目錄並執行下列命令以安裝代理程式:
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"]
設定和啟動代理程式
-
開啟並編輯組態檔案 (如果使用預設檔案存取許可,即以超級使用者身分執行):
/etc/aws-kinesis/agent.json
在此組態檔案中,指定代理程式從中收集資料的檔案 (
"filePattern"
),以及代理程式將資料傳送至的 Firehose 串流 ("deliveryStream"
) 名稱。檔案名稱具備一種模式,可讓代理程式辨識檔案輪換。您可以輪換檔案或建立新的檔案,每秒不超過一次。代理程式會使用檔案建立時間戳記來決定要追蹤哪些檔案並追蹤到 Firehose 串流中。如果建立新檔案或輪換檔案的頻率超過每秒一次,將導致代理程式無法正確區分這些檔案。{ "flows": [ { "filePattern": "
/tmp/app.log*
", "deliveryStream": "yourdeliverystream
" } ] }預設「 AWS 區域」為
us-east-1
。如果您使用不同的區域,請將firehose.endpoint
設定新增至組態檔案,藉此指定您區域的端點。如需詳細資訊,請參閱用戶端組態設定。 -
手動啟動代理程式:
sudo service aws-kinesis-agent start
-
(選用) 設定代理程式在系統啟動時開始執行:
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。 預設: |
firehose.endpoint |
Amazon 數據 Firehose 的區域端點。 預設: |
sts.endpoint |
AWS 保安編碼器服務的地區端點。 預設: |
userDefinedCredentialsProvider.classname |
如果您定義自訂登入資料提供者,請使用此設定提供其完整類別名稱。不要在類別名稱的末尾包含 .class 。 |
userDefinedCredentialsProvider.location |
如果您定義自訂登入資料提供者,請使用此設定來指定包含自訂登入資料提供者之 jar 的絕對路徑。代理程式也會在下列位置尋找 jar 檔案:/usr/share/aws-kinesis-agent/lib/ 。 |
以下是流程組態設定。
組態設定 | 描述 |
---|---|
aggregatedRecordSizeBytes |
若要讓代理程式彙總記錄,然後在一次作業中將其放入 Firehose 串流,請指定此設定。將其設定為您希望在代理程式將彙總記錄放入 Firehose 串流之前具有的大小。 預設值:0 (無彙總) |
dataProcessingOptions |
在傳送至 Firehose 串流之前,會套用至每個已剖析記錄的處理選項清單。此處理選項會在指定的資料夾執行。如需詳細資訊,請參閱使用代理程式預先處理資料。 |
deliveryStream |
[必填]「Firehose」串流的名稱。 |
filePattern |
[必要] 需要代理程式監控的檔案部分。符合此模式的任何檔案將由代理程式自動挑選及監控。對於符合此模式的所有檔案,請將讀取許可授與 重要代理程式會挑選符合此模式的任何檔案。若要確保代理程式不會挑選意外的記錄,請小心選擇此模式。 |
initialPosition |
檔案開始進行剖析的初始位置。有效值為 預設: |
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) 預設: |
透過指定多個流程組態設定,您可以設定代理程式來監控多個檔案目錄,然後將資料傳送到多個串流。在下列組態範例中,代理程式會監控兩個檔案目錄,並將資料分別傳送至 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
模式下,也可能發生這種情況。嘗試將模式變更為預設模式,或建立模式以避免重複。如需有關處理重複記錄的詳細資訊,請參閱處理重複記錄。