As traduções são geradas por tradução automática. Em caso de conflito entre o conteúdo da tradução e da versão original em inglês, a versão em inglês prevalecerá. # Gravar no Amazon Kinesis Data Streams usando o Kinesis Agent O Kinesis Agent é uma aplicação de software Java independente que oferece uma maneira fácil de coletar e enviar dados ao Kinesis Data Streams. O agente monitora continuamente um conjunto de arquivos e envia novos dados ao fluxo. Ele manipula o rodízio de arquivos, os pontos de verificação e as novas tentativas após falhas. Os dados são entregues de maneira confiável, imediata e simples. Ele também emite CloudWatch métricas da Amazon para ajudar você a monitorar e solucionar melhor o processo de streaming. Por padrão, os registros são analisados em cada arquivo com base no caractere de nova linha (`'\n'`). No entanto, o agente também pode ser configurado para analisar registros de várias linhas (consulte [Especificar as definições da configuração do agente](#agent-config-settings)). É possível instalar o agente em ambientes de servidor baseados no Linux, como servidores web, servidores de log e servidores de banco de dados. Após instalar o agente, configure-o especificando os arquivos a serem monitorados e o fluxo dos dados. Depois que o agente é configurado, ele coleta dados dos arquivos de forma durável e os envia confiavelmente ao fluxo. **Topics** + [Concluir os pré-requisitos do Kinesis Agent](#prereqs) + [Fazer download e instalar o agente](#download-install) + [Configuração e inicialização do agente](#config-start) + [Especificar as definições da configuração do agente](#agent-config-settings) + [Monitorar vários diretórios de arquivos e gravação em vários fluxos](#sim-writes) + [Uso do agente para pré-processar dados](#pre-processing) + [Usar comandos da CLI do agente](#cli-commands) + [Perguntas frequentes](#agent-faq) ## Concluir os pré-requisitos do Kinesis Agent + O sistema operacional deve ser a AMI do Amazon Linux versão 2015.09 ou posterior ou o Red Hat Enterprise Linux versão 7 ou posterior. + Se estiver usando o Amazon EC2 para executar o agente, inicie a instância do EC2. + Gerencie suas AWS credenciais usando um dos seguintes métodos: + Especifique um perfil do IAM ao executar a instância do EC2. + Especifique AWS as credenciais ao configurar o agente (consulte [awsAccessKeyID](#awsAccessKeyId) e [awsSecretAccesschave](#awsSecretAccessKey)). + Edite `/etc/sysconfig/aws-kinesis-agent` para especificar sua região e suas chaves de AWS acesso. + [Se sua instância do EC2 estiver em uma AWS conta diferente, crie uma função do IAM para fornecer acesso ao serviço Kinesis Data Streams e especifique essa função ao configurar o agente (consulte [AssumeroLearn](#assumeRoleARN) e Id). assumeRoleExternal](#assumeRoleExternalId) Use um dos métodos anteriores para especificar AWS as credenciais de um usuário na outra conta que tenha permissão para assumir essa função. + A função ou AWS as credenciais do IAM que você especificar devem ter permissão para realizar a operação do Kinesis Data [PutRecords](https://docs.aws.amazon.com/kinesis/latest/APIReference/API_PutRecords.html)Streams para que o agente envie dados para seu stream. Se você ativar o CloudWatch monitoramento para o agente, a permissão para realizar a CloudWatch [PutMetricData](https://docs.aws.amazon.com/AmazonCloudWatch/latest/APIReference/API_PutMetricData.html)operação também será necessária. Para obter mais informações, consulte [Controlar o acesso aos recursos do Amazon Kinesis Data Streams usando o IAM](controlling-access.md)[Monitore a integridade do Kinesis Data Streams Agent com a Amazon CloudWatch](agent-health.md), e [Controle de CloudWatch acesso](https://docs.aws.amazon.com/AmazonCloudWatch/latest/DeveloperGuide/UsingIAM.html). ## Fazer download e instalar o agente Primeiro, conecte-se à instância. Para obter mais informações, consulte [Conectar-se à sua instância](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2-connect-to-instance-linux.html) no *Guia do usuário do Amazon EC2*. Se tiver problemas para se conectar, consulte [Solução de problemas para conectar-se à sua instância](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/TroubleshootingInstancesConnecting.html) no *Guia do usuário do Amazon EC2*. **Como configurar o agente usando o Amazon Linux AMI** Use o comando a seguir para fazer download do agente e instalá-lo: ``` sudo yum install –y aws-kinesis-agent ``` **Como configurar o agente usando o Red Hat Enterprise Linux** Use o comando a seguir para fazer download do agente e instalá-lo: ``` sudo yum install –y https://s3.amazonaws.com/streaming-data-agent/aws-kinesis-agent-latest.amzn2.noarch.rpm ``` **Para configurar o agente usando GitHub** 1. Baixe o agente em [amazon-kinesis-agentawlabs/](https://github.com/awslabs/amazon-kinesis-agent). 1. Instale o agente navegando até o diretório de download e executando o comando a seguir: ``` sudo ./setup --install ``` **Como configurar o agente em um contêiner do Docker** O Kinesis Agent também pode ser executado em um contêiner por meio da base de contêineres [amazonlinux](https://docs.aws.amazon.com/AmazonECR/latest/userguide/amazon_linux_container_image.html). Use o Dockerfile a seguir e depois execute o `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"] ``` ## Configuração e inicialização do agente **Como configurar e iniciar o agente** 1. Abra e edite o arquivo de configuração (como superusuário, se as permissões padrão de acesso a arquivos estiverem sendo usadas): `/etc/aws-kinesis/agent.json` Nesse arquivo de configuração, especifique os arquivos ( `"filePattern"` ) nos quais o agente coleta dados e o nome do fluxo ( `"kinesisStream"` ) ao qual o agente envia dados. Observe que o nome do arquivo é um padrão, e o agente reconhece os rodízios de arquivos. Só é possível fazer o rodízio de arquivos ou criar novos arquivos uma vez por segundo, no máximo. O agente usa o carimbo de data e hora de criação de arquivo para determinar quais arquivos serão rastreados e colocados no final do fluxo; a criação de novos arquivos ou o rodízio de arquivos em uma frequência superior a uma vez por segundo não permite que o agente faça a distinção entre eles corretamente. ``` { "flows": [ { "filePattern": "/tmp/app.log*", "kinesisStream": "yourkinesisstream" } ] } ``` 1. Inicie o agente manualmente: ``` sudo service aws-kinesis-agent start ``` 1. (Opcional) Configure o agente para ser iniciado durante o startup do sistema: ``` sudo chkconfig aws-kinesis-agent on ``` Agora o agente está sendo executado como um serviço do sistema em segundo plano. Ele monitora continuamente os arquivos especificados e envia dados ao fluxo especificado. A atividade do agent é registrada em `/var/log/aws-kinesis-agent/aws-kinesis-agent.log`. ## Especificar as definições da configuração do agente O agente oferece suporte a duas configurações obrigatórias, `filePattern` e `kinesisStream`, além das configurações opcionais de recursos adicionais. É possível especificar configurações obrigatórias e opcionais em `/etc/aws-kinesis/agent.json`. Sempre que o arquivo de configuração for alterado, o agente deverá ser interrompido e iniciado, usando os seguintes comandos: ``` sudo service aws-kinesis-agent stop sudo service aws-kinesis-agent start ``` Se desejar, é possível usar o comando a seguir: ``` sudo service aws-kinesis-agent restart ``` Estas são as configurações gerais. | Definição da configuração | Description | | --- | --- | | assumeRoleARN | O ARN da função a ser assumida pelo usuário. Para obter mais informações, consulte [Delegar acesso entre AWS contas usando funções do IAM](https://docs.aws.amazon.com/IAM/latest/UserGuide/tutorial_cross-account-with-roles.html) no *Guia do usuário do IAM*. | | assumeRoleExternalId | Um identificador opcional que determina quem pode assumir o perfil. Para obter mais informações, consulte [Como usar um ID externo](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_create_for-user_externalid.html) no *Guia do usuário do IAM*. | | awsAccessKeyId | AWS ID da chave de acesso que substitui as credenciais padrão. Essa configuração tem precedência sobre todos os outros provedores de credenciais. | | awsSecretAccessKey | AWS chave secreta que substitui as credenciais padrão. Essa configuração tem precedência sobre todos os outros provedores de credenciais. | | cloudwatch.emitMetrics | Permite que o agente emita métricas para, CloudWatch se definidas (verdadeiras). Padrão: verdadeiro | | cloudwatch.endpoint | O endpoint regional para CloudWatch. Padrão: `monitoring.us-east-1.amazonaws.com` | | kinesis.endpoint | O endpoint regional do Kinesis Data Streams. Padrão: `kinesis.us-east-1.amazonaws.com` | Estas são as configurações de fluxo. | Definição da configuração | Description | | --- | --- | | dataProcessingOptions | A lista das opções de processamento aplicadas a cada registro analisado antes que ele seja enviado ao fluxo. As opções de processamento são executadas na ordem especificada. Para obter mais informações, consulte [Uso do agente para pré-processar dados](#pre-processing). | | kinesisStream | [Obrigatório] O nome do fluxo. | | filePattern | [Obrigatório] O diretório e o padrão de arquivo que devem ser combinados para serem coletados pelo agente. Para todos os arquivos correspondentes a esse padrão, deve ser concedida uma permissão de leitura a `aws-kinesis-agent-user`. Para o diretório que contém os arquivos, devem ser concedidas permissões de leitura e execução a `aws-kinesis-agent-user`. | | initialPosition | A posição em que o arquivo começou a ser analisado. Os valores válidos são `START_OF_FILE` e `END_OF_FILE`. Padrão: `END_OF_FILE` | | maxBufferAgeMillis | O tempo máximo, em milissegundos, durante o qual o agente armazena os dados em buffer antes de enviá-los ao fluxo. Intervalo de valores: 1.000 a 900.000 (1 segundo a 15 minutos) Padrão: 60.000 (1 minuto) | | maxBufferSizeBytes | O tamanho máximo, em bytes, durante o qual o agente armazena os dados em buffer antes de enviá-los ao fluxo. Intervalo de valores: 1 a 4.194.304 (4 MB) Padrão: 4.194.304 (4 MB) | | maxBufferSizeRecords | O número máximo de registros para os quais o agente armazena os dados em buffer antes de enviá-los ao fluxo. Intervalo de valores: 1 a 500 Padrão: 500 | | minTimeBetweenFilePollsMillis | O intervalo de tempo, em milissegundos, em que o agente consulta e analisa os arquivos monitorados em busca de novos dados. Intervalo de valores: 1 ou mais Padrão: 100 | | multiLineStartPattern | O padrão de identificação do início de um registro. Um registro é composto por uma linha que corresponde ao padrão e pelas linhas subsequentes que não correspondem ao padrão. Os valores válidos são expressões regulares. Por padrão, cada nova linha nos arquivos de log é analisada como um único registro. | | partitionKeyOption | O método para gerar a chave de partição. Os valores válidos são `RANDOM` (inteiro gerado aleatoriamente) e `DETERMINISTIC` (um valor de hash calculado a partir dos dados). Padrão: `RANDOM` | | skipHeaderLines | O número de linhas em que o agente ignorará a análise no início dos arquivos monitorados. Intervalo de valores: 0 ou mais Padrão: 0 (zero) | | truncatedRecordTerminator | A string que o agente usa para truncar um registro analisado que excede o limite de tamanho de registro do Kinesis Data Streams. (1,000 KB) Padrão: `'\n'` (nova linha) | ## Monitorar vários diretórios de arquivos e gravação em vários fluxos Ao especificar vários fluxos de configurações, é possível configurar o agente para monitorar vários diretórios de arquivos e enviar dados a vários streams. No exemplo de configuração a seguir, o agente monitora dois diretórios de arquivos e envia dados para um fluxo do Kinesis e para um fluxo de entrega do Firehose, respectivamente. Observe que, como é possível especificar endpoints diferentes para o Kinesis Data Streams e o Firehose, os fluxos dos dois serviços não precisam estar na mesma região. ``` { "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" } ] } ``` Para obter informações mais detalhadas sobre o uso do agente com o Firehose, consulte [Gravar no Amazon Kinesis Data Firehose com o Kinesis Agent](https://docs.aws.amazon.com/firehose/latest/dev/writing-with-agents.html). ## Uso do agente para pré-processar dados O agente pode pré-processar os registros analisados a partir dos arquivos monitorados antes de enviá-los ao fluxo. É possível habilitar esse recurso adicionando a configuração `dataProcessingOptions` ao fluxo de arquivos. Um ou mais opções de processamento podem ser adicionadas e serão executadas na ordem especificada. O agente oferece suporte às seguintes opções de processamento. Como o agente é de código aberto, é possível desenvolver e estender ainda mais suas opções de processamento. O download do agente pode ser feito em [Kinesis Agent](https://github.com/awslabs/amazon-kinesis-agent).Opções de processamento `SINGLELINE` Converte um registro de várias linhas em um registro de única linha removendo caracteres de nova linha, e espaços à esquerda e à direita. ``` { "optionName": "SINGLELINE" } ``` `CSVTOJSON` Converte um registro com formato separado por delimitador em um registro com formato JSON. ``` { "optionName": "CSVTOJSON", "customFieldNames": [ "field1", "field2", ... ], "delimiter": "yourdelimiter" } ``` `customFieldNames` [Obrigatório] Os nomes de campo usados como chaves em cada par de valores de chave JSON. Por exemplo, ao especificar `["f1", "f2"]`, o registro "v1, v2" será convertido em `{"f1":"v1","f2":"v2"}`. `delimiter` A string usada como delimitador no registro. O padrão é uma vírgula (,). `LOGTOJSON` Converte um registro com formato de log em um registro com formato JSON. Os formatos de log com suporte são **Apache Common Log**, **Apache Combined Log**, **Apache Error Log** e **RFC3164 Syslog**. ``` { "optionName": "LOGTOJSON", "logFormat": "logformat", "matchPattern": "yourregexpattern", "customFieldNames": [ "field1", "field2", … ] } ``` `logFormat` [Obrigatório] O formato da entrada de log. Os valores possíveis são: + `COMMONAPACHELOG`: o formato do Apache Common Log. Cada entrada de log tem o seguinte padrão: "`%{host} %{ident} %{authuser} [%{datetime}] \"%{request}\" %{response} %{bytes}`". + `COMBINEDAPACHELOG`: o formato do Apache Combined Log. Cada entrada de log tem o seguinte padrão: "`%{host} %{ident} %{authuser} [%{datetime}] \"%{request}\" %{response} %{bytes} %{referrer} %{agent}`". + `APACHEERRORLOG`: o formato do Apache Error Log. Cada entrada de log tem o seguinte padrão: "`[%{timestamp}] [%{module}:%{severity}] [pid %{processid}:tid %{threadid}] [client: %{client}] %{message}`". + `SYSLOG`— O formato RFC3164 Syslog. Cada entrada de log tem o seguinte padrão: "`%{timestamp} %{hostname} %{program}[%{processid}]: %{message}`". `matchPattern` O padrão da expressão regular usada para extrair valores de entradas de log. Essa configuração é usada se a entrada de log não estiver em um dos formatos de log predefinidos. Se essa configuração for usada, também é necessário especificar `customFieldNames`. `customFieldNames` Os nomes de campo personalizados usados como chaves em cada par de valores de chave JSON. É possível usar essa configuração para definir nomes de campo para valores extraídos de `matchPattern` ou substituir os nomes de campo padrão de formatos de log predefinidos. **Example : Configuração LOGTOJSON** Este é um exemplo de uma configuração `LOGTOJSON` para uma entrada Apache Common Log convertida em formato JSON: ``` { "optionName": "LOGTOJSON", "logFormat": "COMMONAPACHELOG" } ``` Antes da conversão: ``` 64.242.88.10 - - [07/Mar/2004:16:10:02 -0800] "GET /mailman/listinfo/hsdivision HTTP/1.1" 200 6291 ``` Depois da conversão: ``` {"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"} ``` **Example : Configuração LOGTOJSON com campos personalizados** Este é outro exemplo de configuração `LOGTOJSON`: ``` { "optionName": "LOGTOJSON", "logFormat": "COMMONAPACHELOG", "customFieldNames": ["f1", "f2", "f3", "f4", "f5", "f6", "f7"] } ``` Com essa configuração, a mesma entrada Apache Common Log do exemplo anterior é convertida em formato JSON, da seguinte forma: ``` {"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"} ``` **Example : Conversão da entrada Apache Common Log** A configuração de fluxo a seguir converte uma entrada Apache Common Log em um registro de linha única no formato JSON: ``` { "flows": [ { "filePattern": "/tmp/app.log*", "kinesisStream": "my-stream", "dataProcessingOptions": [ { "optionName": "LOGTOJSON", "logFormat": "COMMONAPACHELOG" } ] } ] } ``` **Example : Conversão de registros de várias linhas** A configuração de fluxo a seguir analisa registros de várias linha cuja primeira linha começa com "`[SEQUENCE=`". Cada registro é convertido primeiro em um registro de única linha. Em seguida, os valores são extraídos do registro com base em um delimitador por tabulações. Os valores extraídos são mapeados para os valores `customFieldNames` especificados, a fim de formar um registro de linha única no formato JSON. ``` { "flows": [ { "filePattern": "/tmp/app.log*", "kinesisStream": "my-stream", "multiLineStartPattern": "\\[SEQUENCE=", "dataProcessingOptions": [ { "optionName": "SINGLELINE" }, { "optionName": "CSVTOJSON", "customFieldNames": [ "field1", "field2", "field3" ], "delimiter": "\\t" } ] } ] } ``` **Example : Configuração LOGTOJSON com padrão de correspondência** este é um exemplo de configuração `LOGTOJSON` referente a uma entrada Apache Common Log convertida em formato JSON, com o último campo (bytes) omitido: ``` { "optionName": "LOGTOJSON", "logFormat": "COMMONAPACHELOG", "matchPattern": "^([\\d.]+) (\\S+) (\\S+) \\[([\\w:/]+\\s[+\\-]\\d{4})\\] \"(.+?)\" (\\d{3})", "customFieldNames": ["host", "ident", "authuser", "datetime", "request", "response"] } ``` Antes da conversão: ``` 123.45.67.89 - - [27/Oct/2000:09:27:09 -0400] "GET /java/javaResources.html HTTP/1.0" 200 ``` Depois da conversão: ``` {"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"} ``` ## Usar comandos da CLI do agente Inicie automaticamente o agente durante o startup do sistema: ``` sudo chkconfig aws-kinesis-agent on ``` Verifique o status do agente: ``` sudo service aws-kinesis-agent status ``` Interrompa o agente: ``` sudo service aws-kinesis-agent stop ``` Leia o arquivo de log do agente a partir deste local: ``` /var/log/aws-kinesis-agent/aws-kinesis-agent.log ``` Desinstale o agente: ``` sudo yum remove aws-kinesis-agent ``` ## Perguntas frequentes ### Existe um Kinesis Agent para Windows? O [Kinesis Agent para Windows](https://docs.aws.amazon.com/kinesis-agent-windows/latest/userguide/what-is-kinesis-agent-windows.html) é um software diferente das plataformas do Kinesis Agent para Linux. ### Por que a desaceleração do Kinesis Agent está aumentando? and/or `RecordSendErrors` Isso geralmente ocorre devido ao controle de utilização do Kinesis. Verifique a métrica `WriteProvisionedThroughputExceeded` do Kinesis Data Streams ou a métrica `ThrottledRecords` dos fluxos de entrega do Firehose. Qualquer aumento de 0 nessas métricas indica que os limites do fluxo precisam ser aumentados. Para obter mais informações, consulte [Kinesis Data Stream limits](https://docs.aws.amazon.com/streams/latest/dev/service-sizes-and-limits.html) e [Amazon Firehose Delivery Streams](https://docs.aws.amazon.com/firehose/latest/dev/limits.html). Depois de descartar o controle de utilização como causa, verifique se o Kinesis Agent está configurado para seguir um número grande de arquivos pequenos. Há um atraso quando o Kinesis Agent exibe os dados do final de um arquivo novo, portanto, o Kinesis Agent deveria estar exibindo os dados do final de um pequeno número de arquivos maiores. Tente consolidar os arquivos de log em arquivos maiores. ### Por que estou recebendo exceções `java.lang.OutOfMemoryError`? O Kinesis Agent não tem memória suficiente para lidar com a workload atual. Tente aumentar `JAVA_START_HEAP` e `JAVA_MAX_HEAP` no `/usr/bin/start-aws-kinesis-agent` e reiniciar o agente. ### Por que estou recebendo exceções `IllegalStateException : connection pool shut down`? O Kinesis Agent não tem conexões suficientes para lidar com a workload atual. Tente aumentar `maxConnections` e `maxSendingThreads` nas configurações gerais do agente em `/etc/aws-kinesis/agent.json`. O valor padrão para esses campos é 12 vezes o número de processadores de runtime disponíveis. Consulte [AgentConfiguration.java](https://github.com/awslabs/amazon-kinesis-agent/blob/master/src/com/amazon/kinesis/streaming/agent/config/AgentConfiguration.java) para saber mais sobre as configurações avançadas do agente. ### Como posso depurar outro problema com o Kinesis Agent? Os logs do nível `DEBUG` podem ser habilitados em `/etc/aws-kinesis/log4j.xml`. ### Como devo configurar o Kinesis Agent? Quanto menor o `maxBufferSizeBytes`, mais frequentemente o Kinesis Agent enviará dados. Isso pode ser bom, pois diminui o tempo de entrega dos registros, mas também aumenta as solicitações por segundo feitas ao Kinesis. ### Por que o Kinesis Agent está enviando registros duplicados? Isso ocorre devido a uma configuração incorreta da exibição dos dados do final dos arquivos. Certifique-se de que cada `fileFlow’s filePattern` corresponda a apenas um arquivo. Isso também pode ocorrer se o modo `logrotate` que está sendo usado estiver no modo `copytruncate`. Tente mudar o modo para o modo padrão ou criar para evitar duplicações. Para obter mais informações sobre como lidar com registros duplicados, consulte [Handling Duplicate Records](https://docs.aws.amazon.com/streams/latest/dev/kinesis-record-processor-duplicates.html).