# 使用 CloudWatch Metrics 监控管道
<a name="pipelines-metrics"></a>

CloudWatch 管道将指标发布给 `AWS/Observability Admin` 命名空间中的 Amazon CloudWatch。您可以使用这些指标来监控管道的运行状况、性能和数据流。

## 可用指标
<a name="available-metrics"></a>

下列各表列出了 CloudWatch 管道的可用指标。

**注意**  
仅当值不为零时，才会发出管道指标。

### 核心指标
<a name="core-metrics"></a>


| 指标 | 说明 | 维度 | 单位 | 
| --- | --- | --- | --- | 
| `PipelineBytesIn` | 进入管道的日志记录量（以未压缩字节为单位） | PipelineName | 字节 | 
| `PipelineBytesInByDataSource` | 包含来源/类型细分的传入数据量 | PipelineName、DataSource、DataType | 字节 | 
| `PipelineBytesOut` | 路由到目标的数据量 | PipelineName | 字节 | 
| `PipelineBytesOutByDataSource` | 包含来源/类型细分的传出数据量 | PipelineName、DataSource、DataType | 字节 | 
| `PipelineRecordsIn` | 进入管道的记录数量 | PipelineName | 计数 | 
| `PipelineRecordsInByDataSource` | 包含来源/类型细分的传入记录数量 | PipelineName、DataSource、DataType | 计数 | 
| `PipelineRecordsOut` | 退出管道的记录数量 | PipelineName | 计数 | 
| `PipelineRecordsOutByDataSource` | 包含来源/类型细分的传出记录数量 | PipelineName、DataSource、DataType | 计数 | 

### 错误和警告指标
<a name="error-warning-metrics"></a>


| 指标 | 说明 | 维度 | 单位 | 
| --- | --- | --- | --- | 
| `PipelineErrors` | 管道中的错误总数 | PipelineName | 计数 | 
| `PipelineErrorsByErrorType` | 按类型划分的详细错误计数 | PipelineName、ErrorSource、ErrorComponent、ErrorType | 计数 | 
| `PipelineWarnings` | 遇到的警告数量 | PipelineName | 计数 | 
| `PipelineWarningsByWarningType` | 按类型划分的详细警告 | PipelineName、WarningSource、WarningComponent、WarningType | 计数 | 
| `PipelineRecordsUnprocessed` | 无法处理的记录数量 | PipelineName、DataSource、DataType | 计数 | 
| `PipelineRecordsDropped` | 丢弃的记录数量（仅限第三方来源） | PipelineName、DataSource、DataType | 计数 | 

## Dimensions
<a name="dimensions"></a>

CloudWatch 管道指标使用以下维度：

**PipelineName**  
管道的名称

**DataSource**  
数据来源（AWS 服务名称或第三方来源）

**DataType**  
正在处理的数据类型

**ErrorSource**  
错误源（s3、aws.secrets、cloudwatch\$1logs）

**ErrorComponent**  
发生错误的组件（来源、接收器、扩展）

**ErrorType**  
遇到的错误类型

## 错误类型
<a name="error-types"></a>

以下错误类型在 `PipelineErrorsByErrorType` 中进行跟踪：

**`ACCESS_DENIED`**  
与权限相关的故障

**`ALL`**  
管道中所有错误的总计数

**`RESOURCE_NOT_FOUND`**  
指定的资源不存在

**`SOURCE_READ_FAILURE`**  
无法从来源读取

**`PARSE_FAILURE`**  
数据解析错误

**`PROCESSOR_ERRORS`**  
处理操作失败

**`PAYLOAD_SIZE_EXCEEDED`**  
超出数据大小限制

## 警告类型
<a name="warning-types"></a>

管道上可能会出现以下警告类型：

**`THROTTLED`**  
表示发送的数据量已超过现有速率限制，从而导致某些数据点或事件丢弃或延迟，以保护系统并确保稳定性。

## 查看 指标
<a name="viewing-metrics"></a>

您可以使用以下方法查看 CloudWatch 管道指标：

### 使用 CloudWatch 控制台
<a name="using-cloudwatch-console"></a>

1. 打开 CloudWatch 控制台：[https://console.aws.amazon.com/cloudwatch/](https://console.aws.amazon.com/cloudwatch/)

1. 在导航窗格中，选择**指标**

1. 选择 **AWS/可观测性管理员**命名空间

1. 选择要查看的指标维度

### 使用 AWS CLI
<a name="using-aws-cli"></a>

```
aws cloudwatch get-metric-statistics \
  --namespace "AWS/Observability Admin" \
  --metric-name "PipelineBytesIn" \
  --dimensions Name=PipelineName,Value=my-pipeline \
  --start-time "2025-10-29T00:00:00" \
  --end-time "2025-10-29T23:59:59" \
  --period 300 \
  --statistics Sum
```

## 创建警报
<a name="creating-alarms"></a>

您可以根据这些指标创建 CloudWatch 警报。下面是一个创建管道错误警报的示例：

```
aws cloudwatch put-metric-alarm \
  --alarm-name "HighPipelineErrors" \
  --alarm-description "Alert on high error rate" \
  --metric-name "PipelineErrors" \
  --namespace "AWS/Observability Admin" \
  --dimensions Name=PipelineName,Value=my-pipeline \
  --period 300 \
  --evaluation-periods 2 \
  --threshold 10 \
  --comparison-operator GreaterThanThreshold \
  --statistic Sum \
  --alarm-actions arn:aws:sns:region:account-id:topic-name
```

## CloudWatch 管道指标的最佳实践
<a name="best-practices"></a>

### 监控数据流
<a name="monitor-data-flow"></a>
+ 使用 `PipelineBytesIn` 和 `PipelineBytesOut` 跟踪数据量
+ 监控 `PipelineRecordsIn` 和 `PipelineRecordsOut` 跟踪记录计数
+ 注意吞吐量模式的意外变化

### 跟踪错误和警告
<a name="track-errors-warnings"></a>
+ 为 `PipelineErrors` 创建警报以快速检测问题
+ 使用 `PipelineErrorsByErrorType` 诊断特定问题
+ 监控 `PipelineWarnings` 以尽早发现潜在问题

### 配置适当的阈值
<a name="configure-thresholds"></a>
+ 根据您的预期数据模式设定阈值
+ 考虑数据量的正常变化
+ 设置警报阈值时需考虑高峰使用时段