[适用于 JavaScript 的 AWS SDK V3 API 参考指南](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/)详细描述了 适用于 JavaScript 的 AWS SDK 版本 3 (V3) 的所有 API 操作。
本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。
# CloudWatch 使用适用于 JavaScript (v3) 的 SDK 记录示例
以下代码示例向您展示了如何使用带 CloudWatch 日志的 适用于 JavaScript 的 AWS SDK (v3) 来执行操作和实现常见场景。
*操作*是大型程序的代码摘录，必须在上下文中运行。您可以通过操作了解如何调用单个服务函数，还可以通过函数相关场景的上下文查看操作。
*场景*是向您演示如何通过在一个服务中调用多个函数或与其他 AWS 服务结合来完成特定任务的代码示例。
每个示例都包含一个指向完整源代码的链接，您可以从中找到有关如何在上下文中设置和运行代码的说明。
**Topics**
+ [操作](#actions)
+ [场景](#scenarios)
## 操作
### `CreateLogGroup`
以下代码示例演示了如何使用 `CreateLogGroup`。
**适用于 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 的详细信息，请参阅 *适用于 JavaScript 的 AWS SDK API 参考[CreateLogGroup](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/client/cloudwatch-logs/command/CreateLogGroupCommand)*中的。
### `DeleteLogGroup`
以下代码示例演示了如何使用 `DeleteLogGroup`。
**适用于 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 的详细信息，请参阅 *适用于 JavaScript 的 AWS SDK API 参考[DeleteLogGroup](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/client/cloudwatch-logs/command/DeleteLogGroupCommand)*中的。
### `DeleteSubscriptionFilter`
以下代码示例演示了如何使用 `DeleteSubscriptionFilter`。
**适用于 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 的详细信息，请参阅 *适用于 JavaScript 的 AWS SDK API 参考[DeleteSubscriptionFilter](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/client/cloudwatch-logs/command/DeleteSubscriptionFilterCommand)*中的。
### `DescribeLogGroups`
以下代码示例演示了如何使用 `DescribeLogGroups`。
**适用于 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 的详细信息，请参阅 *适用于 JavaScript 的 AWS SDK API 参考[DescribeLogGroups](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/client/cloudwatch-logs/command/DescribeLogGroupsCommand)*中的。
### `DescribeSubscriptionFilters`
以下代码示例演示了如何使用 `DescribeSubscriptionFilters`。
**适用于 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 的详细信息，请参阅 *适用于 JavaScript 的 AWS SDK API 参考[DescribeSubscriptionFilters](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/client/cloudwatch-logs/command/DescribeSubscriptionFiltersCommand)*中的。
### `GetQueryResults`
以下代码示例演示了如何使用 `GetQueryResults`。
**适用于 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 的详细信息，请参阅 *适用于 JavaScript 的 AWS SDK API 参考[GetQueryResults](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/client/cloudwatch-logs/command/GetQueryResultsCommand)*中的。
### `PutSubscriptionFilter`
以下代码示例演示了如何使用 `PutSubscriptionFilter`。
**适用于 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 的详细信息，请参阅 *适用于 JavaScript 的 AWS SDK API 参考[PutSubscriptionFilter](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/client/cloudwatch-logs/command/PutSubscriptionFilterCommand)*中的。
### `StartLiveTail`
以下代码示例演示了如何使用 `StartLiveTail`。
**适用于 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 的详细信息，请参阅 *适用于 JavaScript 的 AWS SDK API 参考[StartLiveTail](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/client/cloudwatch-logs/command/StartLiveTailCommand)*中的。
### `StartQuery`
以下代码示例演示了如何使用 `StartQuery`。
**适用于 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 的详细信息，请参阅 *适用于 JavaScript 的 AWS SDK API 参考[StartQuery](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/client/cloudwatch-logs/command/StartQueryCommand)*中的。
## 场景
### 运行大型查询
以下代码示例展示了如何使用 CloudWatch 日志查询超过 10,000 条记录。
**适用于 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 详细信息，请参阅《适用于 JavaScript 的 AWS SDK API Reference》**中的以下主题。
+ [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 函数。
**适用于 JavaScript (v3) 的软件开发工具包**
演示如何创建调用函数的 Amazon EventBridge 计划事件。 AWS Lambda 配置 EventBridge 为使用 cron 表达式来调度 Lambda 函数的调用时间。在此示例中，您将使用 Lambda 运行时 API 创建一个 Lambda 函数。 JavaScript 此示例调用不同的 AWS 服务来执行特定的用例。此示例展示了如何创建一个应用程序，在其一周年纪念日时向员工发送移动短信表示祝贺。
有关如何设置和运行的完整源代码和说明，请参阅上的完整示例[GitHub](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/javascriptv3/example_code/cross-services/lambda-scheduled-events)。
该示例也可在 [适用于 JavaScript 的 AWS SDK v3 开发人员指南](https://docs.aws.amazon.com/sdk-for-javascript/v3/developer-guide/scheduled-events-invoking-lambda-example.html)中找到。
**本示例中使用的服务**
+ CloudWatch 日志
+ DynamoDB
+ EventBridge
+ Lambda
+ Amazon SNS