Kinesis 에이전트를 사용하여 Amazon Kinesis Data Streams에 쓰기 - Amazon Kinesis Data Streams

기계 번역으로 제공되는 번역입니다. 제공된 번역과 원본 영어의 내용이 상충하는 경우에는 영어 버전이 우선합니다.

Kinesis 에이전트를 사용하여 Amazon Kinesis Data Streams에 쓰기

Kinesis 에이전트는 간편하게 데이터를 수집하여 Kinesis Data Streams로 전송할 수 있는 독립형 Java 소프트웨어 애플리케이션입니다. 에이전트가 파일 집합을 지속적으로 모니터링하고 새로운 데이터를 스트림에 보냅니다. 에이전트는 파일 로테이션, 검사를 처리하고 실패할 경우 다시 시도하며 적시에 안정적이고 단순한 방식으로 모든 데이터를 전달할 뿐 아니라 또한 스트리밍 프로세스를 더 잘 모니터링하고 문제를 해결하는 데 도움이 되는 Amazon CloudWatch 메트릭을 생성합니다.

기본적으로 줄 바꿈 문자('\n')를 기반으로 각 파일에서 레코드가 구문 분석됩니다. 그러나 여러 줄 레코드를 구문 분석하도록 에이전트를 구성할 수도 있습니다(에이전트 구성 설정 참조).

웹 서버, 로그 서버, 데이터베이스 서버 등 Linux 기반 서버 환경에 에이전트를 설치할 수 있습니다. 에이전트를 설치한 후 모니터링할 파일과 데이터의 스트림을 지정하여 에이전트를 구성하십시오. 에이전트가 구성되면 파일에서 일관되게 데이터를 수집하고, 안정적으로 스트림에 전송합니다.

필수 조건

에이전트 다운로드 및 설치

우선 인스턴스에 연결합니다. 자세한 내용은 Linux용 Amazon EC2 사용 설명서에서 인스턴스에 연결을 참조하세요. 연결 문제가 있는 경우 Amazon EC2 - Linux 인스턴스용 사용 설명서인스턴스 연결 문제 해결을 참조하세요.

Amazon Linux AMI를 이용해 에이전트를 설치하려면

다음 명령을 사용하여 에이전트를 다운로드하고 설치합니다.

sudo yum install –y aws-kinesis-agent
Red Hat Enterprise Linux를 사용하여 에이전트를 설치하려면

다음 명령을 사용하여 에이전트를 다운로드하고 설치합니다.

sudo yum install –y https://s3.amazonaws.com/streaming-data-agent/aws-kinesis-agent-latest.amzn2.noarch.rpm
를 사용하여 에이전트를 설정하려면 GitHub
  1. amazon-kinesis-agentawlabs/에서 에이전트를 다운로드하십시오.

  2. 다운로드 디렉터리로 이동하고 다음 명령을 실행해 에이전트를 설치합니다.

    sudo ./setup --install
Docker 컨테이너에서 에이전트 설정

amazonlinux 컨테이너 베이스를 통해서도 컨테이너에서 Kinesis 에이전트를 실행할 수 있습니다. 다음 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") 및 에이전트가 데이터를 보내는 스트림의 이름("kinesisStream")을 지정합니다. 파일 이름은 패턴이며, 에이전트가 파일 로테이션을 인식합니다. 파일을 로테이션하거나 초당 1회 이하 새 파일을 생성할 수 있습니다. 에이전트가 파일 생성 타임스탬프를 사용하여 어떤 파일을 스트림까지 추적할지 결정합니다. 초당 1회보다 자주 새 파일을 생성하거나 파일을 로테이션하면 에이전트가 제대로 구별할 수 없습니다.

    { "flows": [ { "filePattern": "/tmp/app.log*", "kinesisStream": "yourkinesisstream" } ] }
  2. 에이전트를 수동으로 시작합니다.

    sudo service aws-kinesis-agent start
  3. (선택 사항) 시스템 시작 시 에이전트가 시작되도록 구성합니다.

    sudo chkconfig aws-kinesis-agent on

현재 이 에이전트는 배경에서 시스템 서비스로 실행 중입니다. 지정된 파일을 지속적으로 모니터링하고 지정된 스트림으로 데이터를 보냅니다. 에이전트 활동은 /var/log/aws-kinesis-agent/aws-kinesis-agent.log에 기록됩니다.

에이전트 구성 설정

이 에이전트는 두 가지 필수 구성 설정인 filePatternkinesisStream과 추가 기능을 제공하는 선택적 구성 설정을 지원합니다. /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입니다. 자세한 내용은 IAM 사용 설명서의 IAM 역할을 사용한 AWS 계정 간 액세스 위임을 참조하십시오.

assumeRoleExternalId

역할을 맡을 사람을 결정하는 선택적 식별자입니다. 자세한 내용은 IAM 사용 설명서의 외부 ID 사용 방법을 참조하세요.

awsAccessKeyId

AWS 기본 자격 증명을 재정의하는 액세스 키 ID. 이 설정은 다른 모든 자격 증명 공급자보다 우선 적용됩니다.

awsSecretAccessKey

AWS 기본 자격 증명을 재정의하는 비밀 키. 이 설정은 다른 모든 자격 증명 공급자보다 우선 적용됩니다.

cloudwatch.emitMetrics

설정된 CloudWatch 경우 (true) 에이전트가 메트릭을 내보낼 수 있도록 합니다.

기본값: true

cloudwatch.endpoint

의 지역별 엔드포인트. CloudWatch

기본값: monitoring.us-east-1.amazonaws.com

kinesis.endpoint

Kinesis Data Streams에 대한 리전 엔드포인트.

기본값: kinesis.us-east-1.amazonaws.com

다음은 흐름 구성 설정입니다.

구성 설정 설명
dataProcessingOptions

스트림으로 전송되기 전에 구문 분석된 각 레코드에 적용되는 처리 옵션 목록입니다. 처리 옵션은 지정된 순서로 진행됩니다. 자세한 설명은 에이전트를 사용하여 데이터 사전 처리 섹션을 참조하세요.

kinesisStream

[필수] 스트림 이름입니다.

filePattern

[필수] 에이전트가 픽업하기 위해 일치해야 하는 디렉터리 및 파일 패턴. 이 패턴과 일치하는 모든 파일에 대한 읽기 권한을 aws-kinesis-agent-user에게 부여해야 합니다. 파일이 포함된 디렉터리에 대한 읽기 및 실행 권한을 aws-kinesis-agent-user에게 부여해야 합니다.

initialPosition

파일 구문 분석이 처음 시작된 위치입니다. 유효 값은 START_OF_FILEEND_OF_FILE입니다.

기본값: END_OF_FILE

maxBufferAgeMillis

스트림으로 보내기 전 에이전트가 데이터를 버퍼링하는 최대 시간(밀리초)입니다.

값 범위: 1,000 - 900,000(1초 - 15분)

기본값: 60,000(1분)

maxBufferSizeBytes

스트림으로 보내기 전 에이전트가 데이터를 버퍼링하는 최대 크기(바이트)입니다.

값 범위: 1 - 4,194,304(4MB)

기본값: 4,194,304(4MB)

maxBufferSizeRecords

스트림으로 보내기 전 에이전트가 데이터를 버퍼링하는 최대 레코드 수입니다.

값 범위: 1 - 500

기본값: 500

minTimeBetweenFilePollsMillis

에이전트가 새로운 데이터에 대해 모니터링한 파일을 폴링하고 구문 분석하는 시간 간격(밀리초)입니다.

값 범위: 1 이상

기본값: 100

multiLineStartPattern

레코드의 시작을 식별하기 위한 패턴입니다. 레코드는 패턴과 일치하는 줄 1개 및 패턴과 일치하지 않는 나머지 줄로 이루어져 있습니다. 유효한 값은 정규식입니다. 기본적으로 로그 파일에서 각각의 줄 바꿈은 하나의 레코드로 구문 분석됩니다.

partitionKeyOption

파티션 키를 생성하기 위한 방법입니다. 유효한 값은 RANDOM(임의로 생성된 정수) 및 DETERMINISTIC(데이터에서 계산된 해시 값)입니다.

기본값: RANDOM

skipHeaderLines

모니터링한 파일을 시작할 때 에이전트가 구문 분석을 건너뛰는 줄의 개수입니다.

값 범위: 0 이상

기본값: 0(영)

truncatedRecordTerminator

레코드 크기가 Kinesis Data Streams 레코드 크기 제한을 초과할 때 에이전트가 구문 분석된 레코드를 자르는 데 사용하는 문자열입니다. (1,000KB)

기본값: '\n'(줄 바꿈)

여러 파일 디렉터리 모니터링 및 여러 스트림에 쓰기

여러 개의 흐름 구성 설정을 지정하여, 에이전트가 여러 파일 디렉터리를 모니터링하고 여러 스트림으로 데이터를 보내도록 구성할 수 있습니다. 다음 구성 예제에서 에이전트는 두 개의 파일 디렉터리를 모니터링하고 데이터를 각각 Kinesis 스트림과 Firehose 전송 스트림으로 보냅니다. Kinesis 스트림과 Firehose에 서로 다른 엔드포인트를 지정할 수 있으므로 Kinesis 스트림과 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" } ] }

Firehose에서 에이전트를 사용하는 방법에 대한 자세한 내용은 Kinesis 에이전트를 사용하여 Amazon Data 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 LogRFC3164 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

로그 항목에서 값을 추출하는 데 사용되는 정규식 패턴입니다. 로그 항목이 사전 정의된 로그 형식 중 하나가 아니면 이 설정이 사용됩니다. 이 설정이 사용되면 customFieldNames도 지정해야 합니다.

customFieldNames

각각의 JSON 키 값 쌍에서 키로 사용되는 사용자 지정 필드 이름입니다. 이 설정을 사용하여 matchPattern에서 추출한 값에 필드 이름을 정의하거나 사전 정의된 로그 형식의 기본 필드 이름을 재정의합니다.

예 : 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"}
예 : 사용자 지정 필드가 있는 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"}
예 : Apache Common Log 항목 변환

다음 흐름 구성은 Apache Common Log 항목을 JSON 형식의 한 줄 레코드로 변환합니다.

{ "flows": [ { "filePattern": "/tmp/app.log*", "kinesisStream": "my-stream", "dataProcessingOptions": [ { "optionName": "LOGTOJSON", "logFormat": "COMMONAPACHELOG" } ] } ] }
예 : 여러 줄 레코드 변환

다음 흐름 구성은 첫 줄이 "[SEQUENCE="로 시작하는 여러 줄 레코드를 구문 분석합니다. 먼저 각각의 레코드가 한 줄 레코드로 변환됩니다. 그런 다음 탭 구분 기호를 기반으로 레코드에서 값이 추출됩니다. 추출된 값은 지정된 customFieldNames 값에 매핑되어 JSON 형식의 한 줄 레코드를 형성합니다.

{ "flows": [ { "filePattern": "/tmp/app.log*", "kinesisStream": "my-stream", "multiLineStartPattern": "\\[SEQUENCE=", "dataProcessingOptions": [ { "optionName": "SINGLELINE" }, { "optionName": "CSVTOJSON", "customFieldNames": [ "field1", "field2", "field3" ], "delimiter": "\\t" } ] } ] }
예 : 일치 패턴이 있는 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"}

에이전트 CLI 명령

시스템 시작 시 에이전트가 자동으로 시작됩니다.

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

FAQ

Windows용 Kinesis 에이전트가 있나요?

Windows용 Kinesis 에이전트는 Linux 플랫폼용 Kinesis 에이전트와 다른 소프트웨어입니다.

왜 Kinesis 에이전트가 느려지거나 RecordSendErrors가 증가하나요?

이는 대개 Kinesis에서 제한하기 때문입니다. Kinesis Data Streams의 WriteProvisionedThroughputExceeded 측정치 또는 Firehose 전송 ThrottledRecords 스트림의 측정치를 확인하십시오. 이 지표 중 0에서 증가한 수치가 있으면 스트림 제한을 늘려야 한다는 의미입니다. 자세한 내용은 Kinesis Data Stream limitsAmazon Firehose Delivery Streams를 참조하세요.

제한을 확인한 후에는 Kinesis 에이전트가 대량의 작은 파일을 테일링하도록 구성되어 있는지 확인하세요. Kinesis 에이전트가 새 파일을 테일링할 때 지연이 발생하므로 Kinesis 에이전트는 소량의 대용량 파일을 추적합니다. 로그 파일을 더 큰 파일로 통합해 보세요.

java.lang.OutOfMemoryError 예외가 발생하나요?

Kinesis 에이전트에는 현재 워크로드를 처리할 메모리가 충분하지 않습니다. /usr/bin/start-aws-kinesis-agentJAVA_START_HEAPJAVA_MAX_HEAP을 늘리고 에이전트를 다시 시작해 보세요.

IllegalStateException : connection pool shut down 예외가 발생하나요?

Kinesis 에이전트에는 현재 워크로드를 처리할 연결이 충분하지 않습니다. /etc/aws-kinesis/agent.json에서 일반 에이전트 구성 설정의 maxConnectionsmaxSendingThreads를 늘려 보세요. 이 필드의 기본값은 제공되는 런타임 프로세서의 12배입니다. 고급 에이전트 구성 설정에 대한 자세한 AgentConfiguration내용은.java를 참조하십시오.

Kinesis 에이전트의 다른 문제는 어떻게 디버그할 수 있나요?

/etc/aws-kinesis/log4j.xml에서 DEBUG 레벨 로그를 활성화할 수 있습니다.

Kinesis 에이전트는 어떻게 구성하나요?

maxBufferSizeBytes의 크기가 작을수록 Kinesis 에이전트는 더 자주 데이터를 전송합니다. 이렇게 하면 레코드의 전송 시간이 줄어 유용하지만, Kinesis에 대한 초당 요청 수가 증가합니다.

왜 Kinesis 에이전트가 중복 레코드를 보내나요?

이 문제는 파일 테일링이 잘못 구성되어 발생합니다. fileFlow’s filePattern마다 매칭되는 파일은 하나뿐이어야 합니다. 사용 중인 logrotate 모드가 copytruncate 모드인 경우에도 이 문제가 발생할 수 있습니다. 모드를 기본 모드 또는 생성 모드로 변경하여 중복을 피하세요. 중복 레코드 처리에 대한 자세한 내용은 중복 레코드 처리를 참조하세요.