# 他のデータソースにあるメトリクスへのクエリ CloudWatch では、他のデータソースにあるメトリクスのアラームをクエリ、可視化、作成できます。そのためには、CloudWatch を他のデータソースに接続します。これにより、CloudWatch コンソール内に単一の統合モニタリングエクスペリエンスを実現できます。データの保存場所に関係なく、インフラストラクチャとアプリケーションのメトリクスを一元的に表示できるため、問題をすばやく特定して解決できます。 CloudWatch ウィザードを使用してデータソースに接続すると、AWS CloudFormation スタックが作成されるので、AWS Lambda 関数をデプロイして設定できるようになります。この Lambda 関数は、データソースをクエリするたびにオンデマンドで実行されます。CloudWatch クエリビルダーには、メトリクス、テーブル、フィールド、ラベルなど、クエリ可能な要素のリストがリアルタイムに表示されます。何かを選択すると、選択したソースにネイティブの言語でクエリが事前に入力されます。 CloudWatch では、ウィザードの手順に従って、以下のデータソースに接続できます。データソースと認証情報を特定できるように、各データソースの基本情報を指定できます。また、独自の Lambda 関数を作成して、他のデータソースへのコネクタを手動で作成することもできます。 + Amazon OpenSearch Service - OpenSearch Service のログとトレースからメトリクスを導出します。 + Amazon Managed Service for Prometheus - PromQL を使用して、こうしたメトリクスをクエリします。 + Amazon RDS for MySQL - SQL を使用して、Amazon RDS テーブルに保存されているデータをメトリクスに変換します。 + Amazon RDS for PostgreSQL - SQL を使用して、Amazon RDS テーブルに保存されているデータをメトリクスに変換します。 + Amazon S3 CSV ファイル - Amazon S3 バケットに保存されている CSV ファイルのメトリクスデータを表示します。 + Microsoft Azure Monitor - Microsoft Azure Monitor アカウントからメトリクスをクエリします。 + Prometheus - PromQL を使用して、こうしたメトリクスをクエリします。 データソースへのコネクタを作成したら、「[別のデータソースにあるメトリクスのグラフ化](graph_a_metric.md#create-metric-graph-multidatasource)」でデータソースのメトリクスをグラフ化する方法を確認してください。データソースのメトリクスにアラームを設定する方法については、「[接続されたデータソースに基づいてアラームを作成する](Create_MultiSource_Alarm.md)」を参照してください。 **Topics** + [データソースへのアクセスの管理](CloudWatch_MultiDataSources_Permissions.md) + [ウィザードによる事前構築済みのデータソースへの接続](CloudWatch_MultiDataSources-Connect.md) + [データソースへのカスタムコネクタの作成](CloudWatch_MultiDataSources-Connect-Custom.md) + [カスタムデータソースの使用](CloudWatch_MultiDataSources-Custom-Use.md) + [データソースへのコネクタの削除](CloudWatch_MultiDataSources-Delete.md) # データソースへのアクセスの管理 CloudWatch は、CloudFormation を使用して、アカウントで必要になるリソースを作成します。IAM ユーザーに `CreateStack` アクセス許可を付与する場合は、`cloudformation:TemplateUrl` 条件を使用して CloudFormation テンプレートへのアクセスを制御することをお勧めします。 **警告** データソース呼び出しアクセス許可をユーザーに付与した場合、そのユーザーはデータソースに対して直接 IAM アクセス許可を持っていなくても、そのデータソースのメトリクスをクエリできます。例えば、Amazon Managed Service for Prometheus データソース Lambda 関数に対する `lambda:InvokeFunction` アクセス許可をユーザーに付与した場合、そのユーザーは対応する Amazon Managed Service for Prometheus ワークスペースに対して直接 IAM アクセスを持っていなくても、そのワークスペースからメトリクスをクエリできます。 データソースのテンプレート URL は、CloudWatch Settings Console の **[スタックを作成]** ページにあります。 ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Sid": "AllowCloudFormationCreateStack", "Effect": "Allow", "Action": [ "cloudformation:CreateStack" ], "Resource": "*", "Condition": { "StringEquals": { "cloudformation:TemplateUrl": [ "https://s3.us-east-1.amazonaws.com/amzn-s3-demo-bucket/template.json" ] } } } ] } ``` ------ CloudFormation アクセスを制御する方法の詳細については、「[AWS Identity and Access Management によるアクセスの制御](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/using-iam-template.html)」を参照してください。 # ウィザードによる事前構築済みのデータソースへの接続 このトピックでは、ウィザードを使用して CloudWatch を以下のデータソースに接続する手順について説明します。 + Amazon OpenSearch Service + Amazon Managed Service for Prometheus + Amazon RDS for MySQL + Amazon RDS for PostgreSQL + Amazon S3 CSV ファイル + Microsoft Azure Monitor + Prometheus このトピックのサブセクションでは、こうした各データソースを管理およびクエリする際の注意事項を説明します。 **データソースへのコネクタを作成するには** 1. CloudWatch コンソールの [https://console.aws.amazon.com/cloudwatch/](https://console.aws.amazon.com/cloudwatch/) を開いてください。 1. ナビゲーションペインで **[設定]** を選択します。 1. **[メトリクスのデータソース]** タブを選択します。 1. **[データソースを作成]** を選択します。 1. 目的のソースを選択し、**[次へ]** を選択します。 1. データソースの名前を入力します。 1. 選択したデータソースに応じて、その他の必要な情報を入力します。例えば、データソースにアクセスするための認証情報が必要になることもあれば、Prometheus ワークスペース名、データベース名、Amazon S3 バケット名といったデータソース識別情報が必要になることもあります。AWS サービスの場合、ウィザードがリソースを検出して選択ドロップダウンに入力します。 現在使用中のデータソースに関するその他の注意事項については、この手順に続く各セクションを参照してください。 1. CloudWatch を VPC 内のデータソースに接続するには、**[VPC を使用]** を選択し、使用する VPC を選択します。次に、サブネットとセキュリティグループを選択します。 1. **[CloudFormation が IAM リソースを作成することを承認します]** を選択します。このリソースは Lambda 関数実行ロールです。 1. **[データソースを作成]** を選択します。 先ほど追加した新しいソースは、CloudFormation スタックでの作成が完了するまで表示されません。進行状況を確認するには、**[CloudFormation スタックのステータスを見る]** を選択します。あるいは、更新アイコンを選択して、このリストを更新することもできます。 新しいデータソースがこのリストに表示されたら、使用する準備ができたことになります。**[CloudWatch メトリクスからクエリ]** を選択して、クエリを開始できます。詳細については、「[別のデータソースにあるメトリクスのグラフ化](graph_a_metric.md#create-metric-graph-multidatasource)」を参照してください。 ## Amazon Managed Service for Prometheus **データソース設定の更新** + データソースを手動で更新する場合は、次の操作を実行します。 + Amazon Managed Service for Prometheus ワークスペース ID を更新するには、データソースコネクタ Lambda 関数の `AMAZON_PROMETHEUS_WORKSPACE_ID` 環境変数を更新します。 + VPC 設定を更新する場合は、「[VPC アクセスの設定 (コンソール)](https://docs.aws.amazon.com/lambda/latest/dg/configuration-vpc.html#vpc-configuring)」で詳細を確認してください。 **データソースのクエリ** + Amazon Managed Service for Prometheus をクエリする場合は、**[マルチソースクエリ]** タブでデータソースを選択し、Amazon Managed Service for Prometheus コネクタを選択した後で、**クエリヘルパー**を使用してメトリクスとラベルを検出し、簡単な PromQL クエリを実行できます。また、PromQL クエリエディタを使用して PromQL クエリを作成することもできます。 + CloudWatch データソースコネクタでは、複数行にわたるクエリはサポートされていません。そうしたクエリを実行するか、そうしたクエリでアラームやダッシュボードウィジェットを作成すると、すべてのラインフィードがスペースに置き換えられます。場合によっては、クエリが無効になることもあります。例えば、クエリに 1 行のコメントが含まれていると、そのクエリは無効になります。コマンドラインまたは Infrastructure as Code から複数行にわたるクエリを使用してダッシュボードまたはアラームを作成しようとすると、API がそのアクションを拒否して、解析エラーが発生します。 ## Amazon OpenSearch Service **データソースの作成** OpenSearch ドメインが FGAC で有効になっている場合、コネクタ Lambda 関数の実行ロールを OpenSearch Service 内のユーザーにマッピングする必要があります。詳細については、OpenSearch Service ドキュメントの「[Managing permissions](https://docs.aws.amazon.com/opensearch-service/latest/developerguide/fgac.html#fgac-access-control)」の「**Mapping users to roles**」セクションを参照してください。 OpenSearch ドメインが Virtual Private Cloud (VPC) 内のみでアクセス可能である場合は、`AMAZON_OPENSEARCH_ENDPOINT` と呼ばれる Lambda 関数に新しい環境変数を手動で追加する必要があります。この変数の値は、OpenSearch エンドポイントのルートドメインにする必要があります。このルートドメインは、OpenSearch Service コンソールに一覧表示されているドメインエンドポイントから `https://` と `.es.amazonaws.com` を削除することで取得できます。例えば、ドメインエンドポイントが `https://sample-domain.us-east-1.es.amazonaws.com` の場合、ルートドメインは `sample-domain` になります。 **データソースの更新** + データソースを手動で更新する場合は、次の操作を実行します。 + OpenSearch Service ドメインを更新するには、データソースコネクタ Lambda 関数の `AMAZON_OPENSEARCH_DOMAIN_NAME` 環境変数を更新します。 + VPC 設定を更新する場合は、「[VPC アクセスの設定 (コンソール)](https://docs.aws.amazon.com/lambda/latest/dg/configuration-vpc.html#vpc-configuring)」で詳細を確認してください。 **データソースのクエリ** + OpenSearch Service をクエリする場合は、**[マルチソースクエリ]** タブでデータソースを選択した後で、以下の操作を実行します。 + クエリするインデックスを選択します。 + メトリクス名 (ドキュメント内の任意の数値フィールド) と統計を選択します。 + 時間軸 (ドキュメント内の任意の日付フィールド) を選択します。 + 適用するフィルター (ドキュメント内の任意の文字列フィールド) を選択します。 + **[グラフクエリ]** を選択します。 ## Amazon RDS for PostgreSQL と Amazon RDS for MySQL **データソースの作成** + データソースが VPC 内でのみアクセス可能な場合は、「[ウィザードによる事前構築済みのデータソースへの接続](#CloudWatch_MultiDataSources-Connect)」で説明しているように、コネクタの VPC 設定を含める必要があります。認証情報を取得するためにデータソースを VPC に接続しなければならない場合は、VPC にエンドポイントを設定する必要があります。詳細については、「[AWS Secrets Manager VPC エンドポイントの使用](https://docs.aws.amazon.com/secretsmanager/latest/userguide/vpc-endpoint-overview.html)」を参照してください。 さらに、Amazon RDS サービスの VPC エンドポイントを作成する必要があります。詳細については、「[Amazon RDS API とインターフェイス VPC エンドポイント (AWS PrivateLink)](https://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/vpc-interface-endpoints.html)」を参照してください。 **データソースの更新** + データソースを手動で更新する場合は、次の操作を実行します。 + データベースインスタンスを更新するには、データソースコネクタ Lambda 関数の `RDS_INSTANCE` 環境変数を更新します。 + Amazon RDS への接続に使用するユーザー名とパスワードを更新するには、AWS Secrets Manager を使用します。データソースに使用されるシークレットの ARN は、データソース Lambda 関数の環境変数 `RDS_SECRET` で確認できます。AWS Secrets Manager でシークレットを更新する方法の詳細については、「[Modify an AWS Secrets Manager secret](https://docs.aws.amazon.com/secretsmanager/latest/userguide/manage_update-secret.html)」を参照してください。 + VPC 設定を更新する場合は、「[VPC アクセスの設定 (コンソール)](https://docs.aws.amazon.com/lambda/latest/dg/configuration-vpc.html#vpc-configuring)」で詳細を確認してください。 **データソースのクエリ** + Amazon RDS をクエリする場合は、**[マルチソースクエリ]** タブでデータソースを選択し、Amazon RDS コネクタを選択した後で、データベースディスカバラーを使用して、使用可能なデータベース、テーブル、列を表示できます。また、SQL エディタを使用して、SQL クエリを作成することもできます。 作成した SQL クエリでは、以下の変数を使用できます。 + `$start.iso` - ISO 日付形式の開始時刻 + `$end.iso` - ISO 日付形式の終了時刻 + `$period` - 選択した期間 (秒) 例えば、`SELECT value, timestamp FROM table WHERE timestamp BETWEEN $start.iso and $end.iso` というクエリを実行できます。 + CloudWatch データソースコネクタでは、複数行にわたるクエリはサポートされていません。そうしたクエリを実行するか、そうしたクエリでアラームやダッシュボードウィジェットを作成すると、すべてのラインフィードがスペースに置き換えられます。場合によっては、クエリが無効になることもあります。例えば、クエリに 1 行のコメントが含まれていると、そのクエリは無効になります。コマンドラインまたは Infrastructure as Code から複数行にわたるクエリを使用してダッシュボードまたはアラームを作成しようとすると、API がそのアクションを拒否して、解析エラーが発生します。 **注記** 結果に日付フィールドがない場合は、各数値フィールドの値が合計されて 1 つの値になり、指定された時間範囲にわたってプロットされます。タイムスタンプが CloudWatch で選択された期間と一致しない場合、データは `SUM` を使用して自動的に集計され、CloudWatch の期間に合わせて調整されます。 ## Amazon S3 CSV ファイル **データソースのクエリ** + Amazon S3 CSV ファイルをクエリする場合は、**[マルチソースクエリ]** タブでデータソースを選択し、Amazon S3 コネクタを選択した後で、Amazon S3 バケットとキーを選択します。 CSV ファイルの形式は、次のようにする必要があります。 + タイムスタンプは最初の列である必要があります。 + テーブルにはヘッダー行が必要です。ヘッダーは、メトリクスに名前を付けるために使用されます。タイムスタンプ列のタイトルは無視され、メトリクス列のタイトルのみが使用されます。 + タイムスタンプは ISO 日付形式である必要があります。 + メトリクスは数値フィールドである必要があります。 ``` Timestamp, Metric-1, Metric-2, ... ``` 以下に例を示します。 [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/ja_jp/AmazonCloudWatch/latest/monitoring/CloudWatch_MultiDataSources-Connect.html) **注記** タイムスタンプが指定されていない場合は、各メトリクスの値が合計されて 1 つの値になり、指定された時間範囲にわたってプロットされます。タイムスタンプが CloudWatch で選択された期間と一致しない場合、データは `SUM` を使用して自動的に集計され、CloudWatch の期間に合わせて調整されます。 ## Microsoft Azure Monitor **データソースの作成** + Microsoft Azure Monitor に接続するには、テナント ID、クライアント ID、クライアントシークレットを指定する必要があります。認証情報は、AWS Secrets Manager に保存されます。詳細については、Microsoft のドキュメントの「[Create a Microsoft Entra application and service principal that can access resources](https://learn.microsoft.com/en-us/entra/identity-platform/howto-create-service-principal-portal)」を参照してください。 **データソースの更新** + データソースを手動で更新する場合は、次の操作を実行します。 + Azure Monitor への接続に使用されるテナント ID、クライアント ID、クライアントシークレットを更新するには、データソースに使用されるシークレットの ARN を確認します。これは、データソース Lambda 関数で `AZURE_CLIENT_SECRET` 環境変数として使用されています。AWS Secrets Manager でシークレットを更新する方法の詳細については、「[Modify an AWS Secrets Manager secret](https://docs.aws.amazon.com/secretsmanager/latest/userguide/manage_update-secret.html)」を参照してください。 **データソースのクエリ** + Azure Monitor をクエリする場合は、**[マルチソースクエリ]** タブでデータソースを選択し、Azure Monitor コネクタを選択した後で、Azure のサブスクリプション、リソースグループ、リソースを指定します。次に、メトリクス名前空間、メトリクス、集計を選択し、ディメンションでフィルタリングします。 ## Prometheus **データソースの作成** + Prometheus エンドポイントのほか、Prometheus をクエリするために必要なユーザーとパスワードを指定する必要があります。認証情報は、AWS Secrets Manager に保存されます。 + データソースが VPC 内でのみアクセス可能な場合は、「[ウィザードによる事前構築済みのデータソースへの接続](#CloudWatch_MultiDataSources-Connect)」で説明しているように、コネクタの VPC 設定を含める必要があります。認証情報を取得するためにデータソースを接続しなければならない場合は、VPC にエンドポイントを設定する必要があります。詳細については、「[AWS Secrets Manager VPC エンドポイントの使用](https://docs.aws.amazon.com/secretsmanager/latest/userguide/vpc-endpoint-overview.html)」を参照してください。 **データソース設定の更新** + データソースを手動で更新する場合は、次の操作を実行します。 + Prometheus エンドポイントを更新するには、データソース Lambda 関数で `PROMETHEUS_API_ENDPOINT` 環境変数として新しいエンドポイントを指定します。 + Prometheus への接続に使用されるユーザー名とパスワードを更新するには、データソースに使用されるシークレットの ARN を確認します。これは、データソース Lambda 関数で `PROMETHEUS_API_SECRET` 環境変数として使用されています。AWS Secrets Manager でシークレットを更新する方法の詳細については、「[Modify an AWS Secrets Manager secret](https://docs.aws.amazon.com/secretsmanager/latest/userguide/manage_update-secret.html)」を参照してください。 + VPC 設定を更新する場合は、「[VPC アクセスの設定 (コンソール)](https://docs.aws.amazon.com/lambda/latest/dg/configuration-vpc.html#vpc-configuring)」で詳細を確認してください。 **データソースのクエリ** **重要** Prometheus メトリクスタイプは CloudWatch メトリクスとは異なり、Prometheus で使用できるメトリクスの多くはその仕様上累積的です。Prometheus メトリクスをクエリするときに、データに追加で何らかの変換が適用されることはありません。メトリクス名またはラベルのみを指定した場合は、累積された値が表示されます。詳細については、Prometheus ドキュメントの「[Metric types](https://prometheus.io/docs/concepts/metric_types/)」を参照してください。 Prometheus メトリクスデータを CloudWatch メトリクスのように個別の値として表示するには、クエリをその実行前に編集する必要があります。例えば、場合によっては Prometheus メトリクス名よりも先に rate 関数への呼び出しを追加する必要があります。rate 関数とその他の Prometheus 関数のドキュメントについては、Prometheus ドキュメントの「[rate()](https://prometheus.io/docs/prometheus/latest/querying/functions/#rate)」を参照してください。 CloudWatch データソースコネクタでは、複数行にわたるクエリはサポートされていません。そうしたクエリを実行するか、そうしたクエリでアラームやダッシュボードウィジェットを作成すると、すべてのラインフィードがスペースに置き換えられます。場合によっては、クエリが無効になることもあります。例えば、クエリに 1 行のコメントが含まれていると、そのクエリは無効になります。コマンドラインまたは Infrastructure as Code から複数行にわたるクエリを使用してダッシュボードまたはアラームを作成しようとすると、API がそのアクションを拒否して、解析エラーが発生します。 ## 使用可能な更新の通知 Amazon から随時、新たに使用可能になったバージョンでコネクタを更新することをお勧めする旨が通知されます。その際、更新手順も一緒に通知されます。 # データソースへのカスタムコネクタの作成 このトピックでは、カスタムデータソースを CloudWatch に接続する方法について説明します。カスタムデータソースは、次の 2 つの方法で CloudWatch に接続できます。 + CloudWatch に用意されているサンプルのテンプレートを使用します。このテンプレートでは、JavaScript または Python のいずれかを使用できます。テンプレートには、Lambda 関数を作成するときに役立つサンプルの Lambda コードが含まれています。次に、カスタムデータソースに接続するようにテンプレートの Lambda 関数を変更できます。 + CloudWatch で使用するデータソースコネクタ、データクエリ、時系列の準備を実装する AWS Lambda 関数をゼロから作成します。具体的には、データポイントを必要に応じて事前集約またはマージし、CloudWatch との互換性が確保されるように期間とタイムスタンプを調整するという関数にします。 **Contents** + [テンプレートの使用](#CloudWatch_MultiDataSources-Connect-Custom-template) + [ゼロからのカスタムデータソースの作成](#CloudWatch_MultiDataSources-Connect-Custom-Lambda) + [ステップ 1: 関数を作成する](#MultiDataSources-Connect-Custom-Lambda-Function) + [GetMetricData イベント](#MultiDataSources-GetMetricData) + [DescribeGetMetricData イベント](#MultiDataSources-DescribeGetMetricData) + [CloudWatch アラームに関する重要な考慮事項](#MultiDataSources-Connect-Custom-Lambda-Alarms) + [(オプション) AWS Secrets Manager を使用した認証情報の保存](#MultiDataSources-Connect-Custom-Lambda-Secrets) + [(オプション) VPC のデータソースへの接続](#MultiDataSources-Connect-Custom-Lambda-VPC) + [ステップ 2: Lambda アクセス許可ポリシーを作成する](#MultiDataSources-Connect-Custom-Lambda-Permissions) + [ステップ 3: シークレットリソースを Lambda 関数にアタッチする](#MultiDataSources-Connect-Custom-Lambda-tags) ## テンプレートの使用 テンプレートを使用すると、サンプルの Lambda 関数が作成されるので、カスタムコネクタをすばやく構築できます。こうしたサンプル関数には、カスタムコネクタの構築でよくあるシナリオに対応したサンプルコードが用意されています。テンプレートを使用してコネクタを作成したら、Lambda コードを開き、そのコネクタをデータソースへの接続に使用するようにコードを変更できます。 また、テンプレートを使用した場合、CloudWatch が Lambda アクセス許可ポリシーの作成と Lambda 関数へのリソースタグのアタッチを行います。 **テンプレートを使用してカスタムデータソースへのコネクタを作成するには** 1. CloudWatch コンソールの [https://console.aws.amazon.com/cloudwatch/](https://console.aws.amazon.com/cloudwatch/) を開いてください。 1. ナビゲーションペインで **[設定]** を選択します。 1. **[メトリクスのデータソース]** タブを選択します。 1. **[データソースを作成]** を選択します。 1. **[カスタム - 入門ガイドテンプレート]** のラジオボタンを選択し、**[次へ]** を選択します。 1. データソースの名前を入力します。 1. リストされているテンプレートのいずれかを選択します。 1. Node.js または Python を選択します。 1. **[データソースを作成]** を選択します。 先ほど追加した新しいカスタムソースは、CloudFormation スタックでの作成が完了するまで表示されません。進行状況を確認するには、**[CloudFormation スタックのステータスを見る]** を選択します。あるいは、更新アイコンを選択して、このリストを更新することもできます。 新しいデータソースがこのリストに表示されたら、コンソールでテストして変更できます。 1. (オプション) コンソールでこのソースのテストデータをクエリする場合は、「[別のデータソースにあるメトリクスのグラフ化](graph_a_metric.md#create-metric-graph-multidatasource)」の手順に従ってください。 1. 必要に応じて Lambda 関数を変更します。 1. ナビゲーションペインで **[設定]** を選択します。 1. **[メトリクスのデータソース]** タブを選択します。 1. 変更するソースに対して **[Lambda コンソールで表示]** を選択します。 これで、データソースにアクセスするように関数を変更できます。詳細については、「[ステップ 1: 関数を作成する](#MultiDataSources-Connect-Custom-Lambda-Function)」を参照してください。 **注記** テンプレートを使用すると、Lambda 関数を記述する際に「[ステップ 2: Lambda アクセス許可ポリシーを作成する](#MultiDataSources-Connect-Custom-Lambda-Permissions)」や「[ステップ 3: シークレットリソースを Lambda 関数にアタッチする](#MultiDataSources-Connect-Custom-Lambda-tags)」の手順に従う必要がありません。テンプレートを使用したため、そのいずれのステップも CloudWatch によって実行されるからです。 ## ゼロからのカスタムデータソースの作成 このセクションのステップに従って、CloudWatch をデータソースに接続する Lambda 関数を作成します。 ### ステップ 1: 関数を作成する カスタムデータソースコネクタは、CloudWatch の `GetMetricData` イベントをサポートする必要があります。必要に応じて、`DescribeGetMetricData` イベントを実装して、CloudWatch コンソールでユーザーにコネクタの使用方法に関するドキュメントを提供することもできます。また、`DescribeGetMetricData` レスポンスを使用して、CloudWatch カスタムクエリビルダーに使用されるデフォルトを設定することもできます。 CloudWatch には、最初の一歩に役立つサンプルとしてコードスニペットが用意されています。詳細については、[https://github.com/aws-samples/cloudwatch-data-source-samples](https://github.com/aws-samples/cloudwatch-data-source-samples) でサンプルリポジトリを参照してください。 **制約** + Lambda からのレスポンスは 6 MB 未満でなければなりません。レスポンスが 6 MB を超える場合、`GetMetricData` レスポンスは Lambda 関数を `InternalError` としてマークし、データは返されません。 + Lambda 関数は、可視化とダッシュボードの用途では 10 秒以内に、アラームの用途では 4.5 秒以内に実行を完了する必要があります。実行時間がその時間を超えた場合、`GetMetricData` レスポンスは Lambda 関数を `InternalError` としてマークし、データは返されません。 + Lambda 関数は、エポックタイムスタンプを秒単位で使用して、その出力を送信する必要があります。 + Lambda 関数がデータを再サンプリングするのではなく CloudWatch ユーザーがリクエストした開始時間と期間の長さに対応しないデータを返した場合、CloudWatch ではそのデータは無視されます。こうした余分なデータは、いずれの可視化やアラームからも破棄されます。開始時刻から終了時刻までの範囲内にないデータも破棄されます。 例えば、ユーザーが 10:00 から 11:00 まで 5 分間隔でデータを要求した場合、「10:00:00 から 10:04:59 まで」と「10:05:00 から 10:09:59 まで」は有効な時間範囲としてデータが返されます。`10:00 value1`、`10:05 value2` といった時系列を返す必要があります。例えば、関数から `10:03 valueX` が返された場合、10:03 はリクエストされた開始時間と期間に対応していないため、関数はドロップされます。 + CloudWatch データソースコネクタでは、複数行にわたるクエリはサポートされていません。そうしたクエリを実行するか、そうしたクエリでアラームやダッシュボードウィジェットを作成すると、すべてのラインフィードがスペースに置き換えられます。場合によっては、クエリが無効になることもあります。 #### GetMetricData イベント **リクエストペイロード** 次に、Lambda 関数への入力として送信される `GetMetricData` リクエストペイロードの例を示します。 ``` { "EventType": "GetMetricData", "GetMetricDataRequest": { "StartTime": 1697060700, "EndTime": 1697061600, "Period": 300, "Arguments": ["serviceregistry_external_http_requests{host_cluster!=\"prod\"}"] } } ``` + **StartTime** - 返されるデータの中で最も古いデータであることを指定するタイムスタンプです。**Type** は、タイムスタンプエポック秒です。 + **EndTime** - 返されるデータの中で最も新しいデータであることを指定するタイムスタンプです。**Type** は、タイムスタンプエポック秒です。 + **Period** — メトリクスデータの各集計が表す秒数です。最小値は 60 秒です。**Type** は秒です。 + **Arguments** - Lambda メトリクス数式に渡す一連の引数です。引数を渡す方法の詳細については、「[Lambda 関数に引数を渡す方法](CloudWatch_MultiDataSources-Custom-Use.md#MultiDataSources-Connect-Custom-Lambda-arguments)」を参照してください。 **レスポンスペイロード** 次に、Lambda 関数から返される `GetMetricData` レスポンスペイロードの例を示します。 ``` { "MetricDataResults": [ { "StatusCode": "Complete", "Label": "CPUUtilization", "Timestamps": [ 1697060700, 1697061000, 1697061300 ], "Values": [ 15000, 14000, 16000 ] } ] } ``` レスポンスペイロードには、`MetricDataResults` フィールドまたは `Error` フィールドのいずれかが含まれ、両方が含まれることはありません。 `MetricDataResults` フィールドは、タイプ `MetricDataResult` の時系列フィールドのリストです。こうした時系列フィールドごとに、以下のフィールドを含めることができます。 + **StatusCode** - (オプション) `Complete` は、リクエストした時間範囲内のデータポイントがすべて返されたことを示します。`PartialData` は、データポイントが一部不足した状態で返されたことを示します。これを省略した場合、デフォルトは `Complete` です。 有効な値: `Complete` \$1 `InternalError` \$1 `PartialData` \$1 `Forbidden` + **Messages** - オプションのメッセージリストです。どのようなデータが返されたかに関する情報が追加で含まれています。 Type: `Code` と `Value` の文字列が含まれている [MessageData](https://docs.aws.amazon.com/AmazonCloudWatch/latest/APIReference/API_MessageData.html) オブジェクトの配列です。 + **Label** - データに関連付けられている判読可能なラベルです。 タイプ: 文字列 + **Timestamps** - エポック時間でフォーマットされた、データポイントのタイムスタンプです。タイムスタンプの数は常に値の数に一致し、`Timestamps[x]` の値は `Values[x`] です。 Type: タイムスタンプの配列 + **Values** - メトリクスのデータポイントで、`Timestamps` に対応しています。値の数は常にタイムスタンプの数に一致し、`Timestamps[x]` の値は `Values[x`] です。 Type: 倍精度の配列 `Error` オブジェクトの詳細については、以下のセクションを参照してください。 **エラーレスポンス形式** 必要に応じて、エラーレスポンスを使用してエラーの詳しい情報を提供できます。パラメータの欠落やパラメータの型の誤りなど検証エラーが発生した場合には、コード検証を使用してエラーを返すことをお勧めします。 次に、Lambda 関数で `GetMetricData` 検証例外が発生した場合のレスポンスの例を示します。 ``` { "Error": { "Code": "Validation", "Value": "Invalid Prometheus cluster" } } ``` 次に、アクセスの問題があるために Lambda 関数がデータを返すことができない場合のレスポンスの例を示します。レスポンスは単一の時系列に変換され、`Forbidden` というステータスコードが返されます。 ``` { "Error": { "Code": "Forbidden", "Value": "Unable to access ..." } } ``` 次に、Lambda 関数で全体的な `InternalError` 例外が発生した場合のレスポンスの例を示します。レスポンスは単一の時系列に変換され、`InternalError` というステータスコードとメッセージが返されます。エラーコードに `Validation` や `Forbidden` 以外の値があるたびに、CloudWatch では汎用的な内部エラーが発生したと見なされます。 ``` { "Error": { "Code": "PrometheusClusterUnreachable", "Value": "Unable to communicate with the cluster" } } ``` #### DescribeGetMetricData イベント **リクエストペイロード** 次に、`DescribeGetMetricData` リクエストペイロードの例を示します。 ``` { "EventType": "DescribeGetMetricData" } ``` **レスポンスペイロード** 次に、`DescribeGetMetricData` レスポンスペイロードの例を示します。 ``` { "Description": "Data source connector", "ArgumentDefaults": [{ Value: "default value" }] } ``` + **Description** - データソースコネクタの使用方法の説明です。この説明は、CloudWatch コンソールに表示されます。Markdown がサポートされています。 タイプ: 文字列 + **ArgumentDefaults** - カスタムデータソースビルダーを事前に入力しておくために必要に応じて使用できる、引数のデフォルト値からなる配列です。 `[{ Value: "default value 1"}, { Value: 10}]` が返された場合、CloudWatch コンソールのクエリビルダーに入力が 2 つ表示されます。1 つ目は「デフォルト値 1」で、2 つ目は 10 です。 `ArgumentDefaults` を指定しない場合、入力は 1 つだけ表示され、型がデフォルトの `String` に設定されます。 Type: 値と型が含まれているオブジェクトの配列です。 + **Error** - (オプション) エラーフィールドは、どのレスポンスにも含めることができます。「[GetMetricData イベント](#MultiDataSources-GetMetricData)」で例を確認できます。 #### CloudWatch アラームに関する重要な考慮事項 データソースを使用して CloudWatch アラームを設定する場合は、データをタイムスタンプ付きで 1 分ごとに CloudWatch に報告するように設定する必要があります。接続先のデータソースのメトリクスに対してアラームを作成する方法の詳細とその他の考慮事項については、「[接続されたデータソースに基づいてアラームを作成する](Create_MultiSource_Alarm.md)」を参照してください。 #### (オプション) AWS Secrets Manager を使用した認証情報の保存 Lambda 関数で認証情報を使用してデータソースにアクセスする必要がある場合は、認証情報を Lambda 関数にハードコーディングするのではなく、AWS Secrets Manager を使用して認証情報を保存しておくことをお勧めします。Lambda で AWS Secrets Manager を使用する方法の詳細については、「[Use AWS Secrets Manager secrets in AWS Lambda functions](https://docs.aws.amazon.com/secretsmanager/latest/userguide/retrieving-secrets_lambda.html)」を参照してください。 #### (オプション) VPC のデータソースへの接続 データソースが Amazon Virtual Private Cloud によって管理される VPC にある場合は、そのデータソースにアクセスするように Lambda 関数を設定する必要があります。詳細については、「[アウトバウンドネットワークを VPC 内のリソースに接続する](https://docs.aws.amazon.com/lambda/latest/dg/configuration-vpc.html)」を参照してください。 場合によっては、AWS Secrets Manager などのサービスにアクセスするように VPC サービスエンドポイントを設定する必要があります。詳細については、「[インターフェイス VPC エンドポイントを使用して AWS サービスにアクセスする](https://docs.aws.amazon.com/vpc/latest/privatelink/create-interface-endpoint.html#access-service-though-endpoint)」を参照してください。 ### ステップ 2: Lambda アクセス許可ポリシーを作成する 作成した Lambda 関数を使用するためには、ポリシーステートメントを作成して必要な CloudWatch アクセス許可を付与する必要があります。ポリシーステートメントは、AWS CLI または Lambda コンソールを使用して作成できます。 **AWS CLI を使用してポリシーステートメントを作成するには** + 次のコマンドを入力します。*123456789012* を自分のアカウント ID に、*my-data-source-function* を Lambda 関数の名前に、*MyDataSource-DataSourcePermission1234* を任意の一意の値にそれぞれ置き換えます。 ``` aws lambda add-permission --function-name my-data-source-function --statement-id MyDataSource-DataSourcePermission1234 --action lambda:InvokeFunction --principal lambda.datasource.cloudwatch.amazonaws.com --source-account 123456789012 ``` ### ステップ 3: シークレットリソースを Lambda 関数にアタッチする CloudWatch コンソールが、タグを使用してどの Lambda 関数がデータソースコネクタであるかを判断します。いずれかのウィザードを使用してデータソースを作成すると、その設定を行う CloudFormation スタックによってタグが自動的に適用されます。データソースを自分で作成する場合は、Lambda 関数に以下のタグを使用できます。これにより、メトリクスをクエリしたときに、コネクタが CloudWatch コンソールの **[データソース]** ドロップダウンに表示されます。 + `cloudwatch:datasource` をキーとし、`custom` を値とするタグ。 # カスタムデータソースの使用 データソースを作成したら、そのデータソースのデータをクエリして可視化し、アラームを設定できます。テンプレートを使用してカスタムデータソースコネクタを作成した場合や、「[ステップ 3: シークレットリソースを Lambda 関数にアタッチする](CloudWatch_MultiDataSources-Connect-Custom.md#MultiDataSources-Connect-Custom-Lambda-tags)」にリストされているタグを追加した場合は、「[別のデータソースにあるメトリクスのグラフ化](graph_a_metric.md#create-metric-graph-multidatasource)」の手順に従ってデータをクエリできます。また、この後のセクションで説明しているように、メトリクス数学関数 `LAMBDA` を使用してデータをクエリすることもできます。データソースのメトリクスに対してアラームを作成する方法については、「[接続されたデータソースに基づいてアラームを作成する](Create_MultiSource_Alarm.md)」を参照してください。このトピックでは、カスタムデータソースへの Lambda 関数に引数を渡す方法について説明します。 ## Lambda 関数に引数を渡す方法 カスタムデータソースに引数を渡す場合は、データソースをクエリするときに CloudWatch コンソールのクエリビルダーを使用するという方法をお勧めします。 また、CloudWatch メトリクス数式の新しい `LAMBDA` 式を使用することで、Lambda 関数を使用してデータソースからデータを取得することもできます。 ``` LAMBDA("LambdaFunctionName" [, optional-arg]*) ``` `optional-arg` は、最大 20 個の文字列、数値、またはブール値です。例えば、`param`、`3.14`、または `true` です。 **注記** CloudWatch データソースコネクタでは、複数行にわたる文字列はサポートされていません。そうしたクエリを実行するか、そうしたクエリでアラームやダッシュボードウィジェットを作成すると、すべてのラインフィードがスペースに置き換えられます。場合によっては、クエリが無効になることもあります。 `LAMBDA` メトリクス数学関数を使用する場合は、関数名 (`"MyFunction"`) を指定できます。リソースポリシーで許可されている場合は、関数の特定のバージョン (`"MyFunction:22"`) や Lambda 関数のエイリアス (`"MyFunction:MyAlias"`) を使用することもできます。`*` を使用することはできません。 次に、`LAMBDA` 関数の呼び出し例をいくつか示します。 ``` LAMBDA("AmazonOpenSearchDataSource", "MyDomain", "some-query") ``` ``` LAMBDA("MyCustomDataSource", true, "fuzzy", 99.9) ``` `LAMBDA` メトリクス数学関数は時系列のリストを返します。そのリストをリクエスタに返したり、他のメトリクス数学関数と組み合わせて使用したりできます。次に、`LAMBDA` を他のメトリクス数学関数と組み合わせた場合の例を示します。 ``` FILL(LAMBDA("AmazonOpenSearchDataSource", "MyDomain", "some-query"), 0) ``` # データソースへのコネクタの削除 このセクションの手順では、データソースへのコネクタを削除する方法について説明します。 **データソースへのコネクタを削除するには** 1. CloudWatch コンソールの [https://console.aws.amazon.com/cloudwatch/](https://console.aws.amazon.com/cloudwatch/) を開いてください。 1. ナビゲーションペインで **[設定]** を選択します。 1. **[メトリクスのデータソース]** タブを選択します。 1. 削除するデータソースの行で **[CloudFormation で管理]** を選択します。 CloudFormation コンソールに自動的に移動します。 1. データソースの名前が付いているセクションで、**[削除]** を選択します。 1. 確認ポップアップで、**[削除]** を選択します。