AWS CloudWatch Exporter 設定

注意

CloudWatch Exporter使用時の料金案内

CloudWatch ExporterはAWS CloudWatch APIを通じてメトリクスを照会する方式であるため、照会されるメトリクス数とAPI呼び出し量に応じてAWS CloudWatchの使用料金が発生する場合があります。料金はCloudWatchのメトリクス、APIリクエスト、ログ、ダッシュボード、アラームなどの使用量基準で課金されます。詳細についてはAWS公式料金表をご参照ください。

事前準備

AWSアカウント要件

AWSアカウントおよびコンソールへのアクセス権限
IAMポリシー/ユーザー/ロール(Role)作成権限
CloudWatchメトリクスの読み取り権限

IAMポリシーの作成

CloudWatch ExporterがAWS CloudWatch APIを呼び出すための最小権限ポリシーを作成します。このポリシーは、以下のすべての認証方式で共通して使用されます。

AWS ConsoleでIAM → ポリシー → ポリシーの作成に移動します。

JSONタブを選択後、以下の内容を入力します。

ノート

以下はポリシーの例です。実際に使用するサービスの権限のみを含めることを推奨します。

サービス	必要な権限	備考
EC2	`ec2:DescribeInstances`
EBS	`ec2:DescribeVolumes`
ALB/NLB/CLB	`elasticloadbalancing:DescribeLoadBalancers`
ALB/NLB Target Group	`elasticloadbalancing:DescribeTargetGroups`, `elasticloadbalancing:DescribeTargetHealth`	ターゲットグループの状態収集に必要
Auto Scaling Group	`autoscaling:DescribeAutoScalingGroups`
RDS / Aurora	`rds:DescribeDBInstances`
ElastiCache	`elasticache:DescribeCacheClusters`, `elasticache:DescribeReplicationGroups`
Elastic Beanstalk	`elasticbeanstalk:DescribeEnvironments`, `elasticbeanstalk:DescribeEnvironmentHealth`
Lambda	`lambda:ListFunctions`
ECS	`ecs:ListClusters`, `ecs:DescribeClusters`
S3	`s3:ListAllMyBuckets`

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Sid": "CloudWatchReadPolicy",
            "Effect": "Allow",
            "Action": [
                "cloudwatch:ListMetrics",
                "cloudwatch:GetMetricStatistics",
                "cloudwatch:GetMetricData"
            ],
            "Resource": "*"
        },
        {
            "Sid": "ResourceDiscoveryPolicy",
            "Effect": "Allow",
            "Action": [
                "tag:GetResources",
                "ec2:DescribeInstances",
                "ec2:DescribeVolumes",
                "elasticloadbalancing:DescribeLoadBalancers",
                "elasticloadbalancing:DescribeTargetGroups",
                "elasticloadbalancing:DescribeTargetHealth",
                "autoscaling:DescribeAutoScalingGroups",
                "rds:DescribeDBInstances",
                "elasticache:DescribeCacheClusters",
                "elasticache:DescribeReplicationGroups",
                "elasticbeanstalk:DescribeEnvironments",
                "elasticbeanstalk:DescribeEnvironmentHealth",
                "lambda:ListFunctions",
                "s3:ListAllMyBuckets",
                "ecs:ListClusters",
                "ecs:DescribeClusters"
            ],
            "Resource": "*"
        }
    ]
}

Tips

tag:GetResourcesはaws_tag_select機能の使用時に必要です。タグベースフィルタリングを使用しない場合は削除しても構いません。
最小権限の原則（Least Privilege）に従い、実際にモニタリング対象となるサービスの権限のみを含めることを推奨します。

ポリシー名を入力（例: CloudWatchExporterReadOnlyPolicy）して作成します。

認証方式の選択

CloudWatch ExporterはAWS SDKのデフォルト認証情報チェーン（Default Credential Chain）を使用し、以下の順序で認証情報を探索します。実行環境に合った方式を選択してください。

環境変数 → ~/.aws/credentials ファイル → EC2インスタンスプロファイル(IMDS)

方式	実行環境	Access Key	特徴
方式A: Access Key	すべての環境（オンプレミスを含む）	必要	設定がシンプル、キー管理（漏えい・ローテーション）が必要
方式B: EC2インスタンスプロファイル	EC2	不要	ロールをインスタンスに直接アタッチ。EC2実行時に推奨
方式C: インスタンスプロファイル + `role_arn`	EC2	不要	クロスアカウント収集、CloudWatch権限を別ロールに分離

ノート

config.ymlのrole_arnは「このロールをAssumeせよ」という指示にすぎず、Assumeを実行するためのベースとなる認証情報は別途必要です（方式AのキーまたはB方式のインスタンスプロファイル）。role_arn単体では動作しません。

方式A: Access Key認証

IAMユーザーの作成

AWS ConsoleでIAM > ユーザー > ユーザーの作成に移動します。
ユーザー名を入力してください。
- ユーザー名: cloudwatch-exporter
権限設定でポリシーを直接アタッチに移動し、CloudWatchExporterReadOnlyPolicyを選択します。
ユーザーの作成を完了します。
セキュリティ認証情報タブでアクセスキーを作成します。
ユースケースとしてAWS外部で実行されるアプリケーションを選択します。
発行されたAccess Key IDとSecret Access Keyを保存します。

注意
Secret Access Keyはこの画面でのみ確認できます。必ず安全な場所に保存してください。

AWS Credentialsの設定

CloudWatch ExporterがAWS APIにアクセスするための認証情報を設定します。

方法1. 環境変数方式

export AWS_ACCESS_KEY_ID="AKIAXXXXXXXXXXXXXXXX"
export AWS_SECRET_ACCESS_KEY="xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

永続的に適用するには~/.bashrcまたは~/.bash_profileに追記します。

echo 'export AWS_ACCESS_KEY_ID="AKIAXXXXXXXXXXXXXXXX"' >> ~/.bashrc
echo 'export AWS_SECRET_ACCESS_KEY="xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"' >> ~/.bashrc
source ~/.bashrc

注意

~/.bashrcに認証情報を平文で保存すると、ファイルへのアクセス権限を持つすべてのユーザーに露出する可能性があります。本番環境では方法2（Credentialsファイル方式）を推奨します。

方法2. AWS Credentialsファイル方式（推奨）

# ディレクトリの作成
mkdir -p ~/.aws

# credentialsファイルの作成
cat <<EOF > ~/.aws/credentials
[default]
aws_access_key_id = AKIAXXXXXXXXXXXXXXXX
aws_secret_access_key = xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
EOF

# configファイルの作成
cat <<EOF > ~/.aws/config
[default]
output = json
EOF

# 権限の設定
chmod 600 ~/.aws/credentials
chmod 600 ~/.aws/config

注意

方式Aはconfig.ymlに別途の設定はありません。Exporterは環境変数またはcredentialsファイルから自動的に認証情報を探索し、config.ymlにAccess Keyを設定するオプションはサポートされていません。

方式B: EC2インスタンスプロファイル（Access Key不要）

ロールをEC2インスタンスに直接アタッチする方式です。Access Keyとcredentialsファイルはいずれも不要で、SDKがインスタンスメタデータ（IMDS）から一時的な認証情報を自動的に取得します。長期的な認証情報がないためキーの漏えい・ローテーションの負担がなく、AWSのセキュリティベストプラクティスに合致します。

IAMロールの作成

AWS ConsoleでIAM > ロール > ロールの作成に移動します。

信頼されたエンティティとしてAWSのサービス > EC2を選択します。

信頼ポリシーは自動的に以下のように構成されます。

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Principal": { "Service": "ec2.amazonaws.com" },
            "Action": "sts:AssumeRole"
        }
    ]
}

権限ポリシーでCloudWatchExporterReadOnlyPolicyを選択します。
ロール名を入力し（例: cloudwatch-exporter-role）ロールを作成します。

EC2インスタンスへのロールのアタッチ

EC2コンソールでインスタンスを選択した後、アクション > セキュリティ > IAMロールを変更に移動し、作成したロールを選択して保存します。

ノート

ロールのアタッチはインスタンスの再起動なしに即座に反映されます。ただし、Exporterは起動時に認証情報チェーンを探索するため、すでに実行中だった場合はExporterの再起動が必要です。

アタッチの確認

# IMDSv2トークンを発行後、ロールのアタッチ状態を確認
TOKEN=$(curl -sX PUT "http://169.254.169.254/latest/api/token" -H "X-aws-ec2-metadata-token-ttl-seconds: 60")
curl -s -H "X-aws-ec2-metadata-token: $TOKEN" http://169.254.169.254/latest/meta-data/iam/security-credentials/
# → ロール名が出力されれば正常（404の場合は未アタッチ）

aws sts get-caller-identity
# → "Arn": "arn:aws:sts::<アカウントID>:assumed-role/<ロール名>/..." の出力を確認

注意

方式Bではconfig.ymlにrole_arnを設定しません。インスタンスにアタッチされたロールの権限がそのまま使用されます。インスタンスにアタッチしたロールと同じロールをrole_arnに指定すると、自分自身をAssumeしようとして403エラーが発生します。

ノート

方式Bもconfig.ymlに別途の設定はありません。インスタンスにアタッチされたロールの認証情報をIMDSから自動的に取得します。

方式C: インスタンスプロファイル + role_arn（AssumeRole）

インスタンスロールには最小権限（sts:AssumeRole）のみを持たせ、CloudWatchの読み取り権限は別のロールに分離する方式です。config.ymlのrole_arnに別アカウントのロールを指定すれば、クロスアカウントモニタリングも可能です。ロールが2つ必要です。

ノート

動作の仕組み
インスタンスロール（IMDS） → sts:AssumeRole呼び出し → 対象ロールの一時的な認証情報を取得 → CloudWatch API呼び出し

ロール	用途	アタッチするポリシー
インスタンスロール（例: `cloudwatch-exporter-instance-role`）	インスタンスにアタッチ、Assumeを実行	`sts:AssumeRole`権限のみ
対象ロール（例: `cloudwatch-read-role`）	CloudWatch読み取り	`CloudWatchExporterReadOnlyPolicy`

インスタンスロールの準備

方式Bと同様にEC2用のロール（cloudwatch-exporter-instance-role）を作成してインスタンスにアタッチしますが、CloudWatchポリシーの代わりに以下のインラインポリシーのみをアタッチします。

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": "sts:AssumeRole",
            "Resource": "arn:aws:iam::<アカウントID>:role/cloudwatch-read-role"
        }
    ]
}

対象ロールの作成

AWS ConsoleでIAM > ロール > ロールの作成に移動し、信頼されたエンティティとしてAWSアカウントを選択します。クロスアカウントの場合は該当のアカウントIDを入力します。
権限ポリシーでCloudWatchExporterReadOnlyPolicyをアタッチします。
ロール名を入力し（例: cloudwatch-read-role）ロールを作成します。

作成したロールで信頼関係タブに移動して信頼ポリシーを編集し、インスタンスロールをPrincipalとして指定します。

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Principal": {
                "AWS": "arn:aws:iam::<アカウントID>:role/cloudwatch-exporter-instance-role"
            },
            "Action": "sts:AssumeRole"
        }
    ]
}

ロールのサマリー画面でIAM > ロール > ロール名に移動し、ARNをコピーします。この値はconfig.ymlのrole_arnに使用します。
```
arn:aws:iam::<アカウントID>:role/cloudwatch-read-role
```

注意

両方の設定が必要です。インスタンスロールにAssumeRole権限がない場合、または対象ロールの信頼ポリシーにインスタンスロールが含まれていない場合、is not authorized to perform: sts:AssumeRole 403エラーが発生します。

AssumeRoleの確認

aws sts assume-role \
  --role-arn arn:aws:iam::<アカウントID>:role/cloudwatch-read-role \
  --role-session-name test
# 一時的な認証情報(AccessKeyId/SecretAccessKey/SessionToken)が出力されれば正常

ノート

SDKが一時的な認証情報（デフォルト1時間）を自動更新するため、別途のローテーション作業は不要です。

config.ymlへのrole_arn設定

role_arnはmetrics項目ではなく最上位キーで、対象ロールの作成でコピーした対象ロールのARNを指定します。3つの認証方式のうち、config.ymlに設定が必要なのは方式Cのみです。

region: ap-northeast-2
role_arn: arn:aws:iam::<アカウントID>:role/cloudwatch-read-role
# クロスアカウント収集時は別アカウントのロールARNを指定可能
metrics:
  - aws_namespace: AWS/EC2
    aws_metric_name: CPUUtilization
    aws_dimensions: [InstanceId]
    aws_statistics: [Average]

注意

role_arnには対象ロール（cloudwatch-read-role）のARNを指定してください。インスタンスにアタッチされたロールのARNを指定すると、自分自身をAssumeしようとして403エラーが発生します。

Javaのインストール

CloudWatch ExporterにはJava 11以上が必要です。（参考: CloudWatch Exporter Github）

Amazon Linux 2 / CentOS / RHEL

# Amazon Corretto 11のインストール (Amazon Linux 2)
sudo yum install -y java-11-amazon-corretto-headless

# またはOpenJDK 11のインストール
sudo yum install -y java-11-openjdk-headless

Ubuntu / Debian

sudo apt update
sudo apt install -y openjdk-11-jre-headless

CloudWatch Exporterのインストール

作業ディレクトリの作成

sudo mkdir -p /opt/cloudwatch-exporter
sudo chown $USER:$USER /opt/cloudwatch-exporter
cd /opt/cloudwatch-exporter

JARファイルのダウンロード

最新バージョンはGitHub Releasesで確認できます。

# 最新バージョンは下記のGitHub Releasesページで確認後、VERSIONに入力してください。
# https://github.com/prometheus/cloudwatch_exporter/releases
VERSION="0.16.0"

# JARファイルのダウンロード
wget https://github.com/prometheus/cloudwatch_exporter/releases/download/v${VERSION}/cloudwatch_exporter-${VERSION}-jar-with-dependencies.jar

# ファイル名を簡素化するためのシンボリックリンクの作成
ln -sf cloudwatch_exporter-${VERSION}-jar-with-dependencies.jar cloudwatch_exporter.jar

最終的なディレクトリ構造は以下の通りです。

/opt/cloudwatch-exporter/
├── cloudwatch_exporter.jar              # シンボリックリンク
├── cloudwatch_exporter-0.16.0-jar-with-dependencies.jar  # 実際のJARファイル
└── config.yml                           # 設定ファイル（次のセクションで作成）

設定ファイルの作成(config.yml)

従来のクラウドモニタリングはトグルボタンで収集を有効化しますが、OpenMetrics方式ではconfig.ymlファイルを直接作成して収集対象とメトリクスを設定します。

主要サービス別メトリクスドキュメント

サービス	Namespace	メトリクスドキュメント
EC2	AWS/EC2	https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/viewing_metrics_with_cloudwatch.html
RDS	AWS/RDS	https://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/rds-metrics.html
Aurora	AWS/RDS	https://docs.aws.amazon.com/AmazonRDS/latest/AuroraUserGuide/Aurora.AuroraMonitoring.Metrics.html
ALB	AWS/ApplicationELB	https://docs.aws.amazon.com/elasticloadbalancing/latest/application/load-balancer-cloudwatch-metrics.html
NLB	AWS/NetworkELB	https://docs.aws.amazon.com/elasticloadbalancing/latest/network/load-balancer-cloudwatch-metrics.html
CLB	AWS/ELB	https://docs.aws.amazon.com/elasticloadbalancing/latest/classic/elb-cloudwatch-metrics.html
Lambda	AWS/Lambda	https://docs.aws.amazon.com/lambda/latest/dg/monitoring-metrics.html
EBS	AWS/EBS	https://docs.aws.amazon.com/ebs/latest/userguide/using_cloudwatch_ebs.html
S3	AWS/S3	https://docs.aws.amazon.com/AmazonS3/latest/userguide/cloudwatch-monitoring.html
ECS	AWS/ECS	https://docs.aws.amazon.com/AmazonECS/latest/developerguide/cloudwatch-metrics.html
EKS	AWS/EKS	https://docs.aws.amazon.com/eks/latest/userguide/cloudwatch.html
DynamoDB	AWS/DynamoDB	https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/metrics-dimensions.html
ElastiCache	AWS/ElastiCache	https://docs.aws.amazon.com/AmazonElastiCache/latest/dg/CacheMetrics.html
SQS	AWS/SQS	https://docs.aws.amazon.com/AWSSimpleQueueService/latest/SQSDeveloperGuide/sqs-available-cloudwatch-metrics.html
SNS	AWS/SNS	https://docs.aws.amazon.com/sns/latest/dg/sns-monitoring-using-cloudwatch.html
API Gateway	AWS/ApiGateway	https://docs.aws.amazon.com/apigateway/latest/developerguide/api-gateway-metrics-and-dimensions.html
CloudFront	AWS/CloudFront	https://docs.aws.amazon.com/AmazonCloudFront/latest/DeveloperGuide/monitoring-using-cloudwatch.html
NAT Gateway	AWS/NATGateway	https://docs.aws.amazon.com/vpc/latest/userguide/vpc-nat-gateway-cloudwatch.html
AutoScaling	AWS/AutoScaling	https://docs.aws.amazon.com/autoscaling/ec2/userguide/ec2-auto-scaling-metrics.html
ElasticBeanstalk	AWS/ElasticBeanstalk	https://docs.aws.amazon.com/elasticbeanstalk/latest/dg/health-enhanced-cloudwatch.html

ノート

S3ストレージメトリクスは日次（daily）メトリクスのため、period_secondsを86400（1日）に設定する必要があります。

config.yml 基本構造

必須パラメータの説明

パラメータ	説明	例
`region`	AWSリージョン	`ap-northeast-2`
`aws_namespace`	AWSサービスのネームスペース	`AWS/EC2`, `AWS/RDS`
`aws_metric_name`	収集するメトリクス名	`CPUUtilization`
`aws_dimensions`	メトリクスの分類基準	`[InstanceId]`
`aws_statistics`	統計タイプ	`[Average, Maximum, Sum]`
`period_seconds`	データポイントの間隔（秒）	`300`（5分）
`range_seconds`	照会する時間範囲（秒）	`600`（10分）
`delay_seconds`	CloudWatchデータ遅延の補正（秒）	`600`（10分）

統計タイプ(aws_statistics)

統計	説明	使用例
`Average`	平均値	CPU使用率、メモリ使用率
`Sum`	合計	ネットワークトラフィック、リクエスト数
`Maximum`	最大値	ピークCPU、最大レイテンシ
`Minimum`	最小値	最小空き容量
`SampleCount`	サンプル数	データポイント数

全サービス推奨設定

サービス	period_seconds	range_seconds	delay_seconds
EC2 (基本モニタリング)	300	600	600
EC2 (詳細モニタリング)	60	300	120
EBS Volume	300	600	600
RDS	60	300	120
Lambda	60	300	120
ELB / ALB / NLB	60	300	120
DynamoDB	60	300	120
CloudFront	60	300	120
ElastiCache	60	300	120
S3 (リクエストメトリクス)	60	300	120
S3 (ストレージメトリクス)	86400	172800	600
ECS	60	300	120
ECS/ContainerInsights	60	300	120
AutoScaling	60	300	120
ElasticBeanstalk	60	300	120

値の設定式

period_seconds = 対象サービスのパブリッシュ間隔
range_seconds ≥ period_seconds × 2（安全マージン、通常2〜5倍）
delay_seconds ≥ period_seconds × 2

ノート

例外/注意事項

EC2基本モニタリング: 5分単位がデフォルトです。period_secondsを60に下げてもデータは5分に1回であるため、空のポイントが増えるだけです。
EBS Volume: EC2と同様に5分単位です。
S3ストレージメトリクス: 1日1回パブリッシュされます。period_secondsを86400（1日）に設定し、delay_secondsも十分に長く設定してください。
カスタムメトリクス（高解像度）: 1秒単位も可能ですがコストがかかります。通常は60で十分です。

CloudWatchデータが過去時点となる理由

集計期間が終了してから統計が算出されます。5分間の平均はその5分間がすべて経過してから計算されます。10:00〜10:05の平均を10:03に照会しても、期間がまだ終了していないため値が返されません。
取り込み遅延を回避するための照会遅延設定（delay_seconds）。CloudWatchはメトリクスがAPIに反映されるまで数分の遅延が発生します。不完全なデータを取得しないよう、OpenAgentは一定時間以前のデータのみを照会するよう設定されています。現在の設定基準では、EC2・ALB・EBSは約10〜15分前、ElastiCache・ECSは約1〜2分前のデータから安定して取得できます。（サービスごとのperiod_seconds・delay_seconds設定により異なります。）
EC2基本モニタリングは5分単位でパブリッシュ。AWSのデフォルト提供間隔が5分です。詳細モニタリング（有料）を有効にすると1分単位で収集されます。

config.yml 設定例

# config.yml 例
region: ap-northeast-2               # AWSリージョン
metrics:                             # 収集するメトリクスリスト
  - aws_namespace: AWS/EC2           # AWSサービスのネームスペース
    aws_metric_name: CPUUtilization  # メトリクス名
    aws_dimensions: [InstanceId]     # ディメンション（分類基準）
    aws_tag_select:                  # タグベースフィルタリングおよびラベル追加
      resource_type_selection: "ec2:instance"  # リソースタイプ
      resource_id_dimension: InstanceId        # ディメンションにマッピングするリソースID
    aws_statistics: [Average]        # 統計タイプ
    period_seconds: 300              # データポイントの間隔
    range_seconds: 600               # 照会時間範囲
    delay_seconds: 600               # データ遅延時間

Openmetrics cloudwatch config.yml

高度なパラメータ：フィルタリング

aws_dimension_select (特定リソースのみ収集)

- aws_namespace: AWS/EC2
  aws_metric_name: CPUUtilization
  aws_dimensions: [InstanceId]
  aws_dimension_select:
    InstanceId:
      - i-xxxxxxxxxxxxxxxx1
      - i-xxxxxxxxxxxxxxxx2
  aws_statistics: [Average]
  period_seconds: 300
  range_seconds: 600
  delay_seconds: 600

aws_dimension_select_regex (正規表現フィルタリング)

- aws_namespace: AWS/EC2
  aws_metric_name: CPUUtilization
  aws_dimensions: [InstanceId]
  aws_dimension_select_regex:
    InstanceId: "^i-0123.*"
  aws_statistics: [Average]
  period_seconds: 300
  range_seconds: 600
  delay_seconds: 600

aws_tag_select (タグベースフィルタリング) - 推奨

- aws_namespace: AWS/EC2
  aws_metric_name: CPUUtilization
  aws_dimensions: [InstanceId]
  aws_tag_select:
    tag_selections:
      Environment: ["production", "staging"]
      Team: ["devops"]
    resource_type_selection: "ec2:instance"
    resource_id_dimension: InstanceId
  aws_statistics: [Average]
  period_seconds: 300
  range_seconds: 600
  delay_seconds: 600

注意

tag_selectionsにキーを指定すると、該当タグが存在しないリソースはメトリクス収集の対象から除外されます。収集漏れが発生した場合は、まず対象リソースに該当のタグが設定されているかを確認してください。

サービス	resource_type_selection	resource_id_dimension
EC2	`ec2:instance`	`InstanceId`
ALB	`elasticloadbalancing:loadbalancer/app`	`LoadBalancer`
NLB	`elasticloadbalancing:loadbalancer/net`	`LoadBalancer`
CLB	`elasticloadbalancing:loadbalancer`	`LoadBalancerName`
RDS	`rds:db`	`DBInstanceIdentifier`
Aurora	`rds:cluster`	`DBClusterIdentifier`
EBS	`ec2:volume`	`VolumeId`
ElastiCache	`elasticache:cluster`	`CacheClusterId`

CloudWatch Exporterの実行

nohupでの実行（簡易テスト用）

cd /opt/cloudwatch-exporter

# バックグラウンド実行
nohup java -jar cloudwatch_exporter.jar 9106 config.yml > cloudwatch_exporter.log 2>&1 &

# プロセスの確認
ps aux | grep cloudwatch_exporter

# ログの確認
tail -100f cloudwatch_exporter.log

# 終了
pkill -f cloudwatch_exporter.jar

Systemdサービスへの登録（本番環境推奨）

方法1: 環境変数方式

sudo vi /etc/systemd/system/cloudwatch-exporter.service

[Unit]
Description=Prometheus CloudWatch Exporter
After=network-online.target

[Service]
Type=simple
WorkingDirectory=/opt/cloudwatch-exporter

# 環境変数でAWS Credentialsを直接設定
Environment="AWS_ACCESS_KEY_ID=AKIAXXXXXXXXXXXXXXXX"
Environment="AWS_SECRET_ACCESS_KEY=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

ExecStart=/usr/bin/java -jar /opt/cloudwatch-exporter/cloudwatch_exporter.jar 9106 /opt/cloudwatch-exporter/config.yml
Restart=always
RestartSec=5

[Install]
WantedBy=multi-user.target

方法2: AWS Credentialsファイル方式

sudo vi /etc/systemd/system/cloudwatch-exporter.service

[Unit]
Description=Prometheus CloudWatch Exporter
After=network-online.target

[Service]
Type=simple
WorkingDirectory=/opt/cloudwatch-exporter

# AWS SDKが $HOME/.aws/credentials ファイルを参照
# 例: /root/.aws/credentials ファイルを使用
Environment="HOME=/root"

ExecStart=/usr/bin/java -jar /opt/cloudwatch-exporter/cloudwatch_exporter.jar 9106 /opt/cloudwatch-exporter/config.yml
Restart=always
RestartSec=5

[Install]
WantedBy=multi-user.target

サービスの起動

sudo systemctl daemon-reload
sudo systemctl start cloudwatch-exporter
sudo systemctl enable cloudwatch-exporter
sudo systemctl status cloudwatch-exporter

OpenAgentのダウンロードと設定

すべてのファイルは同じディレクトリに配置する必要があります。

## Example
/opt/whatap/openagent/
├── openagent          # Executable file
├── whatap.conf        # Configuration file
└── scrape_config.yaml # Scraping configuration file

ディレクトリの移動と実行ファイルのダウンロード

mkdir -p /opt/whatap/openagent
cd /opt/whatap/openagent

## AMD64 (Intel/AMD 64-bit processor)
wget https://repo.whatap.io/openagent/latest/amd/openagent

## ARM64 (ARM processor in Linux environment)
## CAUTION: macOS Apple Silicon not supported
wget https://repo.whatap.io/openagent/latest/arm/openagent

実行権限の設定

chmod +x openagent

scrape_config.yamlの作成

scrape_config.yamlファイルが変更されると、OpenAgentは自動的に変更を検出して設定を再ロードします。別途の再起動は不要です。

注意

重要。スクレイピング間隔（interval）は必ずexporterのperiod_seconds以上に設定してください。
interval ≥ period_seconds

CloudWatchはperiod_secondsの間隔でのみ新しいデータポイントを生成します。しかしCloudWatch Exporterはスクレイピングリクエストが来るたびにCloudWatch APIをリアルタイムで呼び出すため、intervalをperiod_secondsより短く設定すると次のようになります。

新しいデータなし: 同じタイムスタンプの同じ値を重複して収集するだけです。
コストの増加: API呼び出し数はスクレイピング回数に比例して増加します。intervalを半分に減らすと、CloudWatch APIの料金は2倍になります。

exporter `period_seconds`	推奨`interval`
300 (EC2基本モニタリング、EBSなど)	`"300s"`以上
60 (RDS、ALB、EC2詳細モニタリングなど)	`"60s"`以上
86400 (S3ストレージメトリクス)	短く設定しても問題ないが、データは1日1回のみ更新

config.ymlにperiodが異なるメトリクスが混在している場合は、最も短いperiod_secondsに合わせれば問題ありません。

#scrape_config.yaml
features:
  openAgent:
    enabled: true
    targets:
      - targetName: cloudwatch-exporter
        type: StaticEndpoints
        # ターゲットはデフォルトで有効(enabled: true)であり、省略可能です
        enabled: true
        endpoints:
          - address: "192.168.49.2:9106"
            path: "/metrics"
            scheme: "http"
            interval: "300s"
            metricRelabelConfigs:
              - source_labels: [__name__]
                regex: ".*"
                action: keep

基本実行

./openagent standalone

バックグラウンド実行

nohup ./openagent standalone > /dev/null 2>&1 &

ログの確認

tail -f logs/whatap-boot-{yyyymmdd}.log

プロセス管理

# Check process
ps aux | grep openagent

# Terminate process
pkill openagent

StaticEndpoints設定要素

targetName: ターゲットの名前（識別用）
type: ターゲットタイプ（"StaticEndpoints"）
endpoints: スクレイピングするエンドポイントの定義
- address: スクレイピング対象のアドレス（IP:PORT または HOSTNAME:PORT）
- path: メトリクスのパス（デフォルト値: /metrics）
- scheme: スクレイピングプロトコル（http または https、デフォルト値: http）
- interval: スクレイピング間隔（デフォルト値: 60s）
- metricRelabelConfigs: スクレイピング後のメトリクスリラベリング設定

メトリクスリラベリング設定(metricRelabelConfigs)

OpenAgentはPrometheusのmetric_relabel_configsと同様のメトリクスリラベリング機能をサポートしています。この機能を使用すると、スクレイピング後にメトリクスをフィルタリングしたり、ラベルを変更したりできます。

リラベリング設定要素

source_labels: ソースラベルのリスト（配列）
separator: ソースラベルの値を連結する際に使用する区切り文字（デフォルト値: ;）
target_label: ターゲットラベル（結果を保存するラベル）
regex: ソースラベルの値に適用する正規表現
replacement: 置換値（正規表現のキャプチャグループ参照が可能、例: ${1}）
action: 実行するアクション（keep、drop、replace）

サポートされるアクション(action)

keep: 正規表現に一致するメトリクスのみ保持
drop: 正規表現に一致するメトリクスを削除
replace: ターゲットラベルの値を置換値に変更

例

1. 全メトリクスの収集

metricRelabelConfigs:
  - source_labels: [__name__]
    regex: ".*"
    action: keep

2. 特定メトリクスのみ保持

metricRelabelConfigs:
  - source_labels: [__name__]
    regex: "aws_ec2_cpuutilization_average"
    action: keep

3. 正規表現を使用したメトリクスフィルタリング

metricRelabelConfigs:
  - source_labels: [__name__]
    regex: "aws_ec2_(cpu|network).*"
    action: keep

4. ラベル名の変更

metricRelabelConfigs:
  - source_labels: [instance_id]
    target_label: ec2_instance_id
    replacement: "${1}"
    action: replace

5. 静的ラベルの追加

metricRelabelConfigs:
  - target_label: metric_src
    replacement: "whatap-open-agent"
    action: replace

事前準備​

AWSアカウント要件​

IAMポリシーの作成​

認証方式の選択​

方式A: Access Key認証​

IAMユーザーの作成​

AWS Credentialsの設定​

方式B: EC2インスタンスプロファイル（Access Key不要）​

IAMロールの作成​

EC2インスタンスへのロールのアタッチ​

アタッチの確認​

方式C: インスタンスプロファイル + role_arn（AssumeRole）​

インスタンスロールの準備​

対象ロールの作成​

AssumeRoleの確認​

config.ymlへのrole_arn設定​

Javaのインストール​

CloudWatch Exporterのインストール​

作業ディレクトリの作成​

JARファイルのダウンロード​

設定ファイルの作成(config.yml)​

主要サービス別メトリクスドキュメント​

config.yml 基本構造​

必須パラメータの説明​

統計タイプ(aws_statistics)​

全サービス推奨設定​

値の設定式​

CloudWatchデータが過去時点となる理由​

config.yml 設定例​

高度なパラメータ：フィルタリング​

CloudWatch Exporterの実行​

nohupでの実行（簡易テスト用）​

Systemdサービスへの登録（本番環境推奨）​

方法1: 環境変数方式​

方法2: AWS Credentialsファイル方式​

サービスの起動​

OpenAgentのダウンロードと設定​

ディレクトリの移動と実行ファイルのダウンロード​

実行権限の設定​

scrape_config.yamlの作成​

基本実行​

バックグラウンド実行​

ログの確認​

プロセス管理​

StaticEndpoints設定要素​

メトリクスリラベリング設定(metricRelabelConfigs)​

リラベリング設定要素​

サポートされるアクション(action)​

例​