메트릭 보고
메트릭 보고 (Metrics Reporting)
1.1.0 버전부터 아이스버그는 MetricsReporter와 MetricsReport API를 지원해요. 이 문서에서는 아이스버그가 수집하는 스캔·커밋 메트릭의 종류와, 이를 다양한 대상으로 보낼 수 있는 확장 가능한 보고 방식에 대해 알려드릴게요. 기본 제공되는 보고자와 커스텀 보고자를 만드는 방법까지 차례로 살펴볼게요.
출처: 문서
본문
1.1.0 버전부터 아이스버그는 MetricsReporter와 MetricsReport API를 지원해요. 이 두 API는 다양한 메트릭 보고서를 표현하면서, 이 보고서들을 보내는 플러그형(pluggable) 방식을 지원해요.
보고서의 종류 (Type of Reports)
ScanReport
ScanReport는 특정 테이블에 대한 스캔 계획 중에 수집된 메트릭을 담아요. 스냅샷 ID나 테이블 이름 같은 관련 테이블의 일반 정보와 함께 다음 메트릭을 포함해요.
- 총 스캔 계획 지속 시간
- 결과에 포함된 데이터/삭제 파일의 수
- 스캔/건너뛴 데이터/삭제 매니페스트의 수
- 스캔/건너뛴 데이터/삭제 파일의 수
- 스캔된 equality/positional 삭제 파일의 수
CommitReport
CommitReport는 테이블에 변경을 커밋한 후(즉 스냅샷을 만든 후) 수집된 메트릭을 담아요. 스냅샷 ID나 테이블 이름 같은 관련 테이블의 일반 정보와 함께 다음 메트릭을 포함해요.
- 총 지속 시간
- 커밋이 성공하는 데 필요한 시도 횟수
- 추가/제거된 데이터/삭제 파일의 수
- 추가/제거된 equality/positional 삭제 파일의 수
- 추가/제거된 equality/positional 삭제의 수
사용 가능한 메트릭 보고자 (Available Metrics Reporters)
LoggingMetricsReporter
이것은 다른 어떤 것도 구성되지 않았을 때의 기본 메트릭 보고자이고, 그 목적은 결과를 로그 파일에 로깅하는 것이에요. 예시 출력은 아래와 같아요.
INFO org.apache.iceberg.metrics.LoggingMetricsReporter - Received metrics report:
ScanReport{
tableName=scan-planning-with-eq-and-pos-delete-files,
snapshotId=2,
filter=ref(name="data") == "(hash-27fa7cc0)",
schemaId=0,
projectedFieldIds=[1, 2],
projectedFieldNames=[id, data],
scanMetrics=ScanMetricsResult{
totalPlanningDuration=TimerResult{timeUnit=NANOSECONDS, totalDuration=PT0.026569404S, count=1},
resultDataFiles=CounterResult{unit=COUNT, value=1},
resultDeleteFiles=CounterResult{unit=COUNT, value=2},
totalDataManifests=CounterResult{unit=COUNT, value=1},
totalDeleteManifests=CounterResult{unit=COUNT, value=1},
scannedDataManifests=CounterResult{unit=COUNT, value=1},
skippedDataManifests=CounterResult{unit=COUNT, value=0},
totalFileSizeInBytes=CounterResult{unit=BYTES, value=10},
totalDeleteFileSizeInBytes=CounterResult{unit=BYTES, value=20},
skippedDataFiles=CounterResult{unit=COUNT, value=0},
skippedDeleteFiles=CounterResult{unit=COUNT, value=0},
scannedDeleteManifests=CounterResult{unit=COUNT, value=1},
skippedDeleteManifests=CounterResult{unit=COUNT, value=0},
indexedDeleteFiles=CounterResult{unit=COUNT, value=2},
equalityDeleteFiles=CounterResult{unit=COUNT, value=1},
positionalDeleteFiles=CounterResult{unit=COUNT, value=1}},
metadata={
iceberg-version=Apache Iceberg 1.4.0-SNAPSHOT (commit 4868d2823004c8c256a50ea7c25cff94314cc135)}}
INFO org.apache.iceberg.metrics.LoggingMetricsReporter - Received metrics report:
CommitReport{
tableName=scan-planning-with-eq-and-pos-delete-files,
snapshotId=1,
sequenceNumber=1,
operation=append,
commitMetrics=CommitMetricsResult{
totalDuration=TimerResult{timeUnit=NANOSECONDS, totalDuration=PT0.098429626S, count=1},
attempts=CounterResult{unit=COUNT, value=1},
addedDataFiles=CounterResult{unit=COUNT, value=1},
removedDataFiles=null,
totalDataFiles=CounterResult{unit=COUNT, value=1},
addedDeleteFiles=null,
addedEqualityDeleteFiles=null,
addedPositionalDeleteFiles=null,
removedDeleteFiles=null,
removedEqualityDeleteFiles=null,
removedPositionalDeleteFiles=null,
totalDeleteFiles=CounterResult{unit=COUNT, value=0},
addedRecords=CounterResult{unit=COUNT, value=1},
removedRecords=null,
totalRecords=CounterResult{unit=COUNT, value=1},
addedFilesSizeInBytes=CounterResult{unit=BYTES, value=10},
removedFilesSizeInBytes=null,
totalFilesSizeInBytes=CounterResult{unit=BYTES, value=10},
addedPositionalDeletes=null,
removedPositionalDeletes=null,
totalPositionalDeletes=CounterResult{unit=COUNT, value=0},
addedEqualityDeletes=null,
removedEqualityDeletes=null,
totalEqualityDeletes=CounterResult{unit=COUNT, value=0}},
metadata={
iceberg-version=Apache Iceberg 1.4.0-SNAPSHOT (commit 4868d2823004c8c256a50ea7c25cff94314cc135)}}
RESTMetricsReporter
이것은 RESTCatalog를 사용할 때의 기본 보고자이고, 그 목적은 REST OpenAPI 스펙에 정의된 대로 /v1/{prefix}/namespaces/{namespace}/tables/{table}/metrics 엔드포인트로 메트릭을 보내는 것이에요.
REST를 통한 메트릭 전송은 rest-metrics-reporting-enabled (기본값은 true) 속성으로 제어할 수 있어요.
커스텀 메트릭 보고자 구현 (Implementing a custom Metrics Reporter)
MetricsReporter API를 구현하면 들어오는 MetricsReport 인스턴스를 처리하는 데 완전한 유연성을 얻을 수 있어요. 예를 들어 결과를 Prometheus 엔드포인트나 다른 관측성 프레임워크/시스템으로 보낼 수 있어요.
아래는 보고서를 리스트에 저장하고 사용할 수 있게 만드는 InMemoryMetricsReporter를 보여주는 짧은 예시예요:
public class InMemoryMetricsReporter implements MetricsReporter {
private List<MetricsReport> metricsReports = Lists.newArrayList();
@Override
public void report(MetricsReport report) {
metricsReports.add(report);
}
public List<MetricsReport> reports() {
return metricsReports;
}
}
커스텀 메트릭 보고자 등록 (Registering a custom Metrics Reporter)
카탈로그 구성을 통한 등록 (Via Catalog Configuration)
카탈로그 속성 metrics-reporter-impl을 사용하면 완전한 클래스 이름을 지정해서 특정 MetricsReporter를 등록할 수 있어요. 예: metrics-reporter-impl=org.apache.iceberg.metrics.InMemoryMetricsReporter.
스캔 계획 중 자바 API를 통한 등록 (Via the Java API during Scan planning)
metrics-reporter-impl 속성으로 카탈로그 수준에서 MetricsReporter를 등록하는 것과는 별개로, 아래처럼 스캔 계획 중에 추가 보고자를 제공할 수도 있어요.
TableScan tableScan =
table
.newScan()
.metricsReporter(customReporterOne)
.metricsReporter(customReporterTwo);
try (CloseableIterable<FileScanTask> fileScanTasks = tableScan.planFiles()) {
// ...
}