1단계: CloudWatch 에이전트 설치 2단계: Prometheus 소스 스크레이프 및 지표 가져오기 예: Prometheus 지표 테스트를 위한 Java/JMX 샘플 워크로드 설정

Amazon EC2 인스턴스에서 Prometheus 지표 수집 설정 및 구성

다음 단원에서는 EC2 인스턴스에 Prometheus 모니터링이 포함된 CloudWatch 에이전트를 설치하는 방법과 추가 대상을 스크레이프하도록 에이전트를 구성하는 방법을 설명합니다. 또한 Prometheus 모니터링을 통해 테스트하는 데 사용할 샘플 워크로드를 설정하기 위한 튜토리얼도 제공합니다.

CloudWatch 에이전트에서 지원하는 운영 체제에 대한 자세한 내용은 CloudWatch 에이전트를 사용하여 지표, 로그, 추적 수집 단원을 참조하세요.

VPC 보안 그룹 요구 사항

VPC를 사용하는 경우 다음 요구 사항이 적용됩니다.

Prometheus 워크로드의 보안 그룹 수신 규칙은 프라이빗 IP로 Prometheus 지표를 스크레이프하기 위해 CloudWatch 에이전트에 대한 Prometheus 포트를 열어야 합니다.
CloudWatch 에이전트의 보안 그룹 송신 규칙은 CloudWatch 에이전트가 프라이빗 IP로 Prometheus 워크로드의 포트에 연결할 수 있도록 허용해야 합니다.

주제

1단계: CloudWatch 에이전트 설치
2단계: Prometheus 소스 스크레이프 및 지표 가져오기
예: Prometheus 지표 테스트를 위한 Java/JMX 샘플 워크로드 설정

1단계: CloudWatch 에이전트 설치

첫 번째 단계는 EC2 인스턴스에 CloudWatch 에이전트를 설치하는 것입니다. 지침은 CloudWatch 에이전트 설치 단원을 참조하십시오.

2단계: Prometheus 소스 스크레이프 및 지표 가져오기

Prometheus 모니터링이 포함된 CloudWatch 에이전트는 Prometheus 지표를 스크레이프하는 데 두 가지 구성이 필요합니다. 하나는 Prometheus 설명서의 <scrape_config>에 설명된 표준 Prometheus 구성을 위한 것입니다. 다른 하나는 CloudWatch 에이전트 구성을 위한 것입니다.

Prometheus 스크레이프 구성

CloudWatch 에이전트는 Prometheus 설명서의 <scrape_config>에 설명된 대로 표준 Prometheus 스크레이프 구성을 지원합니다. 이 섹션을 편집하여 이 파일에 이미 있는 구성을 업데이트하고 Prometheus 스크레이핑 대상을 더 추가할 수 있습니다. 샘플 구성 파일에는 다음과 같은 글로벌 구성 줄이 포함되어 있습니다.


PS C:\ProgramData\Amazon\AmazonCloudWatchAgent> cat prometheus.yaml
global:
  scrape_interval: 1m
  scrape_timeout: 10s
scrape_configs:
- job_name: MY_JOB
  sample_limit: 10000
  file_sd_configs:
    - files: ["C:\\ProgramData\\Amazon\\AmazonCloudWatchAgent\\prometheus_sd_1.yaml", "C:\\ProgramData\\Amazon\\AmazonCloudWatchAgent\\prometheus_sd_2.yaml"]

global 섹션에서는 모든 구성 컨텍스트에서 유효한 파라미터를 지정합니다. 이러한 파라미터는 다른 구성 섹션의 기본값으로도 사용됩니다. 여기에는 다음 파라미터가 포함됩니다.

scrape_interval - 대상을 스크레이프하는 빈도를 정의합니다.
scrape_timeout - 스크레이프 요청 시간이 초과되기 전에 대기할 시간을 정의합니다.

scrape_configs 섹션에서는 대상 세트 및 해당 대상을 스크레이프하는 방법을 정의하는 파라미터를 지정합니다. 여기에는 다음 파라미터가 포함됩니다.

job_name - 기본적으로 스크레이프한 지표에 할당된 작업 이름입니다.
sample_limit - 허용될 스크레이프한 샘플 수에 대한 스크레이프당 제한입니다.
file_sd_configs - 파일 서비스 검색 구성 목록입니다. 0개 이상의 정적 구성 목록이 포함된 파일 세트를 읽습니다. file_sd_configs 섹션에는 대상 그룹이 추출되는 파일의 패턴을 정의하는 files 파라미터가 포함되어 있습니다.

CloudWatch 에이전트는 다음과 같은 서비스 검색 구성 유형을 지원합니다.

static_config 대상 목록 및 해당 대상의 공통 레이블 세트를 지정할 수 있습니다. 스크레이프 구성에서 정적 대상을 지정하는 표준 방법입니다.

다음은 로컬 호스트에서 Prometheus 지표를 스크레이프하는 정적 구성 샘플입니다. 에이전트가 실행되는 서버에 대해 Prometheus 포트가 열려 있는 경우 다른 서버에서도 지표를 스크레이프할 수 있습니다.


PS C:\ProgramData\Amazon\AmazonCloudWatchAgent> cat prometheus_sd_1.yaml
- targets:
    - 127.0.0.1:9404
  labels:
    key1: value1
    key2: value2

이 예에는 다음 파라미터가 포함되어 있습니다.

targets - 정적 구성에 의해 스크레이프되는 대상입니다.
labels - 대상에서 스크레이프한 모든 지표에 할당되는 레이블입니다.

ec2_sd_config Amazon EC2 인스턴스에서 스크레이프 대상을 검색할 수 있습니다. 다음은 EC2 인스턴스 목록에서 Prometheus 지표를 스크레이프하는 ec2_sd_config 샘플입니다. 이러한 인스턴스의 Prometheus 포트는 CloudWatch 에이전트가 실행되는 서버에 대해 열려 있어야 합니다. CloudWatch 에이전트가 실행되는 EC2 인스턴스의 IAM 역할에는 ec2:DescribeInstance 권한이 포함되어 있어야 합니다. 예를 들어 관리형 정책 AmazonEC2ReadOnlyAccess를 CloudWatch 에이전트가 실행되는 인스턴스에 연결할 수 있습니다.


PS C:\ProgramData\Amazon\AmazonCloudWatchAgent> cat prometheus.yaml
global:
  scrape_interval: 1m
  scrape_timeout: 10s
scrape_configs:
  - job_name: MY_JOB
    sample_limit: 10000
    ec2_sd_configs:
      - region: us-east-1
        port: 9404
        filters:
          - name: instance-id
            values:
              - i-98765432109876543
              - i-12345678901234567

이 예에는 다음 파라미터가 포함되어 있습니다.

region - 대상 EC2 인스턴스가 있는 AWS 리전입니다. 이 값을 비워 두면 인스턴스 메타데이터의 리전이 사용됩니다.
port - 지표를 스크레이프할 포트입니다.
filters - 인스턴스 목록을 필터링하는 데 사용할 필터입니다(선택 사항). 이 예에서는 EC2 인스턴스 ID를 기준으로 필터링합니다. 필터링에 사용할 수 있는 다른 기준에 대해서는 DescribeInstances 단원을 참조하세요.

Prometheus에 대한 CloudWatch 에이전트 구성

CloudWatch 에이전트 구성 파일에는 logs와 metrics_collected 모두에 prometheus 섹션이 포함되어 있습니다. 이 섹션에는 다음 파라미터가 포함됩니다.

cluster_name - 로그 이벤트에서 레이블로 추가할 클러스터 이름을 지정합니다. 이 필드는 선택 사항입니다.
log_group_name - 스크레이프한 Prometheus 지표의 로그 그룹 이름을 지정합니다.
prometheus_config_path - Prometheus 스크레이프 구성 파일 경로를 지정합니다.
emf_processor - 임베디드 지표 형식 프로세서 구성을 지정합니다. 포함된 지표 형식에 대한 자세한 내용은 로그 내에 지표 포함 단원을 참조하세요.

emf_processor 섹션에는 다음 파라미터가 포함될 수 있습니다.
- metric_declaration_dedup - true로 설정하면 임베디드 지표 형식 지표에 대한 중복 제거 기능이 사용됩니다.
- metric_namespace - 내보낸 CloudWatch 지표의 지표 네임스페이스를 지정합니다.
- metric_unit - 지표 이름:지표 단위 맵을 지정합니다. 지원되는 지표 단위에 대한 자세한 내용은 MetricDatum 단원을 참조하세요.
- metric_declaration - 생성할 임베디드 지표 형식이 있는 로그 배열을 지정하는 섹션입니다. CloudWatch 에이전트가 기본적으로 가져오는 각 Prometheus 소스에 대한 metric_declaration 섹션이 있습니다. 이러한 섹션에는 각각 다음 필드가 포함됩니다.
  - source_labels는 label_matcher 줄에 의해 확인되는 레이블의 값을 지정합니다.
  - label_matcher는 source_labels에 나열된 레이블의 값을 확인하는 정규 표현식입니다. 일치하는 지표는 CloudWatch에 전송된 임베디드 지표 형식에 포함할 수 있습니다.
  - metric_selectors는 수집하여 CloudWatch에 보낼 지표를 지정하는 정규 표현식입니다.
  - dimensions는 선택한 각 지표의 CloudWatch 측정기준으로 사용할 레이블 목록입니다.

다음은 Prometheus에 대한 CloudWatch 에이전트 구성의 예입니다.


{
   "logs":{
      "metrics_collected":{
         "prometheus":{
            "cluster_name":"prometheus-cluster",
            "log_group_name":"Prometheus",
            "prometheus_config_path":"C:\\ProgramData\\Amazon\\AmazonCloudWatchAgent\\prometheus.yaml",
            "emf_processor":{
               "metric_declaration_dedup":true,
               "metric_namespace":"CWAgent-Prometheus",
               "metric_unit":{
                  "jvm_threads_current": "Count",
                  "jvm_gc_collection_seconds_sum": "Milliseconds"
               },
               "metric_declaration":[
                  {
                     "source_labels":[
                        "job", "key2"
                     ],
                     "label_matcher":"MY_JOB;^value2",
                     "dimensions":[
                        [
                           "key1", "key2"
                        ],
                        [
                           "key2"
                        ]
                     ],
                     "metric_selectors":[
                        "^jvm_threads_current$",
                        "^jvm_gc_collection_seconds_sum$"
                     ]
                  }
               ]
            }
         }
      }
   }
}

위 예에서는 다음 조건이 충족될 경우 임베디드 지표 형식 섹션을 로그 이벤트로 전송하도록 구성합니다.

job 레이블의 값은 MY_JOB입니다.
key2 레이블의 값은 value2입니다.
Prometheus 지표 jvm_threads_current 및 jvm_gc_collection_seconds_sum에는 job 레이블과 key2 레이블이 모두 포함되어 있습니다.

전송되는 로그 이벤트에는 다음과 같이 강조 표시된 섹션이 포함됩니다.


{
    "CloudWatchMetrics": [
        {
            "Metrics": [
                {
                    "Unit": "Count",
                    "Name": "jvm_threads_current"
                },
                {
                    "Unit": "Milliseconds",
                    "Name": "jvm_gc_collection_seconds_sum"
                }
            ],
            "Dimensions": [
                [
                    "key1",
                    "key2"
                ],
                [
                    "key2"
                ]
            ],
            "Namespace": "CWAgent-Prometheus"
        }
    ],
    "ClusterName": "prometheus-cluster",
    "InstanceId": "i-0e45bd06f196096c8",
    "Timestamp": "1607966368109",
    "Version": "0",
    "host": "EC2AMAZ-PDDOIUM",
    "instance": "127.0.0.1:9404",
    "jvm_threads_current": 2,
    "jvm_gc_collection_seconds_sum": 0.006000000000000002,
    "prom_metric_type": "gauge",
    ...
}

예: Prometheus 지표 테스트를 위한 Java/JMX 샘플 워크로드 설정

JMX Exporter는 JMX mBeans를 스크레이프하여 노출할 수 있는 공식 Prometheus 익스포터입니다. 자세한 내용은 prometheus/jmx_exporter를 참조하세요.

CloudWatch 에이전트는 EC2 인스턴스의 JMX Exporter를 통해 Java 가상 머신(JVM), Hjava, Tomcat(Catalina)에서 미리 정의된 Prometheus 지표를 수집할 수 있습니다.

1단계: CloudWatch 에이전트 설치

첫 번째 단계는 EC2 인스턴스에 CloudWatch 에이전트를 설치하는 것입니다. 지침은 CloudWatch 에이전트 설치 단원을 참조하십시오.

2단계: Java/JMX 워크로드 시작

다음 단계는 Java/JMX 워크로드를 시작하는 것입니다.

먼저, prometheus/jmx_exporter에서 최신 JMX Exporter jar 파일을 다운로드합니다.

샘플 애플리케이션에 jar 사용

다음 단원의 명령 예에서는 SampleJavaApplication-1.0-SNAPSHOT.jar를 jar 파일로 사용합니다. 명령의 이 부분을 자체 애플리케이션의 jar로 바꿉니다.

JMX Exporter 구성 준비

config.yaml 파일은 JMX Exporter 구성 파일입니다. 자세한 내용은 JMX Exporter 설명서의 구성을 참조하세요.

다음은 Java 및 Tomcat의 구성 샘플입니다.


---
lowercaseOutputName: true
lowercaseOutputLabelNames: true

rules:
- pattern: 'java.lang<type=OperatingSystem><>(FreePhysicalMemorySize|TotalPhysicalMemorySize|FreeSwapSpaceSize|TotalSwapSpaceSize|SystemCpuLoad|ProcessCpuLoad|OpenFileDescriptorCount|AvailableProcessors)'
  name: java_lang_OperatingSystem_$1
  type: GAUGE

- pattern: 'java.lang<type=Threading><>(TotalStartedThreadCount|ThreadCount)'
  name: java_lang_threading_$1
  type: GAUGE

- pattern: 'Catalina<type=GlobalRequestProcessor, name=\"(\w+-\w+)-(\d+)\"><>(\w+)'
  name: catalina_globalrequestprocessor_$3_total
  labels:
    port: "$2"
    protocol: "$1"
  help: Catalina global $3
  type: COUNTER

- pattern: 'Catalina<j2eeType=Servlet, WebModule=//([-a-zA-Z0-9+&@#/%?=~_|!:.,;]*[-a-zA-Z0-9+&@#/%=~_|]), name=([-a-zA-Z0-9+/$%~_-|!.]*), J2EEApplication=none, J2EEServer=none><>(requestCount|maxTime|processingTime|errorCount)'
  name: catalina_servlet_$3_total
  labels:
    module: "$1"
    servlet: "$2"
  help: Catalina servlet $3 total
  type: COUNTER

- pattern: 'Catalina<type=ThreadPool, name="(\w+-\w+)-(\d+)"><>(currentThreadCount|currentThreadsBusy|keepAliveCount|pollerThreadCount|connectionCount)'
  name: catalina_threadpool_$3
  labels:
    port: "$2"
    protocol: "$1"
  help: Catalina threadpool $3
  type: GAUGE

- pattern: 'Catalina<type=Manager, host=([-a-zA-Z0-9+&@#/%?=~_|!:.,;]*[-a-zA-Z0-9+&@#/%=~_|]), context=([-a-zA-Z0-9+/$%~_-|!.]*)><>(processingTime|sessionCounter|rejectedSessions|expiredSessions)'
  name: catalina_session_$3_total
  labels:
    context: "$2"
    host: "$1"
  help: Catalina session $3 total
  type: COUNTER

- pattern: ".*"

Prometheus Exporter로 Java 애플리케이션 시작

샘플 애플리케이션을 시작합니다. 그러면 Prometheus 지표가 포트 9404로 내보내집니다. 진입점 com.gubupt.sample.app.App을 샘플 Java 애플리케이션의 올바른 정보로 바꿔야 합니다.

Linux에서 다음 명령을 입력합니다.


$ nohup java -javaagent:./jmx_prometheus_javaagent-0.14.0.jar=9404:./config.yaml -cp  ./SampleJavaApplication-1.0-SNAPSHOT.jar com.gubupt.sample.app.App &

Windows에서 다음 명령을 입력합니다.


PS C:\> java -javaagent:.\jmx_prometheus_javaagent-0.14.0.jar=9404:.\config.yaml -cp  .\SampleJavaApplication-1.0-SNAPSHOT.jar com.gubupt.sample.app.App

Prometheus 지표 내보내기 확인

Prometheus 지표가 내보내지고 있는지 확인합니다.

Linux에서 다음 명령을 입력합니다.


$ curl localhost:9404

Windows에서 다음 명령을 입력합니다.


PS C:\> curl  http://localhost:9404

Linux에서의 샘플 출력:


StatusCode        : 200
StatusDescription : OK
Content           : # HELP jvm_classes_loaded The number of classes that are currently loaded in the JVM
                    # TYPE jvm_classes_loaded gauge
                    jvm_classes_loaded 2526.0
                    # HELP jvm_classes_loaded_total The total number of class...
RawContent        : HTTP/1.1 200 OK
                    Content-Length: 71908
                    Content-Type: text/plain; version=0.0.4; charset=utf-8
                    Date: Fri, 18 Dec 2020 16:38:10 GMT

                    # HELP jvm_classes_loaded The number of classes that are currentl...
Forms             : {}
Headers           : {[Content-Length, 71908], [Content-Type, text/plain; version=0.0.4; charset=utf-8], [Date, Fri, 18
                    Dec 2020 16:38:10 GMT]}
Images            : {}
InputFields       : {}
Links             : {}
ParsedHtml        : System.__ComObject
RawContentLength  : 71908

3단계: Prometheus 지표를 스크레이프하도록 CloudWatch 에이전트 구성

다음으로, CloudWatch 에이전트 구성 파일에서 Prometheus 스크레이프 구성을 설정합니다.

Java/JMX 예의 Prometheus 스크레이프 구성을 설정하려면

file_sd_config 및 static_config의 구성을 설정합니다.

Linux에서 다음 명령을 입력합니다.


$ cat /opt/aws/amazon-cloudwatch-agent/var/prometheus.yaml
global:
  scrape_interval: 1m
  scrape_timeout: 10s
scrape_configs:
  - job_name: jmx
    sample_limit: 10000
    file_sd_configs:
      - files: [ "/opt/aws/amazon-cloudwatch-agent/var/prometheus_file_sd.yaml" ]

Windows에서 다음 명령을 입력합니다.


PS C:\ProgramData\Amazon\AmazonCloudWatchAgent> cat prometheus.yaml
global:
  scrape_interval: 1m
  scrape_timeout: 10s
scrape_configs:
  - job_name: jmx
    sample_limit: 10000
    file_sd_configs:
      - files: [ "C:\\ProgramData\\Amazon\\AmazonCloudWatchAgent\\prometheus_file_sd.yaml" ]

스크레이프 대상 구성을 설정합니다.

Linux에서 다음 명령을 입력합니다.


$ cat /opt/aws/amazon-cloudwatch-agent/var/prometheus_file_sd.yaml
- targets:
  - 127.0.0.1:9404
  labels:
    application: sample_java_app
    os: linux

Windows에서 다음 명령을 입력합니다.


PS C:\ProgramData\Amazon\AmazonCloudWatchAgent> cat prometheus_file_sd.yaml
- targets:
  - 127.0.0.1:9404
  labels:
    application: sample_java_app
    os: windows

ec2_sc_config의 Prometheus 스크레이프 구성을 설정합니다. your-ec2-instance-id를 올바른 EC2 인스턴스 ID로 바꿉니다.

Linux에서 다음 명령을 입력합니다.


$ cat .\prometheus.yaml
global:
  scrape_interval: 1m
  scrape_timeout: 10s
scrape_configs:
  - job_name: jmx
    sample_limit: 10000
    ec2_sd_configs:
      - region: us-east-1
        port: 9404
        filters:
          - name: instance-id
            values:
              - your-ec2-instance-id

Windows에서 다음 명령을 입력합니다.


PS C:\ProgramData\Amazon\AmazonCloudWatchAgent> cat prometheus_file_sd.yaml
- targets:
  - 127.0.0.1:9404
  labels:
    application: sample_java_app
    os: windows

CloudWatch 에이전트 구성을 설정합니다. 먼저 올바른 디렉터리로 이동합니다. Linux의 경우 /opt/aws/amazon-cloudwatch-agent/var/cwagent-config.json입니다. Windows의 경우 C:\ProgramData\Amazon\AmazonCloudWatchAgent\cwagent-config.json입니다.

다음은 Java/JHX Prometheus 지표가 정의된 샘플 구성입니다. path-to-Prometheus-Scrape-Configuration-file을 올바른 경로로 바꿔야 합니다.


{
  "agent": {
    "region": "us-east-1"
  },
  "logs": {
    "metrics_collected": {
      "prometheus": {
        "cluster_name": "my-cluster",
        "log_group_name": "prometheus-test",
        "prometheus_config_path": "path-to-Prometheus-Scrape-Configuration-file",
        "emf_processor": {
          "metric_declaration_dedup": true,
          "metric_namespace": "PrometheusTest",
          "metric_unit":{
            "jvm_threads_current": "Count",
            "jvm_classes_loaded": "Count",
            "java_lang_operatingsystem_freephysicalmemorysize": "Bytes",
            "catalina_manager_activesessions": "Count",
            "jvm_gc_collection_seconds_sum": "Seconds",
            "catalina_globalrequestprocessor_bytesreceived": "Bytes",
            "jvm_memory_bytes_used": "Bytes",
            "jvm_memory_pool_bytes_used": "Bytes"
          },
          "metric_declaration": [
            {
              "source_labels": ["job"],
              "label_matcher": "^jmx$",
              "dimensions": [["instance"]],
              "metric_selectors": [
                "^jvm_threads_current$",
                "^jvm_classes_loaded$",
                "^java_lang_operatingsystem_freephysicalmemorysize$",
                "^catalina_manager_activesessions$",
                "^jvm_gc_collection_seconds_sum$",
                "^catalina_globalrequestprocessor_bytesreceived$"
              ]
            },
            {
              "source_labels": ["job"],
              "label_matcher": "^jmx$",
              "dimensions": [["area"]],
              "metric_selectors": [
                "^jvm_memory_bytes_used$"
              ]
            },
            {
              "source_labels": ["job"],
              "label_matcher": "^jmx$",
              "dimensions": [["pool"]],
              "metric_selectors": [
                "^jvm_memory_pool_bytes_used$"
              ]
            }
          ]
        }
      }
    },
    "force_flush_interval": 5
  }
}

다음 명령 중 하나를 입력하여 CloudWatch 에이전트를 다시 시작합니다.

Linux에서 다음 명령을 입력합니다.


sudo /opt/aws/amazon-cloudwatch-agent/bin/amazon-cloudwatch-agent-ctl -a fetch-config -m ec2 -s -c file:/opt/aws/amazon-cloudwatch-agent/var/cwagent-config.json

Windows에서 다음 명령을 입력합니다.


& "C:\Program Files\Amazon\AmazonCloudWatchAgent\amazon-cloudwatch-agent-ctl.ps1" -a fetch-config -m ec2 -s -c file:C:\ProgramData\Amazon\AmazonCloudWatchAgent\cwagent-config.json

Prometheus 지표 및 로그 보기

이제 수집 중인 Java/JMX 지표를 볼 수 있습니다.

샘플 Java/JMX 워크로드에 대한 지표를 보려면

https://console.aws.amazon.com/cloudwatch/에서 CloudWatch 콘솔을 엽니다.
클러스터가 실행되고 있는 리전에서 왼쪽 탐색 창의 [지표(Metrics)]를 선택합니다. PrometheusTest 네임스페이스를 찾아 지표를 확인합니다.
CloudWatch Logs 이벤트를 보려면 탐색 창에서 [로그 그룹(Log groups)]을 선택합니다. 이벤트는 로그 그룹 prometheus-test에 있습니다.

javascript가 브라우저에서 비활성화되거나 사용이 불가합니다.

AWS 설명서를 사용하려면 Javascript가 활성화되어야 합니다. 지침을 보려면 브라우저의 도움말 페이지를 참조하십시오.

문서 규칙

collectd를 사용하여 사용자 지정 지표 검색

Amazon CloudWatch Observability EKS 추가 기능 또는 차트 Helm을 사용하여 CloudWatch 에이전트 설치