# Incorporação de métricas em logs O formato de métricas incorporadas do CloudWatch permite gerar métricas personalizadas de forma assíncrona na forma de logs gravados no CloudWatch Logs. É possível incorporar métricas personalizadas com dados detalhados de eventos de log, e o CloudWatch automaticamente extrairá as métricas personalizadas para que você possa visualizar e criar alarmes para elas visando a detecção de incidentes em tempo real. Além disso, os eventos de log detalhados associados às métricas extraídas podem ser consultados usando o CloudWatch Logs Insights para fornecer insights precisos sobre as causas raízes de eventos operacionais. O formato de métricas incorporadas ajuda a gerar métricas personalizadas acionáveis de recursos efêmeros, como funções e contêineres do Lambda. Agora, ao usar o formato de métricas incorporadas para enviar logs desses recursos efêmeros, é possível criar métricas personalizadas facilmente, sem precisar instrumentar ou manter código separado, ao mesmo tempo que obtém recursos analíticos poderosos nos dados de log. Nenhuma configuração é necessária para usar o formato de métricas incorporadas. Estruture seus logs seguindo a [Especificação do formato de métricas incorporadas](CloudWatch_Embedded_Metric_Format_Specification.md) ou gere-os usando nossas bibliotecas de cliente e envie-os para o CloudWatch Logs usando a [API PutLogEvents](https://docs.aws.amazon.com/AmazonCloudWatchLogs/latest/APIReference/API_PutLogEvents.html) ou o [agente do CloudWatch](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/CloudWatch_Embedded_Metric_Format_Generation_CloudWatch_Agent.html). Para gerar métricas a partir de logs com um formato de métrica incorporado, você precisa da permissão `logs:PutLogEvents`, mas não precisa ter também a permissão `cloudwatch:PutMetricData`. Há cobranças para a ingestão e o arquivamento de logs e para as métricas personalizadas que são geradas. Para obter mais informações, consulte [Preços do Amazon CloudWatch](https://aws.amazon.com/cloudwatch/pricing). **nota** Tenha cuidado ao configurar a extração de métricas, já que isso impacta o uso da métrica personalizada e o faturamento correspondente. Se você criar acidentalmente métricas baseadas em dimensões de alta cardinalidade (como `requestId`), o formato de métricas incorporadas criará por design uma métrica personalizada correspondente a cada combinação de dimensão exclusiva. Para obter mais informações, consulte [Dimensões](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/cloudwatch_concepts.html#Dimension). Os tópicos apresentados a seguir descrevem como publicar logs usando o formato de métricas incorporadas, visualizar as métricas e os logs no console, e definir alarmes para as métricas criadas com o formato de métricas incorporadas. **Topics** + [Publicação de logs com o formato de métricas incorporadas](CloudWatch_Embedded_Metric_Format_Generation.md) + [Visualizar métricas e logs no console](CloudWatch_Embedded_Metric_Format_View.md) + [Configuração de alarmes em métricas criadas com o formato de métricas incorporadas](CloudWatch_Embedded_Metric_Format_Alarms.md) # Publicação de logs com o formato de métricas incorporadas É possível gerar logs no formato de métrica incorporada usando os seguintes métodos: + Gera e envie os logs usando as [bibliotecas de cliente de código aberto](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/CloudWatch_Embedded_Metric_Format_Libraries.html). + Gere manualmente os logs usando a [Especificação do formato de métricas incorporadas](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/CloudWatch_Embedded_Metric_Format_Specification.html), e use em seguida o [agente do CloudWatch](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/CloudWatch_Embedded_Metric_Format_Generation_CloudWatch_Agent.html) ou a [API PutLogEvents](https://docs.aws.amazon.com/AmazonCloudWatchLogs/latest/APIReference/API_PutLogEvents.html) para enviar os logs. Os tópicos apresentados a seguir fornecem mais informações sobre as métricas incorporadas. **Topics** + [Criação de logs no formato de métricas incorporadas usando as bibliotecas clientes](CloudWatch_Embedded_Metric_Format_Libraries.md) + [Especificação: formato de métricas incorporadas](CloudWatch_Embedded_Metric_Format_Specification.md) + [Usar a API PutLogEvents para enviar logs de formato de métricas incorporadas criados manualmente](CloudWatch_Embedded_Metric_Format_Generation_PutLogEvents.md) + [Usar o atendente do CloudWatch para enviar logs de formato de métricas incorporadas](CloudWatch_Embedded_Metric_Format_Generation_CloudWatch_Agent.md) + [Explica como usar o formato de métrica incorporado com o AWS Distro for OpenTelemetry](CloudWatch_Embedded_Metric_Format_OpenTelemetry.md) # Criação de logs no formato de métricas incorporadas usando as bibliotecas clientes É possível usar as bibliotecas de cliente de código aberto que a Amazon fornece para criar logs no formato de métricas incorporadas. Exemplos completos de diferentes configurações podem ser encontrados em nossas bibliotecas de clientes em **/examples**. As bibliotecas e as instruções de como usá-las estão localizadas no GitHub. + [Node.Js](https://github.com/awslabs/aws-embedded-metrics-node) **nota** Para o Node.js, as versões 4.1.1\$1, 3.0.2\$1, 2.0.7\$1 são necessárias para uso com o formato de log JSON do Lambda. O uso de versões anteriores em tais ambientes do Lambda levará à perda de métricas. Para obter mais informações, consulte [Acessar o Amazon CloudWatch Logs para o AWS Lambda](https://docs.aws.amazon.com/lambda/latest/dg/monitoring-cloudwatchlogs.html). + [Python](https://github.com/awslabs/aws-embedded-metrics-python) + [Java](https://github.com/awslabs/aws-embedded-metrics-java) + [C\$1](https://github.com/awslabs/aws-embedded-metrics-dotnet) As bibliotecas de clientes devem funcionar imediatamente com o agente do CloudWatch. Os logs de formato de métrica incorporada gerados são enviados ao agente do CloudWatch, que os agrega e publica no CloudWatch Logs para você. **nota** Ao usar o Lambda, nenhum agente precisa enviar os logs para o CloudWatch. Qualquer coisa registrada em log em STDOUT é enviada ao CloudWatch Logs por meio do agente de logs do Lambda. # Especificação: formato de métricas incorporadas O formato de métrica incorporado do CloudWatch é uma especificação JSON usada para instruir o CloudWatch Logs a extrair automaticamente valores de métrica incorporados em eventos de log estruturados. É possível usar o CloudWatch para criar gráficos e alarmes com relação aos valores de métrica extraídos. Esta seção descreve as convenções de especificação do formato de métricas incorporadas e a estrutura do documento do formato de métricas incorporadas. ## Convenções de especificação do formato de métricas incorporadas As palavras-chave "DEVE", "NÃO DEVE", "OBRIGATÓRIO" "RECOMENDADO", "PODE" e "OPCIONAL" nessa especificação de formato devem ser interpretadas conforme descrito em [Key Words RFC2119](http://tools.ietf.org/html/rfc2119). Os termos "JSON", "texto JSON", "valor JSON", "membro", "elemento", "objeto", "matriz", "número", "string", "booliano", "verdadeiro", "falso" e "nulo" nessa especificação de formato devem ser interpretados conforme definido em [JavaScript Object Notation RFC8259](https://tools.ietf.org/html/rfc8259). **nota** Se você planeja criar alarmes em métricas criadas usando o formato de métricas incorporadas, consulte [Configuração de alarmes em métricas criadas com o formato de métricas incorporadas](CloudWatch_Embedded_Metric_Format_Alarms.md) para obter as recomendações. ## Estrutura de documento de formato de métrica incorporado Esta seção descreve a estrutura de um documento de formato de métricas incorporadas. Os documentos de formato de métricas incorporadas estão definidos em [JavaScript Object Notation RFC8259](https://tools.ietf.org/html/rfc8259). Salvo indicação em contrário, os objetos definidos por essa especificação NÃO DEVEM conter nenhum membro adicional. Os membros não reconhecidos por essa especificação DEVEM ser ignorados. Os membros definidos nessa especificação diferenciam letras maiúsculas de minúsculas. O formato de métrica incorporado está sujeito aos mesmos limites que os eventos padrão do CloudWatch Logs e está limitado ao tamanho máximo de 1 MB. Com o formato de métrica incorporada, você pode acompanhar o processamento de seus logs de EMF por métricas publicadas no namespace `AWS/Logs` da conta. Podem ser usados para rastrear falhas na geração de métricas do EMF, bem como se as falhas ocorrem devido à análise ou validação. Para obter mais informações, consulte [Monitorar com métricas do CloudWatch](https://docs.aws.amazon.com/AmazonCloudWatch/latest/logs/CloudWatch-Logs-Monitoring-CloudWatch-Metrics.html). ### Nó raiz A mensagem de LogEvent DEVE ser um objeto JSON válido sem dados adicionais no início ou no final da string da mensagem de LogEvent. Para obter mais informações sobre a estrutura de LogEvent, consulte [InputLogEvent](https://docs.aws.amazon.com/AmazonCloudWatchLogs/latest/APIReference/API_InputLogEvent.html). Os documentos de formato de métricas incorporadas DEVEM conter o membro de nível superior a seguir no nó raiz. Isso é um objeto [Objeto de metadados](#CloudWatch_Embedded_Metric_Format_Specification_structure_metadata). ``` { "_aws": { "CloudWatchMetrics": [ ... ] } } ``` O nó raiz DEVE conter todos os membros [Membros de destino](#CloudWatch_Embedded_Metric_Format_Specification_structure_target) definidos pelas referências no [Objeto MetricDirective](#CloudWatch_Embedded_Metric_Format_Specification_structure_metricdirective). O nó raiz PODE conter qualquer outro membro que não esteja incluído nos requisitos acima. Os valores desses membros DEVEM ser tipos JSON válidos. ### Objeto de metadados O membro `_aws` pode ser usado para representar metadados sobre a carga útil que informa os serviços downstream como eles devem processar o LogEvent. O valor DEVE ser um objeto e DEVE conter os seguintes membros: + **CloudWatchMetrics**: uma matriz de [Objeto MetricDirective](#CloudWatch_Embedded_Metric_Format_Specification_structure_metricdirective) usada para instruir o CloudWatch a extrair métricas do nó raiz de LogEvent. ``` { "_aws": { "CloudWatchMetrics": [ ... ] } } ``` + **Timestamp**: número que representa o carimbo de data/hora usado para métricas extraídas do evento. Os valores DEVEM ser expressos como o número de milissegundos após 1º de janeiro de 1970 00:00:00 UTC. ``` { "_aws": { "Timestamp": 1559748430481 } } ``` ### Objeto MetricDirective O objeto MetricDirective instrui serviços downstream que o LogEvent contém métricas que serão extraídas e publicadas no CloudWatch. MetricDirectives DEVE conter os seguintes membros: + **Namespace**: uma string que representa o namespace do CloudWatch da métrica. + **Dimensions**: um [Matriz DimensionSet](#CloudWatch_Embedded_Metric_Format_Specification_structure_dimensionset). + **Metrics**: uma matriz de objetos [Objeto MetricDefinition](#CloudWatch_Embedded_Metric_Format_Specification_structure_metricdefinition). Essa matriz NÃO DEVE conter mais de 100 objetos MetricDefinition. ### Matriz DimensionSet Um DimensionSet é uma matriz de strings que contém as chaves de dimensão que serão aplicadas a todas as métricas no documento. Os valores dentro dessa matriz também DEVEM ser membros no nó raiz – referido como o [Membros de destino](#CloudWatch_Embedded_Metric_Format_Specification_structure_target) Um DimensionSet NÃO DEVE conter mais de 30 chaves de dimensão. O DimensionSet PODE estar vazio. O membro de destino DEVE ter um valor de string. Este valor NÃO DEVE conter mais de 1.024 caracteres. O membro de destino define uma dimensão que será publicada como parte da identidade da métrica. Cada DimensionSet usado cria uma métrica no CloudWatch. Para obter mais informações sobre dimensões, consulte [Dimensão](https://docs.aws.amazon.com/AmazonCloudWatch/latest/APIReference/API_Dimension.html) e [Dimensões](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/cloudwatch_concepts.html#Dimension) ``` { "_aws": { "CloudWatchMetrics": [ { "Dimensions": [ [ "functionVersion" ] ], ... } ] }, "functionVersion": "$LATEST" } ``` **nota** Tenha cuidado ao configurar a extração de métricas, já que isso impacta o uso da métrica personalizada e o faturamento correspondente. Se você criar acidentalmente métricas baseadas em dimensões de alta cardinalidade (como `requestId`), o formato de métricas incorporadas criará por design uma métrica personalizada correspondente a cada combinação de dimensão exclusiva. Para obter mais informações, consulte [Dimensões](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/cloudwatch_concepts.html#Dimension). ### Objeto MetricDefinition Um MetricDefinition é um objeto que DEVE conter o seguinte membro: + **Name** (Nome): uma string [Valores de referência](#CloudWatch_Embedded_Metric_Format_Specification_structure_referencevalues) para uma métrica [Membros de destino](#CloudWatch_Embedded_Metric_Format_Specification_structure_target). Os destinos métricos DEVEM ser um valor numérico ou uma matriz de valores numéricos. Um objeto MetricDefinition PODE conter os seguintes membros: + **Unit** (Unit): um valor de string OPCIONAL que representa a unidade de medida da métrica correspondente. Os valores DEVEM ser unidades métricas válidas do CloudWatch. Para obter informações sobre unidades válidas, consulte [MetricDatum](https://docs.aws.amazon.com/AmazonCloudWatch/latest/APIReference/API_MetricDatum.html). Se um valor não for fornecido, então um valor padrão de NONE (NENHUM) será assumido. + **StorageResolution**: um valor inteiro OPCIONAL que representa a resolução de armazenamento da métrica correspondente. Definir isso como 1 especifica essa métrica como uma métrica de alta resolução, de forma que o CloudWatch armazene a métrica com resolução de menos de um minuto de até um segundo. Definir isso como 60 especifica essa métrica como resolução padrão, que o CloudWatch armazena com resolução de 1 minuto. Os valores DEVEM ser resoluções válidas do CloudWatch: 1 ou 60. Se um valor não for fornecido, então um valor padrão de 60 será assumido. Para obter mais informações sobre as métricas de alta resolução, consulte [Métricas de alta resolução](publishingMetrics.md#high-resolution-metrics). **nota** Se você planeja criar alarmes em métricas criadas usando o formato de métricas incorporadas, consulte [Configuração de alarmes em métricas criadas com o formato de métricas incorporadas](CloudWatch_Embedded_Metric_Format_Alarms.md) para obter as recomendações. ``` { "_aws": { "CloudWatchMetrics": [ { "Metrics": [ { "Name": "Time", "Unit": "Milliseconds", "StorageResolution": 60 } ], ... } ] }, "Time": 1 } ``` ### Valores de referência Os valores de referência são valores de string que fazem referência a membros [Membros de destino](#CloudWatch_Embedded_Metric_Format_Specification_structure_target) no nó raiz. Essas referências NÃO devem ser confundidas com os ponteiros JSON descritos em [RFC6901](https://tools.ietf.org/html/rfc6901). Os valores de destino não podem ser aninhados. ### Membros de destino Os destinos válidos DEVEM ser membros no nó raiz e não podem ser objetos aninhados. Por exemplo, um valor \$1reference\$1 de `"A.a"` DEVE corresponder ao seguinte membro: ``` { "A.a" } ``` Ele NÃO DEVE corresponder ao membro aninhado: ``` { "A": { "a" } } ``` Os valores válidos dos membros de destino dependem do que está fazendo referência a eles. Um destino métrico DEVE ser um valor numérico ou uma matriz de valores numéricos. Os destinos da métrica da matriz numérica NÃO PODEM ter mais de 100 membros. Um destino de dimensão DEVE ter um valor de string. ### Exemplo de formato de métricas incorporadas e esquema JSON Veja a seguir um exemplo válido de formato de métricas incorporadas. ``` { "_aws": { "Timestamp": 1574109732004, "CloudWatchMetrics": [ { "Namespace": "lambda-function-metrics", "Dimensions": [["functionVersion"]], "Metrics": [ { "Name": "time", "Unit": "Milliseconds", "StorageResolution": 60 } ] } ] }, "functionVersion": "$LATEST", "time": 100, "requestId": "989ffbf8-9ace-4817-a57c-e4dd734019ee" } ``` É possível usar o esquema a seguir para validar documentos de formato de métricas incorporadas. ``` { "type": "object", "title": "Root Node", "required": [ "_aws" ], "properties": { "_aws": { "$id": "#/properties/_aws", "type": "object", "title": "Metadata", "required": [ "Timestamp", "CloudWatchMetrics" ], "properties": { "Timestamp": { "$id": "#/properties/_aws/properties/Timestamp", "type": "integer", "title": "The Timestamp Schema", "examples": [ 1565375354953 ] }, "CloudWatchMetrics": { "$id": "#/properties/_aws/properties/CloudWatchMetrics", "type": "array", "title": "MetricDirectives", "items": { "$id": "#/properties/_aws/properties/CloudWatchMetrics/items", "type": "object", "title": "MetricDirective", "required": [ "Namespace", "Dimensions", "Metrics" ], "properties": { "Namespace": { "$id": "#/properties/_aws/properties/CloudWatchMetrics/items/properties/Namespace", "type": "string", "title": "CloudWatch Metrics Namespace", "examples": [ "MyApp" ], "pattern": "^(.*)$", "minLength": 1, "maxLength": 1024 }, "Dimensions": { "$id": "#/properties/_aws/properties/CloudWatchMetrics/items/properties/Dimensions", "type": "array", "title": "The Dimensions Schema", "minItems": 1, "items": { "$id": "#/properties/_aws/properties/CloudWatchMetrics/items/properties/Dimensions/items", "type": "array", "title": "DimensionSet", "minItems": 0, "maxItems": 30, "items": { "$id": "#/properties/_aws/properties/CloudWatchMetrics/items/properties/Dimensions/items/items", "type": "string", "title": "DimensionReference", "examples": [ "Operation" ], "pattern": "^(.*)$", "minLength": 1, "maxLength": 250 } } }, "Metrics": { "$id": "#/properties/_aws/properties/CloudWatchMetrics/items/properties/Metrics", "type": "array", "title": "MetricDefinitions", "items": { "$id": "#/properties/_aws/properties/CloudWatchMetrics/items/properties/Metrics/items", "type": "object", "title": "MetricDefinition", "required": [ "Name" ], "properties": { "Name": { "$id": "#/properties/_aws/properties/CloudWatchMetrics/items/properties/Metrics/items/properties/Name", "type": "string", "title": "MetricName", "examples": [ "ProcessingLatency" ], "pattern": "^(.*)$", "minLength": 1, "maxLength": 1024 }, "Unit": { "$id": "#/properties/_aws/properties/CloudWatchMetrics/items/properties/Metrics/items/properties/Unit", "type": "string", "title": "MetricUnit", "examples": [ "Milliseconds" ], "pattern": "^(Seconds|Microseconds|Milliseconds|Bytes|Kilobytes|Megabytes|Gigabytes|Terabytes|Bits|Kilobits|Megabits|Gigabits|Terabits|Percent|Count|Bytes\\/Second|Kilobytes\\/Second|Megabytes\\/Second|Gigabytes\\/Second|Terabytes\\/Second|Bits\\/Second|Kilobits\\/Second|Megabits\\/Second|Gigabits\\/Second|Terabits\\/Second|Count\\/Second|None)$" }, "StorageResolution": { "$id": "#/properties/_aws/properties/CloudWatchMetrics/items/properties/Metrics/items/properties/StorageResolution", "type": "integer", "title": "StorageResolution", "examples": [ 60 ] } } } } } } } } } } } ``` ## Informações da entidade no formato EMF Ao publicar logs no Amazon CloudWatch usando o formato Embedded Metric Format (EMF), é possível incluir informações da entidade no evento de log. Esta seção descreve como especificar as informações da entidade e como o CloudWatch processa essas informações. ### Tipos de entidade Quando nenhuma entidade for especificada com a solicitação `PutLogEvents`, o CloudWatch procurará as informações da entidade no conteúdo do log EMF: + **Entidades do tipo serviço** Campos obrigatórios: `Service` e `Environment` + **Entidades do tipo recurso** Campos obrigatórios: `ResourceType` e `Identifier` ### Atributos da plataforma O CloudWatch determina automaticamente o tipo da plataforma com base nesses atributos: + **Kubernetes (K8s):** Obrigatório: `K8s.Cluster` Opcional: `K8s.Namespace`, `K8s.Workload`, `K8s.Node`, `K8s.Pod`, `EC2.InstanceId`, `EC2.AutoScalingGroup` + **Amazon EKS** Obrigatório: `EKS.Cluster` Opcional: `K8s.Namespace`, `K8s.Workload`, `K8s.Node`, `K8s.Pod`, `EC2.InstanceId` + **Amazon ECS:** Obrigatório: `ECS.Cluster` Opcional: `ECS.Service`, `ECS.Task` + **Amazon EC2** Obrigatório: `EC2.InstanceId` Opcional: `EC2.AutoScalingGroup` + **Lambda:** Obrigatório: `Lambda.Function` + **Hosts genéricos:** Obrigatório: `Host` ### Exemplo de formato de log EMF ``` { "_aws": { "CloudWatchMetrics": [ { "Metrics": [ {"Name": "RequestLatency", "Unit": "Milliseconds"} ], "Namespace": "MyApplication" } ] }, "Service": "PaymentService", "Environment": "Production", "K8s.Cluster": "main-cluster", "K8s.Namespace": "payment-ns", "K8s.Pod": "payment-pod-123", "K8s.Node": "worker-node-1", "K8s.Workload": "payment-deployment", "RequestLatency": 135.5, "timestamp": 1622163600000 } ``` ### Entidade gerada O log EMF acima gerará a seguinte entidade: ``` { "KeyAttributes": { "Type": "Service", "Name": "PaymentService", "Environment": "Production" }, "Attributes": { "PlatformType": "K8s", "K8s.Cluster": "main-cluster", "K8s.Namespace": "payment-ns", "K8s.Pod": "payment-pod-123", "K8s.Node": "worker-node-1", "K8s.Workload": "payment-deployment" } } ``` ### Processamento de entidade O CloudWatch processa as informações da entidade da seguinte forma: + **KeyAttributes:** + Determina o tipo da entidade com base nos campos obrigatórios + Para o tipo serviço, extrai o nome e o ambiente do serviço + Esses se tornam os identificadores primários da entidade + **Atributos:** + Define PlatformType com base nos atributos de plataforma incluídos + Inclui todas as informações relevantes específicas da plataforma + Mantém o contexto de relacionamento para os dados de telemetria O CloudWatch usa essas informações da entidade para estabelecer relações entre diferentes partes dos dados de telemetria, permitindo a observabilidade aprimorada e a análise contextual de suas aplicações e infraestrutura. Para obter mais informações, consulte [Como adicionar informações relacionadas à telemetria personalizada enviada ao CloudWatch](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/adding-your-own-related-telemetry.html). **nota** As informações da entidade ajudam o CloudWatch a criar uma imagem completa dos dados de telemetria da sua aplicação e seus relacionamentos dentro da sua infraestrutura. # Usar a API PutLogEvents para enviar logs de formato de métricas incorporadas criados manualmente É possível enviar logs no formato de métricas incorporadas para o CloudWatch Logs usando a API [PutLogEvents](https://docs.aws.amazon.com/AmazonCloudWatchLogs/latest/APIReference/API_PutLogEvents.html) do CloudWatch Logs. Ao chamar PutLogEvents, você tem a opção de incluir o cabeçalho HTTP apresentado a seguir, que informa ao CloudWatch Logs que as métricas devem ser extraídas, mas isso não é obrigatório. ``` x-amzn-logs-format: json/emf ``` Veja a seguir um exemplo completo usando o AWS SDK for Java 2.x: ``` package org.example.basicapp; import software.amazon.awssdk.regions.Region; import software.amazon.awssdk.services.cloudwatchlogs.CloudWatchLogsClient; import software.amazon.awssdk.services.cloudwatchlogs.model.DescribeLogStreamsRequest; import software.amazon.awssdk.services.cloudwatchlogs.model.DescribeLogStreamsResponse; import software.amazon.awssdk.services.cloudwatchlogs.model.InputLogEvent; import software.amazon.awssdk.services.cloudwatchlogs.model.PutLogEventsRequest; import java.util.Collections; public class EmbeddedMetricsExample { public static void main(String[] args) { final String usage = "To run this example, supply a Region code (eg. us-east-1), log group, and stream name as command line arguments" + "Ex: PutLogEvents "; if (args.length != 3) { System.out.println(usage); System.exit(1); } String regionId = args[0]; String logGroupName = args[1]; String logStreamName = args[2]; CloudWatchLogsClient logsClient = CloudWatchLogsClient.builder().region(Region.of(regionId)).build(); // Build a JSON log using the EmbeddedMetricFormat. long timestamp = System.currentTimeMillis(); String message = "{" + " \"_aws\": {" + " \"Timestamp\": " + timestamp + "," + " \"CloudWatchMetrics\": [" + " {" + " \"Namespace\": \"MyApp\"," + " \"Dimensions\": [[\"Operation\"], [\"Operation\", \"Cell\"]]," + " \"Metrics\": [{ \"Name\": \"ProcessingLatency\", \"Unit\": \"Milliseconds\", \"StorageResolution\": 60 }]" + " }" + " ]" + " }," + " \"Operation\": \"Aggregator\"," + " \"Cell\": \"001\"," + " \"ProcessingLatency\": 100" + "}"; InputLogEvent inputLogEvent = InputLogEvent.builder() .message(message) .timestamp(timestamp) .build(); // Specify the request parameters. PutLogEventsRequest putLogEventsRequest = PutLogEventsRequest.builder() .logEvents(Collections.singletonList(inputLogEvent)) .logGroupName(logGroupName) .logStreamName(logStreamName) .build(); logsClient.putLogEvents(putLogEventsRequest); System.out.println("Successfully put CloudWatch log event"); } } ``` **nota** Com o formato de métrica incorporada, você pode acompanhar o processamento de seus logs de EMF por métricas publicadas no namespace `AWS/Logs` da conta. Podem ser usados para rastrear falhas na geração de métricas do EMF, bem como se as falhas ocorrem devido à análise ou validação. Para obter mais informações, consulte [Monitorar com métricas do CloudWatch](https://docs.aws.amazon.com/AmazonCloudWatch/latest/logs/CloudWatch-Logs-Monitoring-CloudWatch-Metrics.html). # Usar o atendente do CloudWatch para enviar logs de formato de métricas incorporadas Esta seção descreve como instalar e usar o agente do CloudWatch. Na primeira parte desta seção, é abordado como instalar o agente do CloudWatch. Na segunda parte desta seção, é explicado como usar o agente do CloudWatch para enviar logs no formato de métricas incorporadas. Caso deseje usar este método, é necessário instalar o agente do CloudWatch para os Serviços da AWS dos quais deseja enviar logs no formato de métricas incorporadas. Em seguida, você pode começar a enviar os eventos. O atendente do CloudWatch deve ser da versão 1.230621.0 ou posterior. **nota** Não é necessário instalar o atendente do CloudWatch para enviar logs de funções do Lambda. Os tempos limite da função do Lambda não são processados automaticamente. Isso significa que se a função atingir o tempo limite antes de as métricas serem liberadas, as métricas dessa invocação não serão capturadas. ## Instalação do atendente do CloudWatch Instale o atendente do CloudWatch para cada serviço que ´deve enviar logs de formato de métrica incorporado. ### Instalar o atendente do CloudWatch no EC2 Primeiro, instale o atendente do CloudWatch na instância. Para obter mais informações, consulte [Instalação do atendente do CloudWatch](install-CloudWatch-Agent-on-EC2-Instance.md). Após instalar o atendente, configure-o para escutar em uma porta UDP ou TCP para os logs de formato de métricas incorporadas. Veja a seguir um exemplo dessa configuração que escuta no soquete padrão `tcp:25888`. Para obter mais informações sobre a configuração do atendente, consulte [Criar ou editar manualmente o arquivo de configuração do atendente do CloudWatch](CloudWatch-Agent-Configuration-File-Details.md). ``` { "logs": { "metrics_collected": { "emf": { } } } } ``` ### Instalar o atendente do CloudWatch no Amazon ECS A maneira mais fácil de implantar o atendente do CloudWatch no Amazon ECS é executá-lo como um arquivo associado, definindo-o na mesma definição de tarefa da aplicação. **Criar um arquivo de configuração do atendente** Crie o arquivo de configuração do atendente do CloudWatch localmente. Neste exemplo, o caminho do arquivo relativo será `amazon-cloudwatch-agent.json`. Para obter mais informações sobre a configuração do atendente, consulte [Criar ou editar manualmente o arquivo de configuração do atendente do CloudWatch](CloudWatch-Agent-Configuration-File-Details.md). ``` { "logs": { "metrics_collected": { "emf": { } } } } ``` **Enviar configuração para o SSM Parameter Store ** Insira o comando a seguir para enviar o arquivo de configuração do atendente do CloudWatch ao AWS Systems Manager (SSM) Parameter Store. ``` aws ssm put-parameter \ --name "cwagentconfig" \ --type "String" \ --value "`cat amazon-cloudwatch-agent.json`" \ --region "{{region}}" ``` **Configurar a definição da tarefa** Configure a definição de tarefa para usar o atendente do CloudWatch e expor a porta TCP ou UDP. A definição de tarefa de amostra que você deve usar depende do modo de rede. Observe que o `webapp` especifica a variável de ambiente `AWS_EMF_AGENT_ENDPOINT`. Isso é usado pela biblioteca e deve apontar para o endpoint no qual o atendente está escutando. Além disso, o `cwagent` especifica o `CW_CONFIG_CONTENT` como um parâmetro “valueFrom” que aponta para a configuração do SSM criada na etapa anterior. Esta seção contém um exemplo para o modo ponte e um exemplo para o modo host ou awsvpc. Para obter mais exemplos de como configurar o atendente do CloudWatch no Amazon ECS, consulte o [Repositório de exemplos do Github](https://github.com/aws-samples/amazon-cloudwatch-container-insights/tree/master/ecs-task-definition-templates/deployment-mode/sidecar) Veja a seguir um exemplo do modo de ponte. Quando o modo de ponte de redes está habilitado, o atendente precisa estar vinculado à aplicação usando o parâmetro `links` e deve ser abordado usando o nome do contêiner. ``` { "containerDefinitions": [ { "name": "webapp", "links": [ "cwagent" ], "image": "my-org/web-app:latest", "memory": 256, "cpu": 256, "environment": [{ "name": "AWS_EMF_AGENT_ENDPOINT", "value": "tcp://cwagent:25888" }], }, { "name": "cwagent", "mountPoints": [], "image": "public.ecr.aws/cloudwatch-agent/cloudwatch-agent:latest", "memory": 256, "cpu": 256, "portMappings": [{ "protocol": "tcp", "containerPort": 25888 }], "environment": [{ "name": "CW_CONFIG_CONTENT", "valueFrom": "cwagentconfig" }], } ], } ``` Veja a seguir um exemplo do modo de host ou modo awsvpc. Ao executar esses modos de rede, o atendente pode ser abordado como `localhost`. ``` { "containerDefinitions": [ { "name": "webapp", "image": "my-org/web-app:latest", "memory": 256, "cpu": 256, "environment": [{ "name": "AWS_EMF_AGENT_ENDPOINT", "value": "tcp://127.0.0.1:25888" }], }, { "name": "cwagent", "mountPoints": [], "image": "public.ecr.aws/cloudwatch-agent/cloudwatch-agent:latest", "memory": 256, "cpu": 256, "portMappings": [{ "protocol": "tcp", "containerPort": 25888 }], "environment": [{ "name": "CW_CONFIG_CONTENT", "valueFrom": "cwagentconfig" }], } ], } ``` **nota** No modo awsvpc, é necessário atribuir um endereço IP público à VPC (somente Fargate), configurar um gateway NAT ou definir um endpoint da VPC do CloudWatch Logs. Para obter mais informações sobre como configurar um NAT, consulte [Gateways NAT](https://docs.aws.amazon.com/vpc/latest/userguide/vpc-nat-gateway.html). Para obter mais informações sobre como configurar um endpoint da VPC do CloudWatch Logs,consulte [Usar o CloudWatch Logs com endpoints da VPC de interface](https://docs.aws.amazon.com/AmazonCloudWatch/latest/logs/cloudwatch-logs-and-interface-VPC.html). Veja a seguir um exemplo de como atribuir um endereço IP público a uma tarefa que usa o tipo de inicialização do Fargate. ``` aws ecs run-task \ --cluster {{cluster-name}} \ --task-definition cwagent-fargate \ --region {{region}} \ --launch-type FARGATE \ --network-configuration "awsvpcConfiguration={subnets=[{{subnetId}}],securityGroups=[{{sgId}}],assignPublicIp=ENABLED}" ``` **Verificar permissões** Verifique se a função do IAM que está executando as tarefas tem permissão para ler do SSM Parameter Store. É possível adicionar essa permissão anexando a política **AmazonSSMReadOnlyAccess**. Para fazer isso, insira o comando a seguir. ``` aws iam attach-role-policy --policy-arn arn:aws:iam::aws:policy/AmazonSSMReadOnlyAccess \ --role-name CWAgentECSExecutionRole ``` ### Instalar o atendente do CloudWatch no Amazon EKS Partes desse processo podem ser puladas caso o CloudWatch Container Insights já esteja instalado nesse cluster. Permissões Se você ainda não instalou o Container Insights, primeiro verifique se os nós do Amazon EKS têm as permissões do IAM apropriadas. Eles devem ter a **CloudWatchAgentServerPolicy** anexada. Para obter mais informações, consulte [Verificação dos pré-requisitos para o Container Insights no CloudWatch](Container-Insights-prerequisites.md). **Criar ConfigMap** Criar um ConfigMap para o atendente O ConfigMap também informa ao atendente para escutar em uma porta TCP ou UDP. Use o ConfigMap a seguir. ``` # cwagent-emf-configmap.yaml apiVersion: v1 data: # Any changes here must not break the JSON format cwagentconfig.json: | { "agent": { "omit_hostname": true }, "logs": { "metrics_collected": { "emf": { } } } } kind: ConfigMap metadata: name: cwagentemfconfig namespace: default ``` Se o Container Insights já estiver instalado, adicione a linha `"emf": { }` a seguir ao ConfigMap existente. **Aplicar o ConfigMap** Insira o comando a seguir para aplicar o ConfigMap. ``` kubectl apply -f cwagent-emf-configmap.yaml ``` **Implantar o atendente** Para implantar o atendente do CloudWatch como um arquivo associado, adicione o atendente à definição do pod, conforme o exemplo a seguir. ``` apiVersion: v1 kind: Pod metadata: name: myapp namespace: default spec: containers: # Your container definitions go here - name: web-app image: my-org/web-app:latest # CloudWatch Agent configuration - name: cloudwatch-agent image: public.ecr.aws/cloudwatch-agent/cloudwatch-agent:latest imagePullPolicy: Always resources: limits: cpu: 200m memory: 100Mi requests: cpu: 200m memory: 100Mi volumeMounts: - name: cwagentconfig mountPath: /etc/cwagentconfig ports: # this should match the port configured in the ConfigMap - protocol: TCP hostPort: 25888 containerPort: 25888 volumes: - name: cwagentconfig configMap: name: cwagentemfconfig ``` ## Usar o atendente do CloudWatch para enviar logs de formato de métricas incorporadas Após instalar e executar o atendente do CloudWatch, é possível enviar logs de formato de métrica incorporado por TCP ou UDP. Há dois requisitos ao enviar os logs pelo atendente: + Os logs devem conter uma chave `LogGroupName` que informa ao atendente qual grupo de logs deve ser usado. + Cada evento de log deve estar em uma única linha. Em outras palavras, um evento de log não pode conter o caractere de nova linha (\$1n). Os eventos de log também devem seguir a especificação do formato de métricas incorporadas. Para obter mais informações, consulte [Especificação: formato de métricas incorporadas](CloudWatch_Embedded_Metric_Format_Specification.md). Se você planeja criar alarmes em métricas criadas usando o formato de métricas incorporadas, consulte [Configuração de alarmes em métricas criadas com o formato de métricas incorporadas](CloudWatch_Embedded_Metric_Format_Alarms.md) para obter as recomendações. Veja a seguir um exemplo de como enviar eventos de log manualmente de um shell bash do Linux. Em vez disso, é possível usar as interfaces de soquete UDP fornecidas pela linguagem de programação da sua escolha. ``` echo '{"_aws":{"Timestamp":1574109732004,"LogGroupName":"Foo","CloudWatchMetrics":[{"Namespace":"MyApp","Dimensions":[["Operation"]],"Metrics":[{"Name":"ProcessingLatency","Unit":"Milliseconds","StorageResolution":60}]}]},"Operation":"Aggregator","ProcessingLatency":100}' \ > /dev/udp/0.0.0.0/25888 ``` **nota** Com o formato de métrica incorporada, você pode acompanhar o processamento de seus logs de EMF por métricas publicadas no namespace `AWS/Logs` da conta. Podem ser usados para rastrear falhas na geração de métricas do EMF, bem como se as falhas ocorrem devido à análise ou validação. Para obter mais informações, consulte [Monitorar com métricas do CloudWatch](https://docs.aws.amazon.com/AmazonCloudWatch/latest/logs/CloudWatch-Logs-Monitoring-CloudWatch-Metrics.html). # Explica como usar o formato de métrica incorporado com o AWS Distro for OpenTelemetry O OpenTelemetry é uma iniciativa de código aberto que remove limites e restrições entre formatos específicos do fornecedor para rastreamento, logs e métricas, oferecendo um único conjunto de especificações e APIs. Para obter mais informações, consulte [OpenTelemetry](https://opentelemetry.io/). É possível usar o formato de métrica incorporado como parte do projeto OpenTelemetry. O uso do formato de métricas incorporadas com o OpenTelemetry requer dois componentes: uma fonte de dados compatível com o OpenTelemetry e o AWS Distro para OpenTelemetry Collector habilitado para uso com os logs de métricas incorporadas do CloudWatch. Disponibilizamos redistribuições configuradas previamente dos componentes do OpenTelemetry, que são mantidas pela AWS, para tornar o processo de integração o mais fácil possível. Para obter mais informações sobre como usar o OpenTelemetry com o formato de métricas incorporadas, além de outros serviços da AWS, consulte [AWS Distro para OpenTelemetry](https://aws-otel.github.io/). Para obter mais informações sobre compatibilidade de idiomas e uso, consulte [Observabilidade da AWS no Github](https://github.com/aws-observability). # Visualizar métricas e logs no console Após gerar logs de formato de métricas incorporadas que extraem métricas, é possível usar o console do CloudWatch para visualizar as métricas. As métricas incorporadas terão as dimensões especificadas ao gerar os logs. Além disso, as métricas incorporadas que você gerou usando as bibliotecas de cliente têm as seguintes dimensões padrão: + ServiceType + ServiceName + LogGroup Esta seção descreve como visualizar essas métricas no console do CloudWatch e consultar as métricas extraídas usando o [CloudWatch Logs Insights](https://docs.aws.amazon.com/AmazonCloudWatch/latest/logs/AnalyzingLogData.html). **Como visualizar métricas geradas de logs de formato de métricas incorporadas** 1. Abra o console do CloudWatch em [https://console.aws.amazon.com/cloudwatch/](https://console.aws.amazon.com/cloudwatch/). 1. No painel de navegação, selecione **Métricas**. 1. Selecione um namespace especificado para as métricas incorporadas ao gerá-las. Se você usou bibliotecas de cliente para gerar as métricas e não especificou um namespace, selecione **aws-embedded-metrics**. Esse é o namespace padrão de métricas incorporadas geradas usando as bibliotecas de cliente. 1. Selecione uma dimensão de métrica (por exemplo, **ServiceName**). 1. A guia **Todas as métricas** exibe todas as métricas dessa dimensão no namespace. Você pode fazer o seguinte: 1. Para classificar a tabela, use o cabeçalho da coluna. 1. Para criar um gráfico de uma métrica, marque a caixa de seleção ao lado da métrica. Para selecionar todas as métricas, marque a caixa de seleção na linha de cabeçalho da tabela. 1. Para filtrar por recurso, escolha o ID do recurso e, em seguida, escolha **Adicionar à pesquisa**. 1. Para filtrar por métrica, selecione o nome da métrica e, em seguida, escolha **Adicionar à pesquisa**. **Consultar logs usando o CloudWatch Logs Insights** É possível consultar os eventos de log detalhados associados às métricas extraídas usando o CloudWatch Logs Insights para fornecer insights mais profundos sobre as causas raízes de eventos operacionais. Um dos benefícios da extração de métricas dos logs é a possibilidade de filtrar os logs posteriormente pela métrica (nome da métrica mais conjunto de dimensões exclusivo) e pelos valores de métrica exclusivos, a fim de obter contexto para os eventos que contribuíram para o valor da métrica agregada. Por exemplo, para obter o ID de uma solicitação afetada ou o ID de um rastreamento do X-Ray, você pode executar a consulta a seguir no CloudWatch Logs Insights. ``` filter Latency > 1000 and Operation = "Aggregator" | fields RequestId, TraceId ``` Também é possível executar a agregação de tempo de consulta em chaves de alta cardinalidade, como localizar os clientes afetados por um evento. Isso é ilustrado no exemplo a seguir. ``` filter Latency > 1000 and Operation = "Aggregator" | stats count() by CustomerId ``` Para obter mais informações, consulte [Analisar os dados de log com o CloudWatch Logs Insights](https://docs.aws.amazon.com/AmazonCloudWatch/latest/logs/AnalyzingLogData.html) # Configuração de alarmes em métricas criadas com o formato de métricas incorporadas Em geral, a criação de alarmes em métricas geradas pelo formato de métricas incorporadas segue o mesmo padrão de criação de alarmes em qualquer outra métrica. Para obter mais informações, consulte [Usar alarmes do Amazon CloudWatch](CloudWatch_Alarms.md). A geração de métricas no formato de métricas incorporadas depende do fluxo de publicação de logs, pois o CloudWatch Logs precisa processar os logs para que possam ser transformados em métricas. É fundamental publicar os logs em tempo hábil, para que os pontos de dados das métricas sejam criados durante o período em que os alarmes são avaliados. Se você planeja usar o formato de métricas incorporadas para enviar métricas de alta resolução e criar alarmes para essas métricas, recomendamos que você envie os logs para o CloudWatch Logs em intervalos de cinco segundos ou menos, a fim de evitar a introdução de um atraso adicional, que pode resultar em alarmes por dados parciais ou ausentes. Se você estiver usando o agente do CloudWatch, poderá ajustar o intervalo de descarga definindo o parâmetro `force_flush_interval` no arquivo de configuração do agente do CloudWatch. O padrão para esse valor é de 5 segundos. Se você estiver usando o Lambda em outras plataformas nas quais não seja possível controlar o intervalo de liberação dos logs, considere usar alarmes “M de N” para controlar o número de pontos de dados usados para acionar o alarme. Para obter mais informações, consulte [Avaliação de alarme](alarm-evaluation.md).