Conector de métricas do Amazon CloudWatch - AWS IoT Greengrass
RequisitosParâmetrosDados de entradaDados de saídaExemplo de usoLicençasChangelogConsulte também

O AWS IoT Greengrass Version 1 entrou na fase de vida útil prolongada em 30 de junho de 2023. Para obter mais informações, consulte política de manutenção do AWS IoT Greengrass V1. Após essa data, o AWS IoT Greengrass V1 não lançará atualizações que forneçam recursos, aprimoramentos, correções de erros ou patches de segurança. Os dispositivos que funcionam com o AWS IoT Greengrass V1 não serão interrompidos e continuarão operando e se conectando à nuvem. É altamente recomendável que você migre para AWS IoT Greengrass Version 2, o que adicionará novos recursos significativos e suporte para plataformas adicionais.

Conector de métricas do Amazon CloudWatch

O conector de métricas do CloudWatch Metrics publica métricas personalizadas dos dispositivos Greengrass no Amazon CloudWatch. O conector fornece uma infraestrutura centralizada para a publicação de métricas do CloudWatch, que você pode usar para monitorar e analisar o ambiente de núcleo do Greengrass e atuar em eventos locais. Para obter mais informações, consulte Usando as métricas do Amazon CloudWatch no Guia do usuário do Amazon CloudWatch.

Esse conector recebe dados de métrica como mensagens MQTT. O conector agrupa as métricas em lotes do mesmo namespace e as publica no CloudWatch em intervalos regulares.

Esse conector tem as seguintes versões.

Version (Versão)

ARN

5

arn:aws:greengrass:region::/connectors/CloudWatchMetrics/versions/5

4

arn:aws:greengrass:region::/connectors/CloudWatchMetrics/versions/4

3

arn:aws:greengrass:region::/connectors/CloudWatchMetrics/versions/3

2

arn:aws:greengrass:region::/connectors/CloudWatchMetrics/versions/2

1

arn:aws:greengrass:region::/connectors/CloudWatchMetrics/versions/1

Para obter informações sobre alterações de versão, consulte o Changelog.

Requisitos

Esse conector tem os seguintes requisitos:

Version 3 - 5

  • Software de núcleo do AWS IoT Greengrass v1.9.3 ou versão posterior.

  • Python, versão 3.7 ou 3.8, instalado no dispositivo de núcleo e adicionado à variável de ambiente PATH.

    nota

    Para usar o Python 3.8, execute o comando a seguir para criar um symblink da pasta de instalação padrão do Python 3.7 para os binários instalados do Python 3.8.

    sudo ln -s path-to-python-3.8/python3.8 /usr/bin/python3.7

    Isso configura seu dispositivo para atender ao requisito Python para AWS IoT Greengrass.

  • A função de grupo do Greengrass configurada para permitir a ação cloudwatch:PutMetricData, conforme mostrado no seguinte exemplo de política do AWS Identity and Access Management (IAM).

    {
    "Version": "2012-10-17",
    "Statement": [
        {
            "Sid": "Stmt1528133056761",
            "Action": [
                "cloudwatch:PutMetricData"
            ],
            "Effect": "Allow",
            "Resource": "*"
        }
    ]
}

    Para o requisito de função de grupo, você deve configurar a função para conceder as permissões necessárias e certificar-se de que a função tenha sido adicionada ao grupo. Para obter mais informações, consulte Gerenciar a função de grupo do Greengrass (console) ou Gerenciar a função de grupo do Greengrass (CLI).

    Para obter mais informações sobre as permissões do CloudWatch, consulte a Referência de permissões do Amazon CloudWatch no Guia do usuário do IAM.

Versions 1 - 2

  • Software AWS IoT Greengrass Core v1.7 ou posterior.

  • Python versão 2.7 instalado no dispositivo de núcleo e adicionado à variável de ambiente PATH.

  • A função de grupo do Greengrass configurada para permitir a ação cloudwatch:PutMetricData, conforme mostrado no seguinte exemplo de política do AWS Identity and Access Management (IAM).

    {
    "Version": "2012-10-17",
    "Statement": [
        {
            "Sid": "Stmt1528133056761",
            "Action": [
                "cloudwatch:PutMetricData"
            ],
            "Effect": "Allow",
            "Resource": "*"
        }
    ]
}

    Para o requisito de função de grupo, você deve configurar a função para conceder as permissões necessárias e certificar-se de que a função tenha sido adicionada ao grupo. Para obter mais informações, consulte Gerenciar a função de grupo do Greengrass (console) ou Gerenciar a função de grupo do Greengrass (CLI).

    Para obter mais informações sobre as permissões do CloudWatch, consulte a Referência de permissões do Amazon CloudWatch no Guia do usuário do IAM.

Parâmetros do conector

Esse conector oferece os seguintes parâmetros:

Versions 4 - 5
PublishInterval

O número máximo de segundos de espera antes de publicar métricas em lote para um determinado namespace. O valor máximo é 900. Para configurar o conector a fim de publicar métricas conforme são recebidas (sem agrupamento em lotes), especifique 0.

O conector publica no CloudWatch depois de receber 20 métricas no mesmo namespace ou depois do intervalo especificado.

nota

O conector não garante a ordem de publicação de eventos.

Nome de exibição no console do AWS IoT: Intervalo de publicação

Obrigatório: true

Digite: string

Valores válidos: 0 - 900

Padrão válido: [0-9]|[1-9]\d|[1-9]\d\d|900

PublishRegion

O Região da AWS no qual publicar métricas do CloudWatch. Esse valor substitui a região padrão de métricas do Greengrass. É necessário apenas ao publicar métricas entre regiões.

Nome de exibição no console AWS IoT: região de publicação

Obrigatório: false

Digite: string

Padrão válido: ^$|([a-z]{2}-[a-z]+-\d{1})

MemorySize

A memória (em KB) de alocação no conector.

Nome de exibição no console do AWS IoT: Tamanho da memória

Obrigatório: true

Digite: string

Padrão válido: ^[0-9]+$

MaxMetricsToRetain

O número máximo de métricas em todos os namespaces para salvar na memória antes que sejam substituídas por novas métricas. O valor mínimo é 2000.

Esse limite aplica-se quando não há conexão com a Internet, e o conector começa a armazenar as métricas em buffer para publicar posteriormente. Quando o buffer está cheio, as métricas mais antigas são substituídas por novas métricas. As métricas em um determinado namespace são substituídas apenas por métricas no mesmo namespace.

nota

As métricas não são salvas se o processo de host do conector é interrompido. Por exemplo, essa interrupção pode ocorrer durante a implantação do grupo ou quando o dispositivo é reiniciado.

Nome de exibição no console AWS IoT: Maximum metrics to retain (Métricas máximas a serem retidas)

Obrigatório: true

Digite: string

Padrão válido: ^([2-9]\d{3}|[1-9]\d{4,})$

IsolationMode

O modo de conteinerização para este conector. O padrão é GreengrassContainer, o que significa que o conector é executado em um ambiente de runtime isolado dentro do contêiner do AWS IoT Greengrass.

nota

A configuração padrão de conteinerização para o grupo não se aplica aos conectores.

Nome de exibição no console do AWS IoT: Modo de isolamento de contêiner

Obrigatório: false

Digite: string

Valores válidos: GreengrassContainer ou NoContainer

Padrão válido: ^NoContainer$|^GreengrassContainer$

Versions 1 - 3
PublishInterval

O número máximo de segundos de espera antes de publicar métricas em lote para um determinado namespace. O valor máximo é 900. Para configurar o conector a fim de publicar métricas conforme são recebidas (sem agrupamento em lotes), especifique 0.

O conector publica no CloudWatch depois de receber 20 métricas no mesmo namespace ou depois do intervalo especificado.

nota

O conector não garante a ordem de publicação de eventos.

Nome de exibição no console do AWS IoT: Intervalo de publicação

Obrigatório: true

Digite: string

Valores válidos: 0 - 900

Padrão válido: [0-9]|[1-9]\d|[1-9]\d\d|900

PublishRegion

O Região da AWS no qual publicar métricas do CloudWatch. Esse valor substitui a região padrão de métricas do Greengrass. É necessário apenas ao publicar métricas entre regiões.

Nome de exibição no console AWS IoT: região de publicação

Obrigatório: false

Digite: string

Padrão válido: ^$|([a-z]{2}-[a-z]+-\d{1})

MemorySize

A memória (em KB) de alocação no conector.

Nome de exibição no console do AWS IoT: Tamanho da memória

Obrigatório: true

Digite: string

Padrão válido: ^[0-9]+$

MaxMetricsToRetain

O número máximo de métricas em todos os namespaces para salvar na memória antes que sejam substituídas por novas métricas. O valor mínimo é 2000.

Esse limite aplica-se quando não há conexão com a Internet, e o conector começa a armazenar as métricas em buffer para publicar posteriormente. Quando o buffer está cheio, as métricas mais antigas são substituídas por novas métricas. As métricas em um determinado namespace são substituídas apenas por métricas no mesmo namespace.

nota

As métricas não são salvas se o processo de host do conector é interrompido. Por exemplo, essa interrupção pode ocorrer durante a implantação do grupo ou quando o dispositivo é reiniciado.

Nome de exibição no console AWS IoT: Maximum metrics to retain (Métricas máximas a serem retidas)

Obrigatório: true

Digite: string

Padrão válido: ^([2-9]\d{3}|[1-9]\d{4,})$

Exemplo de criação de conector (AWS CLI)

O seguinte comando da CLI cria um ConnectorDefinition com uma versão inicial que contém o conector de métricas do CloudWatch.

aws greengrass create-connector-definition --name MyGreengrassConnectors --initial-version '{
    "Connectors": [
        {
            "Id": "MyCloudWatchMetricsConnector",
            "ConnectorArn": "arn:aws:greengrass:region::/connectors/CloudWatchMetrics/versions/4",
            "Parameters": {
                "PublishInterval" : "600",
                "PublishRegion" : "us-west-2",
                "MemorySize" : "16",
                "MaxMetricsToRetain" : "2500",
                "IsolationMode" : "GreengrassContainer"
            }
        }
    ]
}'

No console do AWS IoT Greengrass, você pode adicionar um conector na página Conectores do grupo. Para obter mais informações, consulte Conceitos básicos de conectores do Greengrass (console).

Dados de entrada

Esse conector aceita métricas em um tópico MQTT e as publica no CloudWatch. As mensagens de entrada devem estar no formato JSON.

Filtro de tópico na assinatura

cloudwatch/metric/put

Propriedades de mensagens
request

Informações sobre a métrica nesta mensagem.

O objeto de solicitação contém os dados de métrica para publicação no CloudWatch. Os valores de métrica devem atender às especificações de API PutMetricData. Apenas o namespace, metricData.metricName e as propriedades metricData.value são necessários.

Obrigatório: true

Tipo: object que inclui as seguintes propriedades:

namespace

O namespace definido pelo usuário para os dados métricos nessa solicitação. O CloudWatch usa namespaces como contêineres para pontos de dados métricos.

nota

Você não pode especificar um namespace que comece com a string reservada AWS/.

Obrigatório: true

Digite: string

Padrão válido: [^:].*

metricData

Os dados para a métrica.

Obrigatório: true

Tipo: object que inclui as seguintes propriedades:

metricName

O nome da métrica.

Obrigatório: true

Digite: string

dimensions

As dimensões associadas com a métrica. As dimensões fornecem mais informações sobre a métrica e seus dados. Uma métrica pode definir até 10 dimensões.

Esse conector inclui, automaticamente, uma dimensão chamada coreName, em que o valor é o nome do núcleo.

Obrigatório: false

Tipo: array de objetos de dimensão que incluem as seguintes propriedades:

name

O nome da dimensão.

Obrigatório: false

Digite: string

value

O valor da dimensão.

Obrigatório: false

Digite: string

timestamp

O horário em que os dados da métrica foram recebidos, expresso em segundos desde Jan 1, 1970 00:00:00 UTC. Se esse valor for omitido, o conector usará o horário em que ele recebeu a mensagem.

Obrigatório: false

Digite: timestamp

nota

Se você usar entre as versões 1 e 4 desse conector, recomendamos que você recupere o timestamp separadamente para cada métrica ao enviar várias métricas de uma única fonte. Não use uma variável para armazenar o timestamp.

value

O valor para a métrica.

nota

O CloudWatch rejeitará valores muito pequenos ou muito grandes. Os valores devem estar no intervalo de 8.515920e-109 a 1.174271e+108 (Base 10) ou 2e-360 a 2e360 (Base 2). Os valores especiais (por exemplo, NaN, +Infinity, -Infinity) não são compatíveis.

Obrigatório: true

Digite: double

unit

A unidade da métrica.

Obrigatório: false

Digite: string

Valores válidos: 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

Limites

Todos os limites impostos pela API PutMetricData do CloudWatch aplicam-se às métricas ao usar esse conector. É especialmente importante observar os limites a seguir:

  • Limite de 40 KB na carga da API

  • 20 métricas por solicitação de API

  • 150 transações por segundo (TPS) para a API PutMetricData

Para obter mais informações, consulte Limites do CloudWatch no Guia do usuário do Amazon CloudWatch.

Exemplo de entrada
{
   "request": {
       "namespace": "Greengrass",
       "metricData":
           {
               "metricName": "latency",
               "dimensions": [
                   {
                       "name": "hostname",
                       "value": "test_hostname"
                   }
               ],
               "timestamp": 1539027324,
               "value": 123.0,
               "unit": "Seconds"
            }
    }
}

Dados de saída

O conector publica informações de status como dados de saída em um tópico MQTT.

Filtro de tópico na assinatura

cloudwatch/metric/put/status

Exemplo de resultado: sucesso

A resposta inclui o namespace dos dados de métrica e o campo RequestId da resposta do CloudWatch.

{
   "response": {
        "cloudwatch_rid":"70573243-d723-11e8-b095-75ff2EXAMPLE",
        "namespace": "Greengrass",
        "status":"success"
    }
}
Exemplo de resultado: falha
{
   "response" : {
        "namespace": "Greengrass",
        "error": "InvalidInputException",
        "error_message":"cw metric is invalid",
        "status":"fail"
   }
}
nota

Se o conector detectar um erro que pode ser repetido (por exemplo, erros de conexão), ele tentará publicar novamente no próximo lote.

Exemplo de uso

Use as seguintes etapas de alto nível para configurar um exemplo de função do Lambda Python 3.7 que pode ser usado para testar o conector.

nota

  1. Certifique-se de cumprir os requisitos para o conector.

    Para o requisito de função de grupo, você deve configurar a função para conceder as permissões necessárias e certificar-se de que a função tenha sido adicionada ao grupo. Para obter mais informações, consulte Gerenciar a função de grupo do Greengrass (console) ou Gerenciar a função de grupo do Greengrass (CLI).

  2. Crie e publique uma função do Lambda que envie dados de entrada para o conector.

    Salve o código de exemplo como arquivo PY. Baixe e descompacte o SDK do AWS IoT Greengrass Core para Python. Crie então um pacote zip que contenha o arquivo PY e a pasta greengrasssdk no nível raiz. Este pacote zip é o pacote de implantação que você transfere por upload para o AWS Lambda.

    Depois de criar a função do Lambda Python 3.7, publique uma versão de função e crie um alias.

  3. Configure o grupo do Greengrass.

    1. Adicione a função do Lambda pelo seu alias (recomendado). Configure o ciclo de vida do Lambda como de longa duração (ou "Pinned": true na CLI).

    2. Adicione o conector e configure seus parâmetros.

    3. Adicione assinaturas que permitam que o conector receba dados de entrada e envie dados de saída em filtros de tópico compatíveis.

      • Defina a função do Lambda como origem, o conector como destino e use um filtro de tópico de entrada compatível.

      • Defina o conector como origem, o AWS IoT Core como destino, e use um filtro de tópico de saída compatível. Use essa assinatura para exibir mensagens de status no console do AWS IoT.

  4. Implante o grupo.

  5. No console do AWS IoT, na página Teste, assine o tópico de dados de saída para exibir mensagens de status do conector. A função de exemplo do Lambda é de longa duração e começa a enviar mensagens imediatamente após o grupo ser implantado.

    Ao finalizar o teste, você pode definir o ciclo de vida do Lambda como sob demanda (ou "Pinned": false na CLI) e implantar o grupo. Isso impede o envio de mensagens pela função.

Exemplo

O exemplo a seguir da função do Lambda envia uma mensagem de entrada para o conector.

import greengrasssdk
import time
import json

iot_client = greengrasssdk.client('iot-data')
send_topic = 'cloudwatch/metric/put'

def create_request_with_all_fields():
    return  {
        "request": {
            "namespace": "Greengrass_CW_Connector",
            "metricData": {
                "metricName": "Count1",
                "dimensions": [
                    {
                        "name": "test",
                        "value": "test"
                    }
                ],
                "value": 1,
                "unit": "Seconds",
                "timestamp": time.time()
            }
        }
    }

def publish_basic_message():
    messageToPublish = create_request_with_all_fields()
    print("Message To Publish: ", messageToPublish)
    iot_client.publish(topic=send_topic,
        payload=json.dumps(messageToPublish))

publish_basic_message()

def lambda_handler(event, context):
    return

Licenças

O conector do CloudWatch inclui o seguinte licenciamento/software de terceiros:

Esse conector é liberado de acordo com o Contrato de licença de software do Greengrass Core.

Changelog

A tabela a seguir descreve as alterações em cada versão do conector.

Version (Versão)

Alterações

5

Correção para adicionar suporte para timestamps duplicados nos dados de entrada.

4

Adicionado o parâmetro IsolationMode para configurar o modo de conteinerização para o conector.

3

Atualização do runtime do Lambda para Python 3.7, o que altera o requisito de runtime.

2

Corrija para reduzir o registro excessivo.

1

Versão inicial.

Um grupo do Greengrass só pode conter uma versão do conector por vez. Para obter informações sobre como fazer upgrade de uma versão do conector, consulte Atualizar a versões do conector.

Consulte também