本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。
# 在 Amazon EC2 執行個體上安裝和設定 Prometheus 指標集合
下列章節說明如何在 EC2 執行個體上安裝具有 Prometheus 監控的 CloudWatch 代理程式，以及如何設定代理程式來擷取其他目標。它也提供了設定範例工作負載的教學課程，以便搭配 Prometheus 監控使用測試。
支援 Windows 和 Linux 執行個體。
如需 CloudWatch 代理程式支援的作業系統相關資訊，請參閱 [使用 CloudWatch 代理程式收集指標、日誌和追蹤](Install-CloudWatch-Agent.md)
**VPC 安全群組要求**
如果您使用 VPC，則適用下列需求。
+ Prometheus 工作負載安全群組的輸入規則必須開啟到 CloudWatch 代理程式的 Prometheus 連接埠，以便透過私有 IP 擷取 Prometheus 指標。
+ CloudWatch 代理程式的安全群組的輸出規則必須允許 CloudWatch 代理程式透過私有 IP 連線到 Prometheus 工作負載的連接埠。
**Topics**
+ [步驟 1：安裝 CloudWatch 代理程式](#CloudWatch-Agent-PrometheusEC2-install)
+ [步驟 2：湊集 Prometheus 來源並匯入指標](#CloudWatch-Agent-PrometheusEC2-configure)
+ [範例：為 Prometheus 指標測試設定 Java/JMX 範例工作負載](#CloudWatch-Agent-Prometheus-Java)
## 步驟 1：安裝 CloudWatch 代理程式
第一步是在 EC2 執行個體上安裝 CloudWatch 代理程式。如需說明，請參閱[安裝 CloudWatch 代理程式](install-CloudWatch-Agent-on-EC2-Instance.md)。
## 步驟 2：湊集 Prometheus 來源並匯入指標
具有 Prometheus 監控功能的 CloudWatch 代理程式需要兩種組態來湊集 Prometheus 指標。其中一個是 Prometheus 文件的 [](https://prometheus.io/docs/prometheus/latest/configuration/configuration/#scrape_config) 中記錄的標準 Prometheus 湊集組態。另一個是 CloudWatch 代理程式組態。
### Prometheus 湊集組態
CloudWatch 代理程式支援標準 Prometheus 湊集組態，如 Prometheus 文件的 [](https://prometheus.io/docs/prometheus/latest/configuration/configuration/#scrape_config) 中所述。您可以編輯此區段來更新已存在於此檔案中的組態，並新增其他 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`— 檔案服務探索組態的清單。它讀取一組包含零個或多個靜態組態清單的檔案。`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_sd_config` 從 EC2 執行個體清單中湊集 Prometheus 指標。這些執行個體的 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](https://docs.aws.amazon.com/AWSEC2/latest/APIReference/API_DescribeInstances.html)。
### Prometheus 的 CloudWatch 代理程式組態
CloudWatch 代理程式組態檔案包含 `logs` 和 `metrics_collected` 中的 `prometheus` 區段。其包含以下參數。
+ **cluster\_name**— 指定要在日誌事件中新增為標籤的叢集名稱。此欄位為選用欄位。
+ **log\_group\_name**— 為湊集的 Prometheus 指標指定日誌檔案群組名稱。
+ **prometheus\_config\_path**— 指定 Prometheus 湊集組態檔案路徑。
+ **emf\_processor**— 指定內嵌指標格式處理器組態。如需內嵌指標格式的詳細資訊，請參閱[在日誌中內嵌指標](CloudWatch_Embedded_Metric_Format.md)。
`emf_processor` 區段可包含以下參數：
+ **metric\_declaration\_dedup**— 設定為 true，已啟用內嵌指標格式的重複資料刪除函數。
+ **metric\_namespace** – 指定發射的 CloudWatch 指標的指標命名空間。
+ **metric\_unit**— 指定指標名稱:指標單位映射。如需支援的指標單位之相關資訊，請參閱 [MetricDatum](https://docs.aws.amazon.com/AmazonCloudWatch/latest/APIReference/API_MetricDatum.html)。
+ **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 是官方的 Prometheus 匯出工具，可以湊集 JMX mBeans 並將其公開為 Prometheus 指標。如需詳細資訊，請參閱 [prometheus/jmx\_exporter](https://github.com/prometheus/jmx_exporter)。
CloudWatch 代理程式可以從 EC2 執行個體上的 JMX Exporter 收集來自 Java 虛擬機器 (JVM)、Hjava 和 Tomcat (Catalina) 的預先定義的 Prometheus 指標。
### 步驟 1：安裝 CloudWatch 代理程式
第一步是在 EC2 執行個體上安裝 CloudWatch 代理程式。如需說明，請參閱[安裝 CloudWatch 代理程式](install-CloudWatch-Agent-on-EC2-Instance.md)。
### 步驟 2：啟動 Java/JMX 工作負載
下一步是啟動 Java/JMX 工作負載。
首先，從以下位置下載最新的 JMX Exporter jar 檔案：[prometheus/jmx\_exporter](https://github.com/prometheus/jmx_exporter)。
**為您的範例應用程式使用 jar**
以下章節中的範例命令使用 `SampleJavaApplication-1.0-SNAPSHOT.jar` 作為 jar 檔案。用您的應用程式的 jar 取代命令的這些部分。
#### 準備 JMX Exporter 組態
`config.yaml` 檔案是 JMX Exporter 組態檔案。如需詳細資訊，請參閱 JMX Exporter 文件中的[組態](https://github.com/prometheus/jmx_exporter#Configuration)。
以下是 Java 和 Tomcat 的範例組態：
```
---
lowercaseOutputName: true
lowercaseOutputLabelNames: true
rules:
- pattern: 'java.lang<>(FreePhysicalMemorySize|TotalPhysicalMemorySize|FreeSwapSpaceSize|TotalSwapSpaceSize|SystemCpuLoad|ProcessCpuLoad|OpenFileDescriptorCount|AvailableProcessors)'
name: java_lang_OperatingSystem_$1
type: GAUGE
- pattern: 'java.lang<>(TotalStartedThreadCount|ThreadCount)'
name: java_lang_threading_$1
type: GAUGE
- pattern: 'Catalina<>(\w+)'
name: catalina_globalrequestprocessor_$3_total
labels:
port: "$2"
protocol: "$1"
help: Catalina global $3
type: COUNTER
- pattern: 'Catalina<>(requestCount|maxTime|processingTime|errorCount)'
name: catalina_servlet_$3_total
labels:
module: "$1"
servlet: "$2"
help: Catalina servlet $3 total
type: COUNTER
- pattern: 'Catalina<>(currentThreadCount|currentThreadsBusy|keepAliveCount|pollerThreadCount|connectionCount)'
name: catalina_threadpool_$3
labels:
port: "$2"
protocol: "$1"
help: Catalina threadpool $3
type: GAUGE
- pattern: 'Catalina<>(processingTime|sessionCounter|rejectedSessions|expiredSessions)'
name: catalina_session_$3_total
labels:
context: "$2"
host: "$1"
help: Catalina session $3 total
type: COUNTER
- pattern: ".*"
```
#### 使用 Prometheus 匯出程式啟動 Java 應用程式
啟動範例應用程式 這會將 Prometheus 指標發射至連接埠 9404。請務必以 java 應用程式範例的正確資訊替換進入點 `com.gubupt.sample.app.App`。
若使用的是 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：設定 CloudWatch 代理程式以湊集 Prometheus 指標
接下來，在 CloudWatch 代理程式組態檔案中設定 Prometheus 湊集組態。
**若要為 Java/JMx 範例設定 Prometheus 湊集組態**
1. 設定 `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" ]
```
1. 設定湊集目標組態。
若使用的是 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
```
1. 透過 `ec2_sc_config` 設定 Prometheus 湊集組態。以正確的 EC2 執行個體 ID 取代 {{your-ec2-instance-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
```
1. 設定 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
}
}
```
1. 輸入下列其中一個命令，以重新啟動 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 指標。
**若要檢視範例 JAW/JMX 工作負載的指標**
1. 透過 [https://console.aws.amazon.com/cloudwatch/](https://console.aws.amazon.com/cloudwatch/) 開啟 CloudWatch 主控台。
1. 在執行叢集的區域中，在左側的導覽窗格中選擇 **Metrics** (指標)。尋找 **PrometheusTest** 命名空間來查看指標。
1. 若要查看 CloudWatch Logs 事件，請在導覽窗格中選擇 **Log groups** (日誌群組)。事件位於日誌群組 **prometheus-test**。