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

Brève description

Pour ajouter les métadonnées EC2 à chaque ligne de journal, procédez comme suit :

1.    Installez et configurez Amazon 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 Amazon Kinesis Agent afin d'envoyer des journaux vers Kinesis Data Firehose, procédez comme suit :

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": ["<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": "*"
    }
  ]
}

Remarque : pour Firehose_ARN et EC2_ARN, saisissez les informations d'Amazon Resource Name (ARN) Vous pouvez également utiliser un caractère générique « * ». Pour plus d'informations, consultez Amazon Resource Name (ARN) pour Amazon EC2.

3.    Attachez ce nouveau rôle IAM aux instances EC2 sur lesquelles avez installé Amazon Kinesis Agent. Pour plus d'informations sur l'attribution d'un rôle IAM existant, consultez 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",
      "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 Utilisation de l'agent pour prétraiter les données.

Important : ajoutez ADDEC2METADATA pour le champ optionName afin que les métadonnées EC2 soient ajoutées à chaque ligne de journal. Par défaut, Amazon Kinesis Agent 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 Kinesis Data Firehose, effectuez les étapes suivantes :

1.    Installez Amazon Kinesis Agent pour Microsoft 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",
        "ec2:DescribeTags"
      ],
      "Resource": "<EC2_ARN>"
    },
    {
      "Sid": "VisualEditor1",
      "Effect": "Allow",
      "Action": "cloudwatch:PutMetricData",
      "Resource": "*"
    }
  ]
}

Remarque : pour KFH_ARN et EC2_ARN, saisissez les informations d'Amazon Resource Name (ARN). Pour plus d'informations, consultez Amazon Resource Name (ARN) pour Amazon EC2.

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",
  <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"
    }
  ]
}

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

---

Informations connexes

Collectez, analysez, transformez et diffusez des événements, des journaux et des métriques Windows à l'aide d'Amazon Kinesis Agent pour Microsoft Windows