Usar um modelo Criar uma fonte de dados personalizada do zero

Criar um conector personalizado para uma fonte de dados

Para conectar uma fonte de dados personalizada ao CloudWatch, você tem duas opções:

Comece usando uma amostra de modelo fornecida pelo CloudWatch. Você pode usar JavaScript ou Python com esse modelo. Esses modelos incluem exemplos de código do Lambda que serão úteis para você criar a função do Lambda. Em seguida, você pode modificar a função do Lambda com base no modelo para se conectar à sua fonte de dados personalizada.
Crie do zero uma função do AWS Lambda que implemente o conector da fonte de dados, a consulta de dados e a preparação da série temporal para uso pelo CloudWatch. Essa função deve pré-agregar ou mesclar pontos de dados, se necessário, e também alinhar o período e os carimbos de data/hora para serem compatíveis com o CloudWatch.

Sumário

Usar um modelo

O uso de um modelo cria um exemplo da função do Lambda e pode ajudar você a criar o conector personalizado com mais rapidez. Esses exemplos de funções fornecem exemplos de código para muitos cenários comuns envolvidos na criação de um conector personalizado. Você pode examinar o código do Lambda depois de criar um conector com um modelo e modificá-lo para usá-lo para se conectar à fonte de dados.

Além disso, se você usar o modelo, o CloudWatch se encarregará de criar a política de permissões do Lambda e anexará tags de recursos à função do Lambda.

Como usar o modelo para criar um conector para uma fonte de dados personalizada

Abra o console CloudWatch em https://console.aws.amazon.com/cloudwatch/.
No painel de navegação, selecione Configurações.
Escolha a guia Fontes de dados de métricas.
Escolha Criar fonte de dados.
Escolha o botão de opção em Personalizado: conceitos básicos do modelo e, em seguida, escolha Próximo.
Insira um nome para a fonte de dados.
Selecione um dos modelos listados.
Selecione Node.js ou Python.
Escolha Criar fonte de dados.

A nova fonte personalizada que você acabou de adicionar não será exibida até que a pilha do AWS CloudFormation termine de criá-la. Para verificar o progresso, escolha Visualizar o status da minha pilha do CloudFormation. Como alternativa, você pode escolher o ícone de atualização para atualizar essa lista.

Quando sua nova fonte de dados for exibida nessa lista, ela estará pronta para ser testada no console e modificada.
(Opcional) Para consultar os dados de teste dessa fonte no console, siga as instruções em Criar um gráfico de métricas com base em outra fonte de dados.
Modifique a função do Lambda de acordo com suas necessidades.
1. No painel de navegação, selecione Configurações.
2. Escolha a guia Fontes de dados de métricas.
3. Escolha Visualizar no console do Lambda para a fonte que você deseja modificar.
Agora, é possível modificar a função para acessar a fonte de dados. Para ter mais informações, consulte Etapa 1: criar a função.

nota
Se usar o modelo quando escrever a função do Lambda, você não precisará seguir as instruções em Etapa 2: criar uma política de permissões do Lambda ou Etapa 3: anexar uma tag de recurso à função do Lambda. Essas etapas foram executadas pelo CloudWatch porque você usou o modelo.

Criar uma fonte de dados personalizada do zero

Siga as etapas nesta seção para criar uma função do Lambda que conecte o CloudWatch a uma fonte de dados.

Etapa 1: criar a função

O conector de uma fonte de dados personalizada deve ser compatível com eventos GetMetricData do CloudWatch. Opcionalmente, você também pode implementar um evento DescribeGetMetricData para fornecer documentação aos usuários no console do CloudWatch sobre como usar o conector. A resposta DescribeGetMetricData também pode ser usada para definir os padrões que serão usados no construtor de consultas personalizadas do CloudWatch.

O CloudWatch fornece trechos de código como exemplos para ajudar você a começar. Para obter mais informações, consulte o repositório de exemplos em https://github.com/aws-samples/cloudwatch-data-source-samples.

Restrições

A resposta do Lambda deve ser menor que 6 Mb. Se a resposta exceder 6 Mb, a resposta GetMetricData marcará a função do Lambda como InternalError e nenhum dado será retornado.
A função do Lambda deve concluir a execução em até dez segundos para fins de visualização e criação de painéis, ou em até 4,5 segundos para uso de alarmes. Se o tempo de execução exceder esse tempo, a resposta GetMetricData marcará a função do Lambda como InternalError e nenhum dado será retornado.
A função do Lambda deve enviar a saída usando carimbos de data/hora de período em segundos.
Se a função do Lambda não amostrar os dados novamente e, em vez disso, retornar dados que não correspondam à hora de início e à duração do período solicitados pelo usuário do CloudWatch, esses dados serão ignorados pelo CloudWatch. Os dados adicionais são descartados de qualquer visualização ou alarme. Qualquer dado que não esteja entre a hora de início e a hora de término também é descartado.

Por exemplo, se o usuário solicitar dados das 10:00 às 11:00 com um período de cinco minutos, “10:00:00 a 10:04:59” e “10:05:00 a 10:09:59” serão os intervalos de tempo válidos para que os dados sejam retornados. Você deve retornar uma série temporal que inclua 10:00 value1, 10:05 value2 e assim por diante. Se a função retornar 10:03 valueX, por exemplo, ela será descartada porque 10:03 não corresponde à hora de início e ao período solicitados.
As consultas de várias linhas não são compatíveis com os conectores de fonte de dados do CloudWatch. Cada feed de linha é substituído por um espaço quando a consulta é executada ou quando você cria um alarme ou um widget de painel com a consulta. Em alguns casos, isso pode tornar a consulta inválida.

Evento GetMetricData

Carga da solicitação

Veja a seguir um exemplo de uma carga da solicitação GetMetricData enviada como entrada para a função do Lambda.


{
  "EventType": "GetMetricData",
  "GetMetricDataRequest": {
    "StartTime": 1697060700,
    "EndTime": 1697061600,
    "Period": 300,
    "Arguments": ["serviceregistry_external_http_requests{host_cluster!=\"prod\"}"] 
  }
}

StartTime: o carimbo de data/hora que especifica os primeiros dados a serem retornados. O Tipo é o período do carimbo de data/hora em segundos.
EndTime: o carimbo de data/hora que especifica os últimos dados a serem retornados. O Tipo é o período do carimbo de data/hora em segundos.
Período: o número de segundos que cada agregação dos dados de métricas representa. O mínimo é 60 segundos. O Tipo é Segundos.
Argumentos: matriz de argumentos a serem passados para a expressão matemática de métricas do Lambda. Para obter mais informações sobre como passar argumentos, consulte Como passar argumentos para sua função do Lambda.

Carga da resposta

Veja a seguir um exemplo de carga da resposta GetMetricData retornada pela função do Lambda.


{
   "MetricDataResults": [
      {
         "StatusCode": "Complete",
         "Label": "CPUUtilization",
         "Timestamps": [ 1697060700, 1697061000, 1697061300 ],
         "Values": [ 15000, 14000, 16000 ]
      }
   ]
}

A carga da resposta conterá um campo MetricDataResults ou um campo Error, mas não ambos.

Um campo MetricDataResults é uma lista de campos de séries temporais do tipo MetricDataResult. Cada um desses campos de séries temporais pode incluir os campos a seguir.

StatusCode: (opcional) Complete indica que todos os pontos de dados no intervalo de tempo solicitado foram retornados. PartialData significa que um conjunto incompleto de pontos de dados foi retornado. Se isso for omitido, o padrão será Complete.

Valores válidos: Complete | InternalError | PartialData | Forbidden
Mensagens: lista opcional de mensagens com informações adicionais sobre os dados retornados.

Tipo: matriz de objetos MessageData com strings Code e Value.
Rótulo: o rótulo legível por humanos associado aos dados.

Tipo: sequência
Carimbos de data/hora: os carimbos de data/hora dos pontos de dados, formatados em períodos. O número de carimbos de data/hora sempre corresponde ao número de valores, e o valor para Timestamps[x] é Values[x].

Tipo: matriz de carimbos de data/hora
Valores: os valores dos pontos de dados da métrica, correspondentes a Timestamps. O número de valores sempre corresponde ao número de carimbos de data/hora, e o valor para Timestamps[x] é Values[x].

Tipo: matriz de duplas

Para obter mais informações sobre objetos de Error, consulte as seções a seguir.

Formatos de resposta de erro

Opcionalmente, você pode usar a resposta de erro para fornecer mais informações sobre erros. Recomendamos que você retorne um erro com validação de código quando ocorrer um erro de validação, como quando um parâmetro está ausente ou é do tipo errado.

Veja a seguir um exemplo da resposta quando a função do Lambda deseja gerar uma exceção de validação GetMetricData.


{
   "Error": {
      "Code": "Validation",
      "Value": "Invalid Prometheus cluster"
   }
}

Veja a seguir um exemplo da resposta quando a função do Lambda indica que não consegue retornar dados devido a um problema de acesso. A resposta é convertida em uma única série temporal com um código de status de Forbidden.


{
   "Error": {
      "Code": "Forbidden",
      "Value": "Unable to access ..."
   }
}

Veja a seguir um exemplo de quando a função do Lambda gera uma exceção geral InternalError, que é convertida em uma única série temporal com um código de status de InternalError e uma mensagem. Sempre que um código de erro tem um valor diferente de Validation ou Forbidden, o CloudWatch pressupõe que trata-se de um erro interno genérico.


{
   "Error": {
      "Code": "PrometheusClusterUnreachable",
      "Value": "Unable to communicate with the cluster"
   }
}

DescribeGetMetricData event

Carga da solicitação

Veja a seguir um exemplo de carga da solicitação DescribeGetMetricData.


{
  "EventType": "DescribeGetMetricData"
}

Carga da resposta

Veja a seguir um exemplo de carga da resposta DescribeGetMetricData.


{
    "Description": "Data source connector",
    "ArgumentDefaults": [{
        Value: "default value"
     }]
}

Descrição: uma descrição de como usar o conector da fonte de dados. Essa descrição será exibida no console do CloudWatch. O Markdown é compatível.

Tipo: sequência
ArgumentDefaults: a matriz opcional de valores padrão de argumentos usada preenche previamente o construtor da fonte de dados personalizada.

Se [{ Value: "default value 1"}, { Value: 10}] for retornado, o construtor de consultas no console do CloudWatch exibirá duas entradas: a primeira com “valor padrão 1” e a segunda com 10.

Se ArgumentDefaults não for fornecida, uma única entrada será exibida com o padrão de tipo definido como String.

Tipo: matriz de objetos contendo Valor e Tipo.
Erro: (opcional) um campo de erro pode ser incluído em qualquer resposta. Você pode ver exemplos em Evento GetMetricData.

Considerações importantes para alarmes do CloudWatch

Se você usar a fonte de dados para definir alarmes do CloudWatch, deverá configurá-la para relatar dados com carimbos e data/hora a cada minuto para o CloudWatch. Para obter mais informações e outras considerações sobre a criação de alarmes com base em métricas de fontes de dados conectadas, consulte Criação de um alarme com base em uma fonte de dados conectada.

(Opcional) Usar o AWS Secrets Manager para armazenar credenciais

Se a função do Lambda precisar usar credenciais para acessar a fonte de dados, recomendamos usar o AWS Secrets Manager para armazenar essas credenciais em vez de codificá-las na função do Lambda. Para obter mais informações sobre como usar o AWS Secrets Manager com o Lambda, consulte Usar segredos do AWS Secrets Manager em funções do AWS Lambda.

(Opcional) Conecte-se a uma fonte de dados em uma VPC

Se sua fonte de dados estiver em uma VPC gerenciada pela Amazon Virtual Private Cloud, você deverá configurar sua função do Lambda para acessá-la. Para obter mais informações, consulte Como conectar as redes de saída aos recursos em uma VPC.

Talvez você também precise configurar endpoints de serviço da VPC para acessar serviços, como o AWS Secrets Manager. Para obter mais informações, consulte Acessar um serviço da AWS usando um endpoint da VPC de interface.

Etapa 2: criar uma política de permissões do Lambda

Você deve criar uma declaração de política que conceda permissão ao CloudWatch para usar a função do Lambda que você criou. Você pode usar a AWS CLI ou o console do Lambda para criar a declaração de política.

Como usar a AWS CLI para criar a declaração de política

Insira o comando a seguir. Substitua 123456789012 pelo ID da sua conta, substitua my-data-source-function pelo nome da função do Lambda e substitua MyDataSource-DataSourcePermission1234 por um valor exclusivo arbitrário.


aws lambda add-permission --function-name my-data-source-function --statement-id MyDataSource-DataSourcePermission1234 --action lambda:InvokeFunction --principal lambda.datasource.cloudwatch.amazonaws.com --source-account 123456789012

Etapa 3: anexar uma tag de recurso à função do Lambda

O console do CloudWatch determina quais das funções do Lambda são conectores de fontes de dados usando uma tag. Quando você cria uma fonte de dados usando um dos assistentes, a tag é aplicada automaticamente pela pilha do AWS CloudFormation que a configura. Ao criar uma fonte de dados por conta própria, você pode usar a tag a seguir para a função do Lambda. Isso faz com que o conector seja exibido na lista suspensa Fonte de dados no console do CloudWatch quando você consulta métricas.

Uma tag com cloudwatch:datasource como chave e custom como valor.

Atenção O Javascript está desativado ou não está disponível no seu navegador.

Para usar a documentação da AWS, o Javascript deve estar ativado. Consulte as páginas de Ajuda do navegador para obter instruções.

Convenções do documento

Conectar-se a uma fonte de dados pré-criada com um assistente

Usar sua fonte de dados personalizada