# CloudWatch 지표를 사용하여 파이프라인 모니터링
CloudWatch 파이프라인은 `AWS/Observability Admin` 네임스페이스의 Amazon CloudWatch에 지표를 게시합니다. 이러한 지표를 사용하여 파이프라인의 상태, 성능, 데이터 흐름을 모니터링할 수 있습니다.
## 사용 가능한 지표
아래 표에는 CloudWatch 파이프라인에서 사용 가능한 지표가 나와 있습니다.
**참고**
파이프라인 지표는 값이 0이 아닌 경우에만 출력됩니다.
### 주요 지표
| 지표 | 설명 | 측정 기준 | 단위 |
| --- | --- | --- | --- |
| `PipelineBytesIn` | 압축되지 않은 바이트 단위로 파이프라인에 전송되는 로그 레코드의 볼륨 | PipelineName | 바이트 |
| `PipelineBytesInByDataSource` | 소스/유형 분석이 포함된 수신 데이터의 볼륨 | PipelineName, DataSource, DataType | 바이트 |
| `PipelineBytesOut` | 대상으로 라우팅된 데이터의 볼륨 | PipelineName | 바이트 |
| `PipelineBytesOutByDataSource` | 소스/유형 분석이 포함된 발신 데이터의 볼륨 | PipelineName, DataSource, DataType | 바이트 |
| `PipelineRecordsIn` | 파이프라인으로 유입되는 레코드 수 | PipelineName | 개수 |
| `PipelineRecordsInByDataSource` | 소스/유형 분석이 포함된 수신 레코드 수 | PipelineName, DataSource, DataType | 개수 |
| `PipelineRecordsOut` | 파이프라인에서 나가는 레코드 수 | PipelineName | 개수 |
| `PipelineRecordsOutByDataSource` | 소스/유형 분석이 포함된 발신 레코드 수 | PipelineName, DataSource, DataType | 개수 |
### 오류 및 경고 지표
| 지표 | 설명 | 측정 기준 | 단위 |
| --- | --- | --- | --- |
| `PipelineErrors` | 파이프라인에서 발생한 오류 수 합계 | PipelineName | 개수 |
| `PipelineErrorsByErrorType` | 유형별 상세 오류 수 | PipelineName, ErrorSource, ErrorComponent, ErrorType | 개수 |
| `PipelineWarnings` | 발생한 경고 수 | PipelineName | 개수 |
| `PipelineWarningsByWarningType` | 유형별 상세 경고 | PipelineName, WarningSource, WarningComponent, WarningType | 개수 |
| `PipelineRecordsUnprocessed` | 처리하지 못한 레코드 수 | PipelineName, DataSource, DataType | 개수 |
| `PipelineRecordsDropped` | 삭제된 레코드 수(서드 파티 소스만 해당) | PipelineName, DataSource, DataType | 개수 |
## 측정 기준
CloudWatch 파이프라인 지표는 다음과 같은 차원을 사용합니다.
**PipelineName**
파이프라인의 이름
**DataSource**
데이터의 소스(AWS 서비스 이름 또는 서드 파티 소스)
**데이터 유형**
처리 중인 데이터의 유형
**ErrorSource**
오류의 오리진(s3, aws.secrets, cloudwatch\$1logs)
**ErrorComponent**
오류가 발생한 구성 요소(소스, 싱크, 확장)
**ErrorType**
발생한 오류 유형
## 오류 유형
`PipelineErrorsByErrorType`에서 추적되는 오류 유형은 다음과 같습니다.
**`ACCESS_DENIED`**
권한 관련 실패
**`ALL`**
파이프라인에서 발생한 모든 오류의 총 수
**`RESOURCE_NOT_FOUND`**
지정된 리소스가 존재하지 않음
**`SOURCE_READ_FAILURE`**
소스에서 읽기 실패
**`PARSE_FAILURE`**
데이터 구문 분석 오류
**`PROCESSOR_ERRORS`**
처리 작업 실패
**`PAYLOAD_SIZE_EXCEEDED`**
데이터 크기 제한 초과
## 경고 유형
파이프라인에서 다음과 같은 경고 유형이 발생할 수 있습니다.
**`THROTTLED`**
전송 중인 데이터 볼륨이 기존 속도 제한을 초과하였으므로, 시스템을 보호하고 안정성을 보장하기 위해 일부 데이터 포인트 또는 이벤트가 삭제되거나 지연된다는 뜻입니다.
## 지표 보기
다음과 같은 방법을 사용하여 CloudWatch 파이프라인 지표를 볼 수 있습니다.
### CloudWatch 콘솔 사용
1. [https://console.aws.amazon.com/cloudwatch/](https://console.aws.amazon.com/cloudwatch/)에서 CloudWatch 콘솔을 엽니다.
1. 탐색 창에서 **지표**를 선택합니다.
1. **AWS/Observability Admin** 네임스페이스를 선택합니다.
1. 열람하려는 지표 차원을 선택합니다.
### AWS CLI 사용
```
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
```
## 경보 생성
이러한 지표를 기반으로 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 파이프라인 지표에 대한 모범 사례
### 데이터 흐름 모니터링
+ `PipelineBytesIn` 및 `PipelineBytesOut`을 사용하여 데이터 볼륨 추적
+ `PipelineRecordsIn` 및 `PipelineRecordsOut`을 모니터링하여 레코드 수 추적
+ 처리량 패턴의 예기치 않은 변동 사항 감시
### 오류 및 경고 추적
+ `PipelineErrors`에 대한 경보를 생성하여 문제를 신속하게 감지
+ `PipelineErrorsByErrorType`을 사용하여 특정 문제 진단
+ `PipelineWarnings`를 모니터링하여 잠재적 문제를 조기에 식별
### 알맞은 임곗값 구성
+ 예상 데이터 패턴에 대한 기본 임곗값
+ 데이터 볼륨의 정상적인 변동치 고려
+ 경보 임곗값 설정 시 피크 사용 기간 고려