# @aws-cdk/aws-logs 中文文档

规范地址：https://npmcn.com/package/%40aws-cdk/aws-logs/

版本：1\.204\.0
npm 元数据更新时间：2023-11-21T10:16:11.192Z
中文译文更新时间：2026-11-07T09:22:18.238Z
软件包许可：Apache-2\.0

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40aws-cdk/aws-logs
原文对照：https://npmcn.com/package/%40aws-cdk/aws-logs/?lang=original
项目主页：https://github.com/aws/aws-cdk
源码仓库：https://github.com/aws/aws-cdk

弃用说明：AWS CDK v1 has reached End-of-Support on 2023-06-01\. This package is no longer being updated, and users should migrate to AWS CDK v2\. For more information on how to migrate, see https://docs\.aws\.amazon\.com/cdk/v2/guide/migrating-v2\.html

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：965 kB，35 个文件
- 模块格式：CommonJS
- TypeScript 类型：包内自带
- Node.js 要求：\>= 14\.15\.0
- 运行依赖：7 个
- peer 依赖：@aws-cdk/aws-cloudwatch 1\.204\.0，@aws-cdk/aws-iam 1\.204\.0，@aws-cdk/aws-kms 1\.204\.0，@aws-cdk/aws-s3-assets 1\.204\.0，@aws-cdk/core 1\.204\.0，@aws-cdk/cx-api 1\.204\.0，constructs ^3\.3\.69
- 首次发布：2018-07-31T13:37:57.711Z
- 最新版本发布：2023-06-19T21:06:10.643Z
- 近 30 天下载量：374022（2026-10-08 至 2026-11-06，npm 官方下载统计）
- 已发布版本数：288（近 12 个月 0 个）

## 中文简介

AWS:Logs 的 CDK 构造库

## 安装

```sh
npm install @aws-cdk/aws-logs
```

也可以使用：`pnpm add @aws-cdk/aws-logs`、`yarn add @aws-cdk/aws-logs`、`bun add @aws-cdk/aws-logs`

## README

# 亚马逊云表日志构建库

* * *

![End-of-Support](https://img.shields.io/badge/End--of--Support-critical.svg?style=for-the-badge)

> AWS CDK v1在2023-06-01上达到了支持结束. 此软件包不再更新,用户应该迁移到 AWS CDK v2.
> 
> 关于如何移徙的更多信息,请参见: [_移动到 AWS CDK v2_ 指南](https://docs.aws.amazon.com/cdk/v2/guide/migrating-v2.html)。 。 。 .

* * *

该图书馆为与Cloud Watch Logs合作提供构件.

## 日志组/结构

"云表"的基本单位是 _日志组_每个日志组通常都有 以相同格式登录的同类数据。 如果有多个 程序或服务登录到日志组,每组创建一个新的 _日志流_。 。 。 .

每个日志操作都会创建一个“日志事件”,它可以由一个简单的字符串组成 或单行JSON对象. JSON物体的优势在于它们能承受 更多的过滤能力(见下文).

日志流的唯一可配置属性是保留期,即 配置日志流中的事件到期和到期后的时间 删除.

如果不提供,默认保留期为2年,但可设定为 中一个值 `RetentionDays` 用于配置不同 留存期(包括无限留存).

[保留示例](https://npmcn.com/package/%40aws-cdk/aws-logs/test/example.retention.lit.ts)

## 保留日志

这个 `LogRetention` 构造是控制在CDK外所创建的日志组的保留期的一种方法。 构造通常 用于由 AWS 服务创建的自动日志组,例如 [自动取款机 羊绒](https://docs.aws.amazon.com/lambda/latest/dg/monitoring-cloudwatchlogs.html)。 。 。 .

使用一个 [云阵自定义 资源](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-cfn-customresource.html) 如果日志组不存在,则预设该组,并设定指定的日志保留期(默认不会过期).

默认情况下,日志组将与堆栈在同一区域创建. 这个 `logGroupRegion` 属性可用于配置 其他区域的伐木组。 这通常在控制由全球服务自动创建的日志组的保留时有用 将其日志组发布到特定区域, 例如 AWS Chatbot 在其中创建日志组 `us-east-1`。 。 。 .

## 资源政策

CloudWatch资源政策允许其他AWS服务或IAM特等将日志事件放入日志组. 当 `addToResourcePolicy` 首次调用日志组 :

```ts
const logGroup = new logs.LogGroup(this, 'LogGroup');
logGroup.addToResourcePolicy(new iam.PolicyStatement({
    actions: ['logs:CreateLogStream', 'logs:PutLogEvents'],
    principals: [new iam.ServicePrincipal('es.amazonaws.com')],
    resources: [logGroup.logGroupArn],
}));
```

或更方便的,可以给予日志组写权限如下,得出与上例相同的结果.

```ts
const logGroup = new logs.LogGroup(this, 'LogGroup');
logGroup.grantWrite(new iam.ServicePrincipal('es.amazonaws.com'));
```

注意任何传递到资源策略的ARN或标定值会被转换为AWS账户ID. 这是因为Cloud Watchs日志资源政策不接受ARNs为主,但他们确实接受 账户标识字符串 。 非ARN校长,如服务校长或任何省长,均被Cloud Watch接受.

## 加密日志组

默认情况下,日志组数据总是在Cloud Watch日志中加密. 你有这个 选择使用 AWS KMS 客户主密钥加密日志组数据 您不想使用默认的 AWS 加密。 记住,如果你决定 加密日志组、 需要读取加密内容的任何服务或 IAM 身份 未来日志流需要相同的CMK来解密数据.

以下是使用KMS CMK创建加密日志组的简单例子.

```ts
import * as kms from '@aws-cdk/aws-kms';

new logs.LogGroup(this, 'LogGroup', {
  encryptionKey: new kms.Key(this, 'Key'),
});
```

关于AWS文档的更详细信息请参见: [加密云表 日志](https://docs.aws.amazon.com/AmazonCloudWatch/latest/logs/encrypt-log-data-kms.html)。 。 。 .

## 订阅和目的

匹配特定过滤器的日志事件可以发送到 Lambda 函数 或克尼西斯溪流.

如果Kinesis流生活在不同的账户中,a `CrossAccountDestination` 对象需要添加到将起到代理作用的目标账户 为偏僻的克尼斯溪. 此对象自动为您创建 如果您使用 CDK Kinesis 库.

创建一个 `SubscriptionFilter`,以适当的字母开头 `Pattern` (见 提供预定目的地:

```ts
import * as destinations from '@aws-cdk/aws-logs-destinations';
declare const fn: lambda.Function;
declare const logGroup: logs.LogGroup;

new logs.SubscriptionFilter(this, 'Subscription', {
  logGroup,
  destination: new destinations.LambdaDestination(fn),
  filterPattern: logs.FilterPattern.allTerms("ERROR", "MainThread"),
});
```

## 度量过滤器

Cloud Watch Logs可以根据文字日志流提取并释放出度量衡. 根据你的需求,这可能是一个更方便的方法 生成度量衡 而不是给自己打电话 给Cloud Watch Metrics.

A 类 `MetricFilter` 或者每次看到日志事件都会发出一个固定的号码 匹配特定模式(见下文),或从日志中提取数字 事件,并将它作为度量值.

示例

[测量过滤器示例](https://npmcn.com/package/%40aws-cdk/aws-logs/test/integ.metricfilter.lit.ts)

记住,如果你想使用日志事件的值作为度量值, 你必须在某个地方提到它.

一个非常简单的度量计可以通过使用 `logGroup.extractMetric()` 帮助函数 :

```ts
declare const logGroup: logs.LogGroup;
logGroup.extractMetric('$.jsonField', 'Namespace', 'MetricName');
```

将提取 `jsonField` 无论它发生在JSON构造 日志组中的日志记录,然后将其发送到 Cloud Watch Metrics 下 名称 `Namespace/MetricName`。 。 。 .

### 在计量过滤器上曝光计量

通过调用 `MetricFilter.metric()` API (英语). 这有一个默认 `statistic = 'avg'` 如果统计未设置在 `props`。 。 。 .

```ts
declare const logGroup: logs.LogGroup;
const mf = new logs.MetricFilter(this, 'MetricFilter', {
  logGroup,
  metricNamespace: 'MyApp',
  metricName: 'Latency',
  filterPattern: logs.FilterPattern.exists('$.latency'),
  metricValue: '$.latency',
});

//expose a metric from the metric filter
const metric = mf.metric();

//you can use the metric to create a new alarm
new cloudwatch.Alarm(this, 'alarm from metric filter', {
  metric,
  threshold: 100,
  evaluationPeriods: 2,
});
```

## 模式

模式描述哪些日志事件匹配一个订阅或度量过滤器. 那边 三种模式:

-   文本图案
-   JSON 图案
-   空格限制表模式

所有图案都是通过在 `FilterPattern` 课.

除上述规律外,还存在以下特有规律: 1

-   `FilterPattern.allEvents()`:匹配所有日志事件.
-   `FilterPattern.literal(string)`: 如果您已经知道什么模式表达式 ,此函数将使用字符串,并将将其作为日志模式。 对于 更多信息,参见 [过滤和图案 语法](https://docs.aws.amazon.com/AmazonCloudWatch/latest/logs/FilterAndPatternSyntax.html)。 。 。 .

### 文本图案

如果文字字符串出现在日志的文字形式中, 则文本模式匹配 线条.

-   `FilterPattern.allTerms(term, term, ...)`: 匹配所有给定条件 (子串)出现在日志事件.
-   `FilterPattern.anyTerm(term, term, ...)`: 匹配所有给定条件 (子串)出现在日志事件.
-   `FilterPattern.anyTermGroup([term, term, ...], [term, term, ...], ...)`: 匹配,如果 任意一组中的所有术语(指定为数组)匹配。 这是 一个OR匹配.

实例:

```ts
// Search for lines that contain both "ERROR" and "MainThread"
const pattern1 = logs.FilterPattern.allTerms('ERROR', 'MainThread');

// Search for lines that either contain both "ERROR" and "MainThread", or
// both "WARN" and "Deadlock".
const pattern2 = logs.FilterPattern.anyTermGroup(
  ['ERROR', 'MainThread'],
  ['WARN', 'Deadlock'],
);
```

## JSON 图案

JSON 模式适用于日志事件为对象的 JSON 表示 (没有其他字符,因此不能包括时间戳等前缀) 或日志级别)。 JSON 模式可以比较 字段.

-   **字符串**: 允许字符串的比较运算符是 `=` 财务报告和审定财务报表 `!=`。 。 。 . 字符串值可以开始或结束于 `*` 通关卡.
-   **数字**: 允许比较数字的运算符是: `=`, (中文(简体) ), `!=`, (中文(简体) ), `<`, (中文(简体) ), `<=`, (中文(简体) ), `>`, (中文(简体) ), `>=`。 。 。 .

JSON结构中的字段通过标识符识别出完整的对象为 `$` 然后坠入其中 `$.field` 或者说 `$.list[0].field`。 。 。 .

-   `FilterPattern.stringValue(field, comparison, string)`: 如果给定的话匹配 字段与给定的字符串值进行比较.
-   `FilterPattern.numberValue(field, comparison, number)`: 如果给定的话匹配 字段与给定的数字值进行比较.
-   `FilterPattern.isNull(field)`: 如果给定字段存在且有 价值 `null`。 。 。 .
-   `FilterPattern.notExists(field)`: 如果指定字段不在 JSON 中, 匹配 结构.
-   `FilterPattern.exists(field)`: 如果给定的字段在 JSON 中匹配 结构.
-   `FilterPattern.booleanValue(field, boolean)`: 如果给定字段匹配 正是给定的布尔值.
-   `FilterPattern.all(jsonPattern, jsonPattern, ...)`: 如果全部匹配 给JSON模式匹配。 这使得给定和组合 模式.
-   `FilterPattern.any(jsonPattern, jsonPattern, ...)`: 匹配(如果有的话) 给JSON模式匹配。 这使得给定的 OR 组合 模式.

示例

```ts
// Search for all events where the component field is equal to
// "HttpServer" and either error is true or the latency is higher
// than 1000.
const pattern = logs.FilterPattern.all(
  logs.FilterPattern.stringValue('$.component', '=', 'HttpServer'),
  logs.FilterPattern.any(
    logs.FilterPattern.booleanValue('$.error', true),
    logs.FilterPattern.numberValue('$.latency', '>', 1000),
  ),
);
```

## 空格限制表模式

如果日志事件是空格限制表格的行,则可以使用此模式 确定该结构中的栏并增加其中任何一栏的条件。 这个 您将应用此类型模式的学说实例是 Apache 服务器 木头.

由 `"..."` 引用或 `[...]` 方括号将 作为一栏处理.

-   `FilterPattern.spaceDelimited(column, column, ...)`: 构造一个 `SpaceDelimitedTextPattern` 对象与指定的列。 栏目 逐一绘制日志事件中发现的列。 字符串 `"..."` 可能 用于指定任意数量的无名列 名称列表(但只能指定一次).

建造后 `SpaceDelimitedTextPattern`时,您可以使用以下 增加限制的两名成员:

-   `pattern.whereString(field, comparison, string)`: 添加字符串条件. 规则与JSON模式相同.
-   `pattern.whereNumber(field, comparison, number)`: 添加一个数字条件. 规则与JSON模式相同.

在同一栏目中可以增加多种限制,必须全部适用.

示例

```ts
// Search for all events where the component is "HttpServer" and the
// result code is not equal to 200.
const pattern = logs.FilterPattern.spaceDelimited('time', 'component', '...', 'result_code', 'latency')
  .whereString('component', '=', 'HttpServer')
  .whereNumber('result_code', '!=', 200);
```

## 日志 透视查询定义

为 Cloud Watch Logs Insights 创建查询定义.

示例

```ts
new logs.QueryDefinition(this, 'QueryDefinition', {
  queryDefinitionName: 'MyQuery',
  queryString: new logs.QueryString({
    fields: ['@timestamp', '@message'],
    sort: '@timestamp desc',
    limit: 20,
  }),
});
```

## 页:1

注意日志组 ARN 总是有字符串 `:*` 附 录 他们,以匹配的行为 [云阵 `AWS::Logs::LogGroup` 资源](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-logs-loggroup.html#aws-resource-logs-loggroup-return-values)。 。 。 .

## 常见问题

### @aws-cdk/aws-logs 是什么？

AWS:Logs 的 CDK 构造库注意：该包已被作者标记为弃用——AWS CDK v1 has reached End-of-Support on 2023-06-01\. This package is no longer being updated, and users should migrate to AWS CDK v2\. For more information on how to migrate, see https://docs\.aws\.amazon\.com/cdk/v2/guide/migrating-v2\.html

### 如何安装 @aws-cdk/aws-logs？

在项目目录运行 npm install @aws-cdk/aws-logs，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：@aws-cdk/aws-cloudwatch（1\.204\.0）、@aws-cdk/aws-iam（1\.204\.0）、@aws-cdk/aws-kms（1\.204\.0）、@aws-cdk/aws-s3-assets（1\.204\.0）、@aws-cdk/core（1\.204\.0）、@aws-cdk/cx-api（1\.204\.0）、constructs（^3\.3\.69）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @aws-cdk/aws-logs 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @aws-cdk/aws-logs 支持 ESM 还是 CommonJS？

以 CommonJS 形式发布，可以直接 require\(\)；在 ES Module 项目中也可以用 import 引入（Node\.js 会把 module\.exports 作为默认导出）。

### @aws-cdk/aws-logs 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>= 14\.15\.0。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @aws-cdk/aws-logs 可以商用吗？

@aws-cdk/aws-logs 使用 Apache-2\.0 许可。宽松许可：允许商业使用、修改和再分发，并附带明确的专利授权；分发时需保留许可与 NOTICE 文件，修改过的文件要注明改动。以上为概括，不构成法律意见，请以许可原文为准。

### @aws-cdk/aws-logs 的下载量有多少？

根据 npm 官方下载统计，@aws-cdk/aws-logs 在 2026/10/08 – 2026/11/06 这 30 天内被下载 374,022 次，日均约 12,467 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @aws-cdk/aws-logs 还在维护吗？

最新版本 1\.204\.0 发布于 2023/06/20（3 年前）；至今共发布 288 个版本，其中过去 12 个月发布了 0 个；首次发布于 2018/07/31。作者已将其标记为弃用，新项目建议寻找替代方案。