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
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
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 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
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 256 KB.
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.
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.
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.
{ "_aws": { "CloudWatchMetrics": [ ... ] } }
O nó raiz DEVE conter todos os membros Membros de destino definidos pelas referências no Objeto 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 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.
Metrics: uma matriz de objetos 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
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 e Dimensões
{ "_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.
Objeto MetricDefinition
Um MetricDefinition é um objeto que DEVE conter o seguinte membro:
Name (Nome): uma string Valores de referência para uma métrica Membros de destino. 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. 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.
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 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 no nó raiz. Essas referências NÃO devem ser confundidas com os ponteiros JSON descritos em RFC6901
Membros de destino
Os destinos válidos DEVEM ser membros no nó raiz e não podem ser objetos aninhados. Por exemplo, um valor _reference_ 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 ] } } } } } } } } } } }
