Comment ajouter des métadonnées Amazon EC2 lors de la transmission de journaux vers Kinesis à l'aide de Kinesis Agent ?

Dernière mise à jour : 12/05/2020

Je souhaite envoyer des journaux depuis Amazon Elastic Compute Cloud (Amazon EC2) vers Amazon Kinesis à l'aide d'Amazon Kinesis Agent. Comment puis-je ajouter les métadonnées Amazon EC2 à chaque ligne de journal ?

Brève description

Vous pouvez ajouter les métadonnées EC2 à chaque ligne de journal en suivant cette procédure :

1.    Installez et configurez Kinesis Agent sur une plateforme Linux ou Windows.

2.    Mettez à jour vos paramètres de configuration afin d'afficher les métadonnées EC2.

3.    Vérifiez que vous disposez des autorisations AWS Identity and Access Management (IAM) requises.

Remarque : ces autorisations IAM sont nécessaires pour récupérer des métadonnées EC2 et publier des données dans Amazon Kinesis Data Firehose.

Solution

Sur une plateforme Linux

Pour utiliser Kinesis Agent afin d'envoyer des journaux vers Kinesis Data Firehose, effectuez les opérations suivantes :

1.    Téléchargez et installez l'agent.

2.    Créez un rôle IAM doté des autorisations suivantes :

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

3.    Attachez ce nouveau rôle IAM aux instances EC2 sur lesquelles avez installé Kinesis Agent. Pour plus d'informations sur l'attribution d'un rôle IAM existant, consultez la section Comment attribuer un rôle IAM existant à une instance EC2 ?

4.    Modifiez le fichier /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",
      "partitionKeyOption": "RANDOM",
      "dataProcessingOptions": [
	      {
                    "optionName": "LOGTOJSON",
                    "logFormat": "COMMONAPACHELOG"
              },
	      {
	        "optionName": "ADDEC2METADATA",
		"logFormat": "COMMONAPACHELOG"
	      }
      ]
    }
  ]
}

Dans cet exemple, le fichier /etc/aws-kinesis/agent.json traite le format de fichier journal COMMONAPACHELOG. Si le format de votre fichier journal est différent, mettez à jour le paramètre dataProcessingOptions en conséquence. Pour plus d'informations sur les agents et les options de traitement, consultez la section Utilisation de l'agent pour prétraiter les données.

Important : ajoutez ADDEC2METADATA dans le champ optionName afin que les métadonnées EC2 soient ajoutées à chaque ligne de journal. Par défaut, l'agent Kinesis ajoute les paramètres suivants dans les métadonnées EC2 : privateIp, availabilityZone, instanceId, instanceType, accountId, amiId, region, et metadataTimestamp.

5.    Configurez et démarrez l'agent. Celui-ci s'exécute désormais en arrière-plan en tant que service système. Il surveille en permanence les fichiers spécifiés, en envoyant des données au flux de diffusion sélectionné. L'activité de l'agent est consignée dans le fichier /var/log/aws-kinesis-agent/aws-kinesis-agent.log, comme dans cet exemple de sortie :

{
        "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"
    }

Sur une plateforme Windows

Pour utiliser Amazon Kinesis Tap Agent afin d'envoyer des données vers Data Firehose, procédez comme suit :

1.    Installez Kinesis Agent pour Windows.

2.    Créez un rôle IAM doté des autorisations suivantes :

{
  "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"
      ],
      "Resource": "*"
    },
    {
      "Sid": "VisualEditor1",
      "Effect": "Allow",
      "Action": "cloudwatch:PutMetricData",
      "Resource": "*"
    }
  ]
}

3.    Attachez ce nouveau rôle IAM aux instances EC2 sur lesquelles vous avez installé Kinesis Tap Agent.

4.    Ouvrez le fichier 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",
	"ObjectDecoration": "instance_id={instance_id};hostname={hostname};ec2:local-hostname={ec2:local-hostname};computername={computername};env:computername={env:computername};timestamp:yyyyMMdd={timestamp:yyyyMMdd}"
        }		
	
    ],
    "Pipes": [
        {
            "Id": "W3SVCLog1ToKinesisStream",
            "SourceRef": "W3SVCLog1",
            "SinkRef": "W3SVCLogSink"
        }
    ]
}

Important : Ajoutez "ObjectDecoration": "instance_id={instance_id};hostname={hostname};ec2:local-hostname={ec2:local-hostname};computername={computername};env:computername={env:computername};timestamp:yyyyMMdd={timestamp:yyyyMMdd}" à votre récepteur afin d'ajouter les métadonnées EC2 à chaque ligne de journal. Kinesis Tap Agent ajoute les paramètres suivants en tant que métadonnées EC2 : instance_id, hostname, ec2:local-hostname, computername, env:computername et timestamp:yyyyMMdd. Vous pouvez également indiquer les paramètres spécifiques que vous souhaitez ajouter.

Pour plus d'informations sur les options de configuration, consultez la section Configuration d'Amazon Kinesis Agent pour Microsoft Windows.

5.    Configurez et démarrez Kinesis Agent pour Windows pour démarrer Kinesis Tap Agent. La sortie suivante doit apparaître à chaque ligne de journal :

{
    "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"
}