指标上报

从 1.1.0 版本起，Iceberg 支持 MetricsReporter 和 MetricsReport 这两个 API。通过这两个 API，可以表达不同类型的指标上报，并以可插拔的方式上报这些报告。

报告类型

ScanReport

ScanReport 承载的是针对给定表进行扫描规划期间收集的指标。除了一些关于涉及表的通用信息（如快照 ID 或表名）之外，它还包含如下指标：

扫描规划总耗时
结果中包含的数据/删除文件数量
已扫描/已跳过的数据/删除清单文件数量
已扫描/已跳过的数据/删除文件数量
已扫描的等值/位置删除文件数量

CommitReport

CommitReport 承载的是对表提交变更（即生成快照）之后收集的指标。除了一些关于涉及表的通用信息（如快照 ID 或表名）之外，它还包含如下指标：

总耗时
提交成功所需的尝试次数
新增/删除的数据/删除文件数量
新增/删除的等值/位置删除文件数量
新增/删除的等值/位置删除记录数量

可用的指标上报器

`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）来控制是否通过 REST 发送指标。

实现自定义指标报告器

实现 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;
  }
}

注册自定义 Metrics Reporter

通过 Catalog 配置

Catalog 属性 metrics-reporter-impl 允许通过指定 MetricsReporter 的全限定类名来注册它，例如 metrics-reporter-impl=org.apache.iceberg.metrics.InMemoryMetricsReporter。

通过扫描规划阶段的 Java API

除了通过 metrics-reporter-impl 属性在 Catalog 级别注册 MetricsReporter 之外，还可以在扫描规划阶段提供额外的 reporter，示例如下：

TableScan tableScan =
    table
        .newScan()
        .metricsReporter(customReporterOne)
        .metricsReporter(customReporterTwo);

try (CloseableIterable<FileScanTask> fileScanTasks = tableScan.planFiles()) {
  // ...
}

指标报告