CloudWatch 메트릭 커넥터 - AWS IoT Greengrass
요구 사항파라미터입력 데이터출력 데이터사용 예라이선스Changelog다음 사항도 참조하십시오.

AWS IoT Greengrass Version 1 2023년 6월 30일에 수명 연장 단계에 들어갔습니다. AWS IoT Greengrass V1 관리형 정책에 대한 자세한 정보는 섹션을 참조하세요. 이 날짜 이후에는 기능, 개선 사항, 버그 수정 또는 보안 패치를 제공하는 업데이트가 AWS IoT Greengrass V1 릴리스되지 않습니다. 에서 실행되는 기기는 AWS IoT Greengrass V1 중단되지 않으며 계속 작동하고 클라우드에 연결됩니다. 새로운 기능이 크게 추가되고 추가 플랫폼에 대한 지원이 추가되는 으로 마이그레이션하는 AWS IoT Greengrass Version 2 것이 좋습니다.

기계 번역으로 제공되는 번역입니다. 제공된 번역과 원본 영어의 내용이 상충하는 경우에는 영어 버전이 우선합니다.

CloudWatch 메트릭 커넥터

CloudWatch 지표 커넥터는 Greengrass 디바이스의 사용자 지정 지표를 Amazon에 게시합니다. CloudWatch 커넥터는 CloudWatch 지표 게시를 위한 중앙 집중식 인프라를 제공하며, 이를 사용하여 Greengrass 핵심 환경을 모니터링 및 분석하고 로컬 이벤트에 대한 조치를 취할 수 있습니다. 자세한 내용은 Amazon 사용 CloudWatch 설명서의 Amazon CloudWatch 측정치 사용을 참조하십시오.

이 커넥터는 지표 데이터를 MQTT 메시지로 수신합니다. 커넥터는 동일한 네임스페이스에 있는 메트릭을 일괄 처리하여 CloudWatch 정기적으로 게시합니다.

이 커넥터의 버전은 다음과 같습니다.

버전

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

버전 변경 사항에 대한 자세한 내용은 Changelog를 참조하십시오.

요구 사항

이 커넥터에는 다음과 같은 요구 사항이 있습니다.

Version 3 - 5

  • AWS IoT Greengrass 코어 소프트웨어 v1.9.3 이상.

  • 코어 디바이스에 설치되고 PATH 환경 변수에 추가된 Python 버전 3.7 또는 3.8입니다.

    참고

    Python 3.8을 사용하려면 다음 명령을 실행하여 기본 Python 3.7 설치 폴더에서 설치된 Python 3.8 바이너리로 연결되는 심볼릭 링크를 만드십시오.

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

    이렇게 하면 AWS IoT Greengrass에 대한 Python 요구 사항을 충족하도록 디바이스가 구성됩니다.

  • 다음 예제에 표시된 것처럼 cloudwatch:PutMetricData 작업을 허용하는 Greengrass 그룹 역할에 추가된 AWS Identity and Access Management (IAM) 정책.

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

    그룹 역할 요구 사항의 경우, 필수 권한을 부여하도록 역할을 구성하고 역할이 그룹에 추가되었는지 확인해야 합니다. 자세한 내용은 Greengrass 그룹 역할 관리(콘솔) 또는 Greengrass 그룹 역할 관리(CLI) 섹션을 참조하세요.

    CloudWatch 권한에 대한 자세한 내용은 IAM 사용 설명서의 Amazon CloudWatch 권한 참조를 참조하십시오.

Versions 1 - 2

  • AWS IoT Greengrass 코어 소프트웨어 v1.7 이상.

  • 코어 디바이스에 설치되고 PATH 환경 변수에 추가된 Python 버전 3.7입니다.

  • 다음 예제에 표시된 것처럼 cloudwatch:PutMetricData 작업을 허용하는 Greengrass 그룹 역할에 추가된 AWS Identity and Access Management (IAM) 정책.

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

    그룹 역할 요구 사항의 경우, 필수 권한을 부여하도록 역할을 구성하고 역할이 그룹에 추가되었는지 확인해야 합니다. 자세한 내용은 Greengrass 그룹 역할 관리(콘솔) 또는 Greengrass 그룹 역할 관리(CLI) 섹션을 참조하세요.

    CloudWatch 권한에 대한 자세한 내용은 IAM 사용 설명서의 Amazon CloudWatch 권한 참조를 참조하십시오.

커넥터 파라미터

이 커넥터는 다음 파라미터를 제공합니다.

Versions 4 - 5
PublishInterval

지정된 네임스페이스에 대해 일괄 처리된 지표를 게시하기 전에 대기해야 하는 최대 시간(초). 최대값은 900입니다. 지표가 (배치 처리 없이) 수신될 때 지표를 게시하도록 커넥터를 구성하려면 0을 지정합니다.

커넥터는 동일한 네임스페이스에서 20개의 지표를 수신한 CloudWatch 후 또는 지정된 간격 후에 게시합니다.

참고

이 커넥터는 게시 이벤트의 순서를 보장하지 않습니다.

AWS IoT 콘솔의 표시 이름: 게시 간격

필수: true

유형: string

유효값: 0 - 900

유효한 패턴: [0-9]|[1-9]\d|[1-9]\d\d|900

PublishRegion

AWS 리전메트릭을 게시할 대상 CloudWatch 이 값은 기본 Greengrass 지표 리전을 재정의합니다. 교차 리전 지표를 게시하는 경우에만 필요합니다.

AWS IoT 콘솔의 표시 이름: 게시 리전

필수: false

유형: string

유효한 패턴: ^$|([a-z]{2}-[a-z]+-\d{1})

MemorySize

커넥터에 할당할 메모리(KB).

AWS IoT 콘솔의 표시 이름: 메모리 크기

필수: true

유형: string

유효한 패턴: ^[0-9]+$

MaxMetricsToRetain

새 지표로 바뀌기 전에 메모리에 저장할 모든 네임스페이스 간 최대 지표 수. 최소값은 2000입니다.

이러한 제한은 인터넷에 연결되어 있지 않거나 커넥터가 나중에 게시할 지표를 버퍼링하기 시작할 때 적용됩니다. 버퍼가 꽉 차면 가장 오래된 지표가 새 지표로 바뀝니다. 지정된 네임스페이스의 지표는 동일한 네임스페이스의 지표로만 바뀝니다.

참고

커넥터에 대한 호스트 프로세스가 중단되면 지표가 저장되지 않습니다. 예를 들어, 그룹 배포 중 또는 디바이스가 다시 시작될 때 중단이 발생할 수 있습니다.

AWS IoT 콘솔의 표시 이름: 보존할 최대 지표

필수: true

유형: string

유효한 패턴: ^([2-9]\d{3}|[1-9]\d{4,})$

IsolationMode

이 커넥터의 컨테이너화 모드입니다. 기본값은 GreengrassContainer이며 이는 커넥터가 AWS IoT Greengrass 컨테이너 내부의 격리된 런타임 환경에서 실행됨을 의미합니다.

참고

그룹의 기본 컨테이너화 설정은 커넥터에는 적용되지 않습니다.

AWS IoT 콘솔의 표시 이름: 컨테이너 격리 모드

필수: false

유형: string

유효한 값: GreengrassContainer또는 NoContainer

유효한 패턴: ^NoContainer$|^GreengrassContainer$

Versions 1 - 3
PublishInterval

지정된 네임스페이스에 대해 일괄 처리된 지표를 게시하기 전에 대기해야 하는 최대 시간(초). 최대값은 900입니다. 지표가 (배치 처리 없이) 수신될 때 지표를 게시하도록 커넥터를 구성하려면 0을 지정합니다.

커넥터는 동일한 네임스페이스에서 20개의 메트릭을 수신한 후 또는 지정된 간격 후에 게시합니다. CloudWatch

참고

이 커넥터는 게시 이벤트의 순서를 보장하지 않습니다.

AWS IoT 콘솔의 표시 이름: 게시 간격

필수: true

유형: string

유효값: 0 - 900

유효한 패턴: [0-9]|[1-9]\d|[1-9]\d\d|900

PublishRegion

AWS 리전메트릭을 게시할 대상 CloudWatch 이 값은 기본 Greengrass 지표 리전을 재정의합니다. 교차 리전 지표를 게시하는 경우에만 필요합니다.

AWS IoT 콘솔의 표시 이름: 게시 리전

필수: false

유형: string

유효한 패턴: ^$|([a-z]{2}-[a-z]+-\d{1})

MemorySize

커넥터에 할당할 메모리(KB).

AWS IoT 콘솔의 표시 이름: 메모리 크기

필수: true

유형: string

유효한 패턴: ^[0-9]+$

MaxMetricsToRetain

새 지표로 바뀌기 전에 메모리에 저장할 모든 네임스페이스 간 최대 지표 수. 최소값은 2000입니다.

이러한 제한은 인터넷에 연결되어 있지 않거나 커넥터가 나중에 게시할 지표를 버퍼링하기 시작할 때 적용됩니다. 버퍼가 꽉 차면 가장 오래된 지표가 새 지표로 바뀝니다. 지정된 네임스페이스의 지표는 동일한 네임스페이스의 지표로만 바뀝니다.

참고

커넥터에 대한 호스트 프로세스가 중단되면 지표가 저장되지 않습니다. 예를 들어, 그룹 배포 중 또는 디바이스가 다시 시작될 때 중단이 발생할 수 있습니다.

AWS IoT 콘솔의 표시 이름: 보존할 최대 지표

필수: true

유형: string

유효한 패턴: ^([2-9]\d{3}|[1-9]\d{4,})$

커넥터 만들기 예(AWS CLI)

다음 CLI 명령은 CloudWatch Metrics 커넥터가 ConnectorDefinition 포함된 초기 버전을 사용하여 를 생성합니다.

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"
            }
        }
    ]
}'

AWS IoT Greengrass 콘솔에서는 그룹의 커넥터 페이지에서 커넥터를 추가할 수 있습니다. 자세한 설명은 Greengrass 커넥터 시작하기(콘솔) 섹션을 참조하세요.

입력 데이터

이 커넥터는 MQTT 주제에 대한 메트릭을 수락하고 메트릭을 게시합니다. CloudWatch 입력 메시지는 JSON 형식이어야 합니다.

구독의 주제 필터

cloudwatch/metric/put

메시지 속성
request

이 메시지에는 지표에 대한 정보가 포함되어 있습니다.

요청 객체에는 CloudWatch에 게시할 지표 데이터가 포함되어 있습니다. 지표 값은 PutMetricData API의 사양을 충족해야 합니다. namespace, metricData.metricName 및 metricData.value 속성만 필요합니다.

필수: true

유형: 다음 속성을 포함하는 object:

namespace

이 요청의 메트릭 데이터에 대한 사용자 정의 네임스페이스입니다. CloudWatch 네임스페이스를 지표 데이터 포인트의 컨테이너로 사용합니다.

참고

예약 문자어 AWS/로 시작하는 네임스페이스는 지정할 수 없습니다.

필수: true

유형: string

유효한 패턴: [^:].*

metricData

지표에 대한 데이터.

필수: true

유형: 다음 속성을 포함하는 object:

metricName

지표의 이름.

필수: true

유형: string

dimensions

지표와 연결된 차원. 차원은 지표와 해당 데이터에 대한 추가 정보를 제공합니다. 지표는 최대 10개 차원을 정의할 수 있습니다.

이 커넥터에는 이름이 coreName인 차원이 자동으로 포함되며, 여기서 값은 코어의 이름입니다.

필수: false

유형: 다음 속성을 포함하는 차원 객체의 array

name

차원 이름입니다.

필수: false

유형: string

value

차원 값입니다.

필수: false

유형: string

timestamp

지표 데이터가 수신된 시간, Jan 1, 1970 00:00:00 UTC 이후 밀리초로 표시됩니다. 이 값을 생략하면 커넥터는 메시지를 수신한 시간을 사용합니다.

필수: false

유형: timestamp

참고

이 커넥터의 버전 1~4를 사용하는 경우 단일 소스에서 여러 지표를 전송할 때 각 지표에 대한 타임스탬프를 개별적으로 검색하는 것이 좋습니다. 변수를 사용하여 타임스탬프를 저장하지 마세요.

value

지표에 대한 값.

참고

CloudWatch 너무 작거나 너무 큰 값은 거부합니다. 값의 범위는 8.515920e-109 ~ 1.174271e+108(기본 10) 또는 2e-360 ~ 2e360(기본 2)이어야 합니다. 특수 값(예: NaN, +Infinity, -Infinity)은 지원되지 않습니다.

필수: true

유형: double

unit

측정치의 단위입니다.

필수: false

유형: string

유효값: 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

Limits

CloudWatch PutMetricDataAPI에서 부과하는 모든 제한은 이 커넥터를 사용할 때 지표에 적용됩니다. 다음은 중요한 제한 사항입니다.

  • API 페이로드에 대한 40KB 제한

  • API 요청당 20개 지표

  • PutMetricData API에 대한 150개의 초당 트랜잭션(TPS)

자세한 내용은 Amazon CloudWatch 사용 설명서의 CloudWatch 한도를 참조하십시오.

입력 예
{
   "request": {
       "namespace": "Greengrass",
       "metricData":
           {
               "metricName": "latency",
               "dimensions": [
                   {
                       "name": "hostname",
                       "value": "test_hostname"
                   }
               ],
               "timestamp": 1539027324,
               "value": 123.0,
               "unit": "Seconds"
            }
    }
}

출력 데이터

이 커넥터는 상태 정보를 MQTT 주제에 출력 데이터로 게시합니다.

구독의 주제 필터

cloudwatch/metric/put/status

출력 예: 성공

응답에는 메트릭 데이터의 네임스페이스와 응답의 RequestId 필드가 포함됩니다. CloudWatch 

{
   "response": {
        "cloudwatch_rid":"70573243-d723-11e8-b095-75ff2EXAMPLE",
        "namespace": "Greengrass",
        "status":"success"
    }
}
출력 예: 실패
{
   "response" : {
        "namespace": "Greengrass",
        "error": "InvalidInputException",
        "error_message":"cw metric is invalid",
        "status":"fail"
   }
}
참고

커넥터가 재시도 가능한 오류(예: 연결 오류)를 감지하면 다음 배치에서 게시를 재시도합니다.

사용 예

다음 상위 수준 단계를 사용하여 커넥터를 사용해 보는 데 이용할 수 있는 예제 Python 3.7 Lambda 함수를 설정합니다.

참고

  • 다른 Python 런타임을 사용하는 경우 Python3.x에서 Python 3.7로의 심볼릭 링크를 만들 수 있습니다.

  • 커넥터 시작하기(콘솔) 및 커넥터 시작하기(CLI) 주제에는 예제 Twilio 알림 커넥터를 구성하고 배포하는 방법을 보여주는 자세한 단계가 포함되어 있습니다.

  1. 커넥터에 대한 요구 사항을 충족하는지 확인합니다.

    그룹 역할 요구 사항의 경우, 필수 권한을 부여하도록 역할을 구성하고 역할이 그룹에 추가되었는지 확인해야 합니다. 자세한 내용은 Greengrass 그룹 역할 관리(콘솔) 또는 Greengrass 그룹 역할 관리(CLI) 섹션을 참조하세요.

  2. 입력 데이터를 커넥터로 보내는 Lambda 함수를 생성하고 게시합니다.

    예제 코드를 PY 파일로 저장합니다. Python용 AWS IoT Greengrass 코어 SDK를 다운로드하고 압축을 풉니다. 그런 다음 루트 수준에서 PY 파일과 greengrasssdk 폴더를 포함하는 zip 패키지를 생성합니다. 이 zip 패키지는 AWS Lambda에 업로드하는 배포 패키지입니다.

    Python 3.7 Lambda 함수를 생성한 후 함수 버전을 게시하고 별칭을 만듭니다.

  3. Greengrass 그룹을 구성합니다.

    1. 별칭으로 Lambda 함수를 추가합니다(권장). Lambda 수명 주기를 수명이 긴 함수(또는 CLI의 "Pinned": true)로 구성합니다.

    2. 커넥터를 추가하고 해당 파라미터를 구성합니다.

    3. 커넥터가 입력 데이터를 수신하고 지원되는 주제 필터에서 출력 데이터를 전송할 수 있도록 허용하는 구독을 추가합니다.

      • Lambda 함수를 소스로, 커넥터를 대상으로 설정하고 지원되는 입력 주제 필터를 사용합니다.

      • 커넥터를 소스로, AWS IoT Core를 대상으로 설정하고 지원되는 출력 주제 필터를 사용합니다. 이 구독을 사용하여 AWS IoT에서 상태 메시지를 확인합니다.

  4. 그룹을 배포합니다.

  5. AWS IoT콘솔의 테스트 페이지에서 출력 데이터 주제를 구독하여 커넥터의 상태 메시지를 확인합니다. 예제 Lambda 함수는 수명이 긴 함수로 그룹이 배포된 직후 메시지 전송을 시작합니다.

    테스트를 마치면 Lambda 수명 주기를 온디맨드 함수(또는 CLI의 "Pinned": false)로 설정하고 그룹을 배포할 수 있습니다. 이렇게 하면 함수가 메시지 전송을 중지합니다.

예

다음 예제 Lambda 함수는 커넥터에 입력 메시지를 보냅니다.

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

라이선스

CloudWatch Metrics 커넥터에는 다음과 같은 타사 소프트웨어/라이선스가 포함됩니다.

이 커넥터는 Greengrass 코어 소프트웨어 라이선스 계약에 따라 릴리스됩니다.

Changelog

다음 표에서는 의 각 릴리스에서 변경된 중요 사항에 대해 설명합니다.

버전

변경

5

입력 데이터의 중복 타임스탬프에 대한 지원을 추가하도록 수정했습니다.

4

커넥터에 대한 컨테이너화 모드를 구성하는 IsolationMode 파라미터가 추가되었습니다.

3

Lambda 런타임 요구 사항을 변경하는 Python 3.7로 런타임을 업그레이드했습니다.

2

과도한 로깅을 줄이도록 고정합니다.

1

최초 릴리스.

Greengrass 그룹은 한 번에 하나의 커넥터 버전만 포함할 수 있습니다. 커넥터 버전 업그레이드에 대한 자세한 내용은 커넥터 버전 업그레이드을 참조하십시오.

다음 사항도 참조하십시오.