[AWS SDK for JavaScript V3 API リファレンスガイド](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/)では、 AWS SDK for JavaScript バージョン3 (V3) のすべての API オペレーションについて詳しく説明します。
翻訳は機械翻訳により提供されています。提供された翻訳内容と英語版の間で齟齬、不一致または矛盾がある場合、英語版が優先します。
# SDK for JavaScript (v3) を使用した CloudWatch Logs の例
次のコード例は、CloudWatch Logs で AWS SDK for JavaScript (v3) を使用してアクションを実行し、一般的なシナリオを実装する方法を示しています。
*アクション*はより大きなプログラムからのコードの抜粋であり、コンテキスト内で実行する必要があります。アクションは個々のサービス機能を呼び出す方法を示していますが、コンテキスト内のアクションは、関連するシナリオで確認できます。
*シナリオ*は、1 つのサービス内から、または他の AWS のサービスと組み合わせて複数の関数を呼び出し、特定のタスクを実行する方法を示すコード例です。
各例には完全なソースコードへのリンクが含まれており、コードの設定方法と実行方法に関する手順を確認できます。
**Topics**
+ [アクション](#actions)
+ [シナリオ](#scenarios)
## アクション
### `CreateLogGroup`
次のコード例は、`CreateLogGroup` を使用する方法を示しています。
**SDK for JavaScript (v3)**
GitHub には、その他のリソースもあります。用例一覧を検索し、[AWS コード例リポジトリ](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/javascriptv3/example_code/cloudwatch-logs#code-examples)での設定と実行の方法を確認してください。
```
import { CreateLogGroupCommand } from "@aws-sdk/client-cloudwatch-logs";
import { client } from "../libs/client.js";
const run = async () => {
const command = new CreateLogGroupCommand({
// The name of the log group.
logGroupName: process.env.CLOUDWATCH_LOGS_LOG_GROUP,
});
try {
return await client.send(command);
} catch (err) {
console.error(err);
}
};
export default run();
```
+ API の詳細については、*AWS SDK for JavaScript API リファレンス*の「[CreateLogGroup](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/client/cloudwatch-logs/command/CreateLogGroupCommand)」を参照してください。
### `DeleteLogGroup`
次のコード例は、`DeleteLogGroup` を使用する方法を示しています。
**SDK for JavaScript (v3)**
GitHub には、その他のリソースもあります。用例一覧を検索し、[AWS コード例リポジトリ](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/javascriptv3/example_code/cloudwatch-logs#code-examples)での設定と実行の方法を確認してください。
```
import { DeleteLogGroupCommand } from "@aws-sdk/client-cloudwatch-logs";
import { client } from "../libs/client.js";
const run = async () => {
const command = new DeleteLogGroupCommand({
// The name of the log group.
logGroupName: process.env.CLOUDWATCH_LOGS_LOG_GROUP,
});
try {
return await client.send(command);
} catch (err) {
console.error(err);
}
};
export default run();
```
+ API の詳細については、*AWS SDK for JavaScript API リファレンス*の「[DeleteLogGroup](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/client/cloudwatch-logs/command/DeleteLogGroupCommand)」を参照してください。
### `DeleteSubscriptionFilter`
次のコード例は、`DeleteSubscriptionFilter` を使用する方法を示しています。
**SDK for JavaScript (v3)**
GitHub には、その他のリソースもあります。用例一覧を検索し、[AWS コード例リポジトリ](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/javascriptv3/example_code/cloudwatch-logs#code-examples)での設定と実行の方法を確認してください。
```
import { DeleteSubscriptionFilterCommand } from "@aws-sdk/client-cloudwatch-logs";
import { client } from "../libs/client.js";
const run = async () => {
const command = new DeleteSubscriptionFilterCommand({
// The name of the filter.
filterName: process.env.CLOUDWATCH_LOGS_FILTER_NAME,
// The name of the log group.
logGroupName: process.env.CLOUDWATCH_LOGS_LOG_GROUP,
});
try {
return await client.send(command);
} catch (err) {
console.error(err);
}
};
export default run();
```
+ API の詳細については、*AWS SDK for JavaScript API リファレンス*の「[DeleteSubscriptionFilter](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/client/cloudwatch-logs/command/DeleteSubscriptionFilterCommand)」を参照してください。
### `DescribeLogGroups`
次のコード例は、`DescribeLogGroups` を使用する方法を示しています。
**SDK for JavaScript (v3)**
GitHub には、その他のリソースもあります。用例一覧を検索し、[AWS コード例リポジトリ](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/javascriptv3/example_code/cloudwatch-logs#code-examples)での設定と実行の方法を確認してください。
```
import {
paginateDescribeLogGroups,
CloudWatchLogsClient,
} from "@aws-sdk/client-cloudwatch-logs";
const client = new CloudWatchLogsClient({});
export const main = async () => {
const paginatedLogGroups = paginateDescribeLogGroups({ client }, {});
const logGroups = [];
for await (const page of paginatedLogGroups) {
if (page.logGroups?.every((lg) => !!lg)) {
logGroups.push(...page.logGroups);
}
}
console.log(logGroups);
return logGroups;
};
```
+ API の詳細については、*AWS SDK for JavaScript API リファレンス*の「[DescribeLogGroups](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/client/cloudwatch-logs/command/DescribeLogGroupsCommand)」を参照してください。
### `DescribeSubscriptionFilters`
次のコード例は、`DescribeSubscriptionFilters` を使用する方法を示しています。
**SDK for JavaScript (v3)**
GitHub には、その他のリソースもあります。用例一覧を検索し、[AWS コード例リポジトリ](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/javascriptv3/example_code/cloudwatch-logs#code-examples)での設定と実行の方法を確認してください。
```
import { DescribeSubscriptionFiltersCommand } from "@aws-sdk/client-cloudwatch-logs";
import { client } from "../libs/client.js";
const run = async () => {
// This will return a list of all subscription filters in your account
// matching the log group name.
const command = new DescribeSubscriptionFiltersCommand({
logGroupName: process.env.CLOUDWATCH_LOGS_LOG_GROUP,
limit: 1,
});
try {
return await client.send(command);
} catch (err) {
console.error(err);
}
};
export default run();
```
+ API の詳細については、*AWS SDK for JavaScript API リファレンス*の「[DescribeSubscriptionFilters](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/client/cloudwatch-logs/command/DescribeSubscriptionFiltersCommand)」を参照してください。
### `GetQueryResults`
次のコード例は、`GetQueryResults` を使用する方法を示しています。
**SDK for JavaScript (v3)**
GitHub には、その他のリソースもあります。用例一覧を検索し、[AWS コード例リポジトリ](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/javascriptv3/example_code/cloudwatch-logs#code-examples)での設定と実行の方法を確認してください。
```
/**
* Simple wrapper for the GetQueryResultsCommand.
* @param {string} queryId
*/
_getQueryResults(queryId) {
return this.client.send(new GetQueryResultsCommand({ queryId }));
}
```
+ API の詳細については、「**AWS SDK for JavaScript API リファレンス」の「[GetQueryResults](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/client/cloudwatch-logs/command/GetQueryResultsCommand)」を参照してください。
### `PutSubscriptionFilter`
次のコード例は、`PutSubscriptionFilter` を使用する方法を示しています。
**SDK for JavaScript (v3)**
GitHub には、その他のリソースもあります。用例一覧を検索し、[AWS コード例リポジトリ](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/javascriptv3/example_code/cloudwatch-logs#code-examples)での設定と実行の方法を確認してください。
```
import { PutSubscriptionFilterCommand } from "@aws-sdk/client-cloudwatch-logs";
import { client } from "../libs/client.js";
const run = async () => {
const command = new PutSubscriptionFilterCommand({
// An ARN of a same-account Kinesis stream, Kinesis Firehose
// delivery stream, or Lambda function.
// https://docs.aws.amazon.com/AmazonCloudWatch/latest/logs/SubscriptionFilters.html
destinationArn: process.env.CLOUDWATCH_LOGS_DESTINATION_ARN,
// A name for the filter.
filterName: process.env.CLOUDWATCH_LOGS_FILTER_NAME,
// A filter pattern for subscribing to a filtered stream of log events.
// https://docs.aws.amazon.com/AmazonCloudWatch/latest/logs/FilterAndPatternSyntax.html
filterPattern: process.env.CLOUDWATCH_LOGS_FILTER_PATTERN,
// The name of the log group. Messages in this group matching the filter pattern
// will be sent to the destination ARN.
logGroupName: process.env.CLOUDWATCH_LOGS_LOG_GROUP,
});
try {
return await client.send(command);
} catch (err) {
console.error(err);
}
};
export default run();
```
+ API の詳細については、*AWS SDK for JavaScript API リファレンス*の「[PutSubscriptionFilter](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/client/cloudwatch-logs/command/PutSubscriptionFilterCommand)」を参照してください。
### `StartLiveTail`
次のコード例は、`StartLiveTail` を使用する方法を示しています。
**SDK for JavaScript (v3)**
必要なファイルを含めます。
```
import { CloudWatchLogsClient, StartLiveTailCommand } from "@aws-sdk/client-cloudwatch-logs";
```
Live Tail セッションのイベントを処理します。
```
async function handleResponseAsync(response) {
try {
for await (const event of response.responseStream) {
if (event.sessionStart !== undefined) {
console.log(event.sessionStart);
} else if (event.sessionUpdate !== undefined) {
for (const logEvent of event.sessionUpdate.sessionResults) {
const timestamp = logEvent.timestamp;
const date = new Date(timestamp);
console.log("[" + date + "] " + logEvent.message);
}
} else {
console.error("Unknown event type");
}
}
} catch (err) {
// On-stream exceptions are captured here
console.error(err)
}
}
```
Live Tail セッションを開始します。
```
const client = new CloudWatchLogsClient();
const command = new StartLiveTailCommand({
logGroupIdentifiers: logGroupIdentifiers,
logStreamNames: logStreamNames,
logEventFilterPattern: filterPattern
});
try{
const response = await client.send(command);
handleResponseAsync(response);
} catch (err){
// Pre-stream exceptions are captured here
console.log(err);
}
```
一定時間が経過したら Live Tail セッションを停止します。
```
/* Set a timeout to close the client. This will stop the Live Tail session. */
setTimeout(function() {
console.log("Client timeout");
client.destroy();
}, 10000);
```
+ API の詳細については、*AWS SDK for JavaScript API リファレンス*の「[StartLiveTail](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/client/cloudwatch-logs/command/StartLiveTailCommand)」を参照してください。
### `StartQuery`
次のコード例は、`StartQuery` を使用する方法を示しています。
**SDK for JavaScript (v3)**
GitHub には、その他のリソースもあります。用例一覧を検索し、[AWS コード例リポジトリ](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/javascriptv3/example_code/cloudwatch-logs#code-examples)での設定と実行の方法を確認してください。
```
/**
* Wrapper for the StartQueryCommand. Uses a static query string
* for consistency.
* @param {[Date, Date]} dateRange
* @param {number} maxLogs
* @returns {Promise<{ queryId: string }>}
*/
async _startQuery([startDate, endDate], maxLogs = 10000) {
try {
return await this.client.send(
new StartQueryCommand({
logGroupNames: this.logGroupNames,
queryString: "fields @timestamp, @message | sort @timestamp asc",
startTime: startDate.valueOf(),
endTime: endDate.valueOf(),
limit: maxLogs,
}),
);
} catch (err) {
/** @type {string} */
const message = err.message;
if (message.startsWith("Query's end date and time")) {
// This error indicates that the query's start or end date occur
// before the log group was created.
throw new DateOutOfBoundsError(message);
}
throw err;
}
}
```
+ API の詳細については、「**AWS SDK for JavaScript API リファレンス」の「[StartQuery](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/client/cloudwatch-logs/command/StartQueryCommand)」を参照してください。
## シナリオ
### 大規模なクエリを実行する
次のコード例は、CloudWatch Logs を使用して 10,000 を超えるレコードをクエリする方法を示しています。
**SDK for JavaScript (v3)**
GitHub には、その他のリソースもあります。用例一覧を検索し、[AWS コード例リポジトリ](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/javascriptv3/example_code/cloudwatch-logs/scenarios/large-query#code-examples)での設定と実行の方法を確認してください。
これはエントリポイントです。
```
// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
// SPDX-License-Identifier: Apache-2.0
import { CloudWatchLogsClient } from "@aws-sdk/client-cloudwatch-logs";
import { CloudWatchQuery } from "./cloud-watch-query.js";
console.log("Starting a recursive query...");
if (!process.env.QUERY_START_DATE || !process.env.QUERY_END_DATE) {
throw new Error(
"QUERY_START_DATE and QUERY_END_DATE environment variables are required.",
);
}
const cloudWatchQuery = new CloudWatchQuery(new CloudWatchLogsClient({}), {
logGroupNames: ["/workflows/cloudwatch-logs/large-query"],
dateRange: [
new Date(Number.parseInt(process.env.QUERY_START_DATE)),
new Date(Number.parseInt(process.env.QUERY_END_DATE)),
],
});
await cloudWatchQuery.run();
console.log(
`Queries finished in ${cloudWatchQuery.secondsElapsed} seconds.\nTotal logs found: ${cloudWatchQuery.results.length}`,
);
```
これは、必要に応じてクエリを複数のステップに分割するクラスです。
```
// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
// SPDX-License-Identifier: Apache-2.0
import {
StartQueryCommand,
GetQueryResultsCommand,
} from "@aws-sdk/client-cloudwatch-logs";
import { splitDateRange } from "@aws-doc-sdk-examples/lib/utils/util-date.js";
import { retry } from "@aws-doc-sdk-examples/lib/utils/util-timers.js";
class DateOutOfBoundsError extends Error {}
export class CloudWatchQuery {
/**
* Run a query for all CloudWatch Logs within a certain date range.
* CloudWatch logs return a max of 10,000 results. This class
* performs a binary search across all of the logs in the provided
* date range if a query returns the maximum number of results.
*
* @param {import('@aws-sdk/client-cloudwatch-logs').CloudWatchLogsClient} client
* @param {{ logGroupNames: string[], dateRange: [Date, Date], queryConfig: { limit: number } }} config
*/
constructor(client, { logGroupNames, dateRange, queryConfig }) {
this.client = client;
/**
* All log groups are queried.
*/
this.logGroupNames = logGroupNames;
/**
* The inclusive date range that is queried.
*/
this.dateRange = dateRange;
/**
* CloudWatch Logs never returns more than 10,000 logs.
*/
this.limit = queryConfig?.limit ?? 10000;
/**
* @type {import("@aws-sdk/client-cloudwatch-logs").ResultField[][]}
*/
this.results = [];
}
/**
* Run the query.
*/
async run() {
this.secondsElapsed = 0;
const start = new Date();
this.results = await this._largeQuery(this.dateRange);
const end = new Date();
this.secondsElapsed = (end - start) / 1000;
return this.results;
}
/**
* Recursively query for logs.
* @param {[Date, Date]} dateRange
* @returns {Promise}
*/
async _largeQuery(dateRange) {
const logs = await this._query(dateRange, this.limit);
console.log(
`Query date range: ${dateRange
.map((d) => d.toISOString())
.join(" to ")}. Found ${logs.length} logs.`,
);
if (logs.length < this.limit) {
return logs;
}
const lastLogDate = this._getLastLogDate(logs);
const offsetLastLogDate = new Date(lastLogDate);
offsetLastLogDate.setMilliseconds(lastLogDate.getMilliseconds() + 1);
const subDateRange = [offsetLastLogDate, dateRange[1]];
const [r1, r2] = splitDateRange(subDateRange);
const results = await Promise.all([
this._largeQuery(r1),
this._largeQuery(r2),
]);
return [logs, ...results].flat();
}
/**
* Find the most recent log in a list of logs.
* @param {import("@aws-sdk/client-cloudwatch-logs").ResultField[][]} logs
*/
_getLastLogDate(logs) {
const timestamps = logs
.map(
(log) =>
log.find((fieldMeta) => fieldMeta.field === "@timestamp")?.value,
)
.filter((t) => !!t)
.map((t) => `${t}Z`)
.sort();
if (!timestamps.length) {
throw new Error("No timestamp found in logs.");
}
return new Date(timestamps[timestamps.length - 1]);
}
/**
* Simple wrapper for the GetQueryResultsCommand.
* @param {string} queryId
*/
_getQueryResults(queryId) {
return this.client.send(new GetQueryResultsCommand({ queryId }));
}
/**
* Starts a query and waits for it to complete.
* @param {[Date, Date]} dateRange
* @param {number} maxLogs
*/
async _query(dateRange, maxLogs) {
try {
const { queryId } = await this._startQuery(dateRange, maxLogs);
const { results } = await this._waitUntilQueryDone(queryId);
return results ?? [];
} catch (err) {
/**
* This error is thrown when StartQuery returns an error indicating
* that the query's start or end date occur before the log group was
* created.
*/
if (err instanceof DateOutOfBoundsError) {
return [];
}
throw err;
}
}
/**
* Wrapper for the StartQueryCommand. Uses a static query string
* for consistency.
* @param {[Date, Date]} dateRange
* @param {number} maxLogs
* @returns {Promise<{ queryId: string }>}
*/
async _startQuery([startDate, endDate], maxLogs = 10000) {
try {
return await this.client.send(
new StartQueryCommand({
logGroupNames: this.logGroupNames,
queryString: "fields @timestamp, @message | sort @timestamp asc",
startTime: startDate.valueOf(),
endTime: endDate.valueOf(),
limit: maxLogs,
}),
);
} catch (err) {
/** @type {string} */
const message = err.message;
if (message.startsWith("Query's end date and time")) {
// This error indicates that the query's start or end date occur
// before the log group was created.
throw new DateOutOfBoundsError(message);
}
throw err;
}
}
/**
* Call GetQueryResultsCommand until the query is done.
* @param {string} queryId
*/
_waitUntilQueryDone(queryId) {
const getResults = async () => {
const results = await this._getQueryResults(queryId);
const queryDone = [
"Complete",
"Failed",
"Cancelled",
"Timeout",
"Unknown",
].includes(results.status);
return { queryDone, results };
};
return retry(
{ intervalInMs: 1000, maxRetries: 60, quiet: true },
async () => {
const { queryDone, results } = await getResults();
if (!queryDone) {
throw new Error("Query not done.");
}
return results;
},
);
}
}
```
+ API の詳細については、「AWS SDK for JavaScript API リファレンス**」の以下のトピックを参照してください。
+ [GetQueryResults](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/client/cloudwatch-logs/command/GetQueryResultsCommand)
+ [StartQuery](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/client/cloudwatch-logs/command/StartQueryCommand)
### スケジュールされたイベントを使用した Lambda 関数の呼び出し
次のコード例は、Amazon EventBridge スケジュールされたイベントによって呼び出される AWS Lambda 関数を作成する方法を示しています。
**SDK for JavaScript (v3)**
AWS Lambda 関数を呼び出す Amazon EventBridge スケジュールされたイベントを作成する方法を示します。cron 式を使用して Lambda 関数が呼び出されるタイミングをスケジュールするように EventBridge を設定します。この例では、Lambda JavaScript ランタイム API を使用して Lambda 関数を作成します。この例では、さまざまな AWS サービスを呼び出して、特定のユースケースを実行します。この例では、年間の記念日に従業員を祝福するモバイルテキストメッセージを従業員に送信するアプリを作成する方法を示します。
完全なソースコードとセットアップおよび実行の手順については、[GitHub](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/javascriptv3/example_code/cross-services/lambda-scheduled-events) で完全な例を参照してください。
この例は、[AWS SDK for JavaScript v3 デベロッパーガイド](https://docs.aws.amazon.com/sdk-for-javascript/v3/developer-guide/scheduled-events-invoking-lambda-example.html)でも使用できます。
**この例で使用されているサービス**
+ CloudWatch Logs
+ DynamoDB
+ EventBridge
+ Lambda
+ Amazon SNS