Kinesis 에이전트를 사용하여 Kinesis로 로그를 푸시할 때 Amazon EC2 메타데이터를 추가하려면 어떻게 해야 합니까?

최종 업데이트 날짜: 2022년 2월 25일

Amazon Kinesis 에이전트를 사용하여 Amazon Elastic Compute Cloud(Amazon EC2)에서 Amazon Kinesis로 로그를 전송하려고 합니다. Amazon EC2 메타데이터를 각 로그 라인에 추가하려면 어떻게 해야 합니까?

간략한 설명

각 로그 라인에 EC2 메타데이터를 추가하려면 다음을 수행합니다.

1.    Linux 또는 Windows 플랫폼에서 Amazon Kinesis 에이전트를 설치하고 설정합니다.

2.    EC2 메타데이터를 표시하도록 구성 설정을 업데이트합니다.

3.    필요한 AWS Identity and Access Management(IAM) 권한이 있는지 확인합니다.

참고: EC2 메타데이터를 검색하고 Amazon Kinesis Data Firehose에 데이터를 게시하려면 IAM 권한이 필요합니다.

​해결 방법

Linux 플랫폼

Amazon Kinesis 에이전트를 사용하여 Kinesis Data Firehose로 로그를 전송하려면 다음을 수행합니다.

1.    에이전트를 다운로드하여 설치합니다.

2.    다음 권한이 있는 IAM 역할을 생성합니다.

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "firehose:PutRecord",
        "firehose:PutRecordBatch"
      ],
      "Resource": ["<FIREHOSE_ARN>"
      ]
    },
    {
      "Sid": "VisualEditor0",
      "Effect": "Allow",
      "Action": [
        "ec2:DescribeInstances",
        "ec2:DescribeInstanceAttribute",
        "ec2:DescribeInstanceTypes",
        "ec2:DescribeInstanceStatus",
        "ec2:DescribeTags"
      ],
      "Resource": "<EC2_ARN>"
    },
    {
      "Sid": "VisualEditor1",
      "Effect": "Allow",
      "Action": "cloudwatch:PutMetricData",
      "Resource": "*"
    }
  ]
}

참고: Firehose_ARNEC2_ARN의 경우 Amazon 리소스 이름(ARN) 정보를 입력합니다. 또는 와일드카드 “*”를 사용할 수 있습니다. 자세한 내용은 Amazon EC2용 Amazon 리소스 이름(ARN)을 참조하세요.

3.    Amazon Kinesis 에이전트를 설치한 EC2 인스턴스에 새로 생성된 IAM 역할을 연결합니다. 기존 IAM 역할 할당에 대한 자세한 내용은 기존 IAM 역할을 EC2 인스턴스에 할당하려면 어떻게 해야 합니까?를 참조하세요.

4.    /etc/aws-kinesis/agent.json 파일을 편집합니다.

{
  "cloudwatch.emitMetrics": true,
  "kinesis.endpoint": "",
  "firehose.endpoint": "firehose.us-east-1.amazonaws.com",
  
  "flows": [
    {
      "filePattern": "/tmp/app.log*",
      "deliveryStream": "yourdeliverystream",
      "dataProcessingOptions": [
          {
                    "optionName": "LOGTOJSON",
                    "logFormat": "COMMONAPACHELOG"
              },
          {
            "optionName": "ADDEC2METADATA",
        "logFormat": "COMMONAPACHELOG"
          }
      ]
    }
  ]
}

이 예제에서 /etc/aws-kinesis/agent.json 파일은 COMMONAPACHELOG 로그 파일 형식을 처리합니다. 로그 파일의 형식이 다른 경우 dataProcessingOptions 설정을 로그 파일 형식으로 업데이트해야 합니다. 에이전트 및 처리 옵션에 대한 자세한 내용은 에이전트를 사용하여 데이터 사전 처리를 참조하세요.

중요: optionName 필드에 ADDEC2METADATA를 추가하여 EC2 메타데이터가 각 로그 라인에 추가되도록 합니다. 기본적으로 Amazon Kinesis 에이전트는 EC2 메타데이터에 privateIp, availabilityZone, instanceId, instanceType, accountId, amiId, regionmetadataTimestamp 파라미터를 추가합니다.

5.    에이전트를 구성하고 시작합니다. 이제 에이전트가 백그라운드에서 시스템 서비스로 실행됩니다. 지정된 파일을 지속적으로 모니터링하여 지정된 전송 스트림으로 데이터를 전송합니다. 에이전트 활동은 다음 예시 출력과 유사하게 /var/log/aws-kinesis-agent/aws-kinesis-agent.log 파일에 기록됩니다.

{
    "host": "157.92.12.106",
    "ident": null,
    "authuser": null,
    "datetime": "31/Aug/1995:20:50:31 -0400",
    "request": "GET /history/astp/astp-spacecraft.txt HTTP/1.0",
    "response": "200",
    "bytes": "440",
    "privateIp": "X.X.X.X",
    "availabilityZone": "us-east-1c",
    "instanceId": "i-01bxxxxxxxxxx43a0",
    "instanceType": "t2.xlarge",
    "accountId": "585xxxxxx740",
    "amiId": "ami-0fc61db8544a617ed",
    "region": "us-east-1",
    "metadataTimestamp": "2020-04-20T02:28:40+0000"
  }

Windows 플랫폼

Amazon Kinesis Tap 에이전트를 사용하여 Kinesis Data Firehose로 데이터를 전송하려면 다음 단계를 수행합니다.

1.    Microsoft Windows용 Amazon Kinesis 에이전트를 설치합니다.

2.    다음 권한이 있는 IAM 역할을 생성합니다.

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "firehose:DeleteDeliveryStream",
        "firehose:PutRecord",
        "firehose:PutRecordBatch",
        "firehose:UpdateDestination"
      ],
      "Resource": ["<KFH_ARN>"
      ]
    },
    {
      "Sid": "VisualEditor0",
      "Effect": "Allow",
      "Action": [
        "ec2:DescribeInstances",
        "ec2:DescribeInstanceAttribute",
        "ec2:DescribeInstanceTypes",
        "ec2:DescribeInstanceStatus",
        "ec2:DescribeTags"
      ],
      "Resource": "<EC2_ARN>"
    },
    {
      "Sid": "VisualEditor1",
      "Effect": "Allow",
      "Action": "cloudwatch:PutMetricData",
      "Resource": "*"
    }
  ]
}

참고: KFH_ARNEC2_ARN의 경우 Amazon 리소스 이름(ARN) 정보를 입력합니다. 자세한 내용은 Amazon EC2용 Amazon 리소스 이름(ARN)을 참조하세요.

3.    Kinesis Tap Agent를 설치한 EC2 인스턴스에 새로 생성된 IAM 역할을 연결합니다.

4.    C:\Program Files\Amazon\AWSKinesisTap\appsettings.json 파일을 엽니다.

{
  "Sources": [
    {
      "Id": "W3SVCLog1",
      "SourceType": "W3SVCLogSource",
      "Directory": "C:\\inetpub\\logs\\LogFiles\\W3SVC1",
      "FileNameFilter": "*.log",
      "TimeZoneKind": "UTC"
    }
  ],
  "Sinks": [
    {
      "Id": "W3SVCLogSink",
      "SinkType": "KinesisFirehose",
      "Region": "eu-central-1",
      "StreamName": " W3SVCLogStream",
  "Format": "json",
  <b>"ObjectDecoration": "instance_id={instance_id};hostname={hostname};ec2:local-hostname={ec2:local-hostname};computername={computername};env:computername={env:computername};timestamp:yyyyMMdd={timestamp:yyyyMMdd}"</b>
    }    
  
  ],
  "Pipes": [
    {
      "Id": "W3SVCLog1ToKinesisStream",
      "SourceRef": "W3SVCLog1",
      "SinkRef": "W3SVCLogSink"
    }
  ]
}

중요: "ObjectDecoration": "instance_id={instance_id};hostname={hostname};ec2:local-hostname={ec2:local-hostname};computername={computername};env:computername={env:computername};timestamp:yyyyMMdd={timestamp:yyyyMMdd}"를 싱크에 추가하여 EC2 메타데이터가 각 로그 라인에 추가되었는지 확인합니다. Kinesis Tap Agent는 instance_id, hostname, ec2:local-hostname, computername, env:computernametimestamp:yyyyMMdd 파라미터를 EC2 메타데이터로 추가합니다. 이러한 파라미터를 모두 표시하지 않으려면 추가할 파라미터를 지정합니다.

구성 옵션에 대한 자세한 내용은 Configuring Amazon Kinesis Agent for Microsoft Windows를 참조하십시오.

5.    Kinesis Tap 에이전트를 시작하려면 Windows용 Kinesis 에이전트를 구성하고 시작합니다. 각 로그 라인에 다음 출력이 표시되어야 합니다.

{
  "EventId": 7036,
  "Description": "The WinHTTP Web Proxy Auto-Discovery Service service entered the stopped state.",
  "LevelDisplayName": "Informational",
  "LogName": "System",
  "MachineName": "EC2AMAZ-GLL60A7",
  "ProviderName": "Service Control Manager",
  "TimeCreated": "2020-04-20T06:02:51.5847181Z",
  "Index": 34427,
  "UserName": null,
  "Keywords": "Classic",
  "instance_id": "i-0183xxxxxxxxxx4b7",
  "hostname": "ip-x-x-x-x.ec2.internal",
  "ec2:local-hostname": "ip-x-x-x-x.ec2.internal",
  "computername": "EC2AMAZ-GLL60A7",
  "env:computername": "EC2AMAZ-GLL60A7",
  "timestamp:yyyyMMdd": "20200420"
}