第 5 章 Reports

以下示例 Report 对象包含每个 pod 的 CPU 请求信息，每小时运行一次，每次运行时均会添加最后几小时的数据。

apiVersion: metering.openshift.io/v1
kind: Report
metadata:
  name: pod-cpu-request-hourly
spec:
  query: "pod-cpu-request"
  reportingStart: "2019-07-01T00:00:00Z"
  schedule:
    period: "hourly"
    hourly:
      minute: 0
      second: 0

以下 Report 对象示例包含 7 月份所有 Pod 的 CPU 请求信息。完成后，便不会再运行。

apiVersion: metering.openshift.io/v1
kind: Report
metadata:
  name: pod-cpu-request-hourly
spec:
  query: "pod-cpu-request"
  reportingStart: "2019-07-01T00:00:00Z"
  reportingEnd: "2019-07-31T00:00:00Z"

query 字段命名用于生成报告的 ReportQuery 资源。报告查询会控制报告的架构以及结果的处理方式。

query 为必填字段。

使用以下命令列出可用的 ReportQuery 资源：

$ oc -n openshift-metering get reportqueries

NAME                                         AGE
cluster-cpu-capacity                         23m
cluster-cpu-capacity-raw                     23m
cluster-cpu-usage                            23m
cluster-cpu-usage-raw                        23m
cluster-cpu-utilization                      23m
cluster-memory-capacity                      23m
cluster-memory-capacity-raw                  23m
cluster-memory-usage                         23m
cluster-memory-usage-raw                     23m
cluster-memory-utilization                   23m
cluster-persistentvolumeclaim-request        23m
namespace-cpu-request                        23m
namespace-cpu-usage                          23m
namespace-cpu-utilization                    23m
namespace-memory-request                     23m
namespace-memory-usage                       23m
namespace-memory-utilization                 23m
namespace-persistentvolumeclaim-request      23m
namespace-persistentvolumeclaim-usage        23m
node-cpu-allocatable                         23m
node-cpu-allocatable-raw                     23m
node-cpu-capacity                            23m
node-cpu-capacity-raw                        23m
node-cpu-utilization                         23m
node-memory-allocatable                      23m
node-memory-allocatable-raw                  23m
node-memory-capacity                         23m
node-memory-capacity-raw                     23m
node-memory-utilization                      23m
persistentvolumeclaim-capacity               23m
persistentvolumeclaim-capacity-raw           23m
persistentvolumeclaim-phase-raw              23m
persistentvolumeclaim-request                23m
persistentvolumeclaim-request-raw            23m
persistentvolumeclaim-usage                  23m
persistentvolumeclaim-usage-raw              23m
persistentvolumeclaim-usage-with-phase-raw   23m
pod-cpu-request                              23m
pod-cpu-request-raw                          23m
pod-cpu-usage                                23m
pod-cpu-usage-raw                            23m
pod-memory-request                           23m
pod-memory-request-raw                       23m
pod-memory-usage                             23m
pod-memory-usage-raw                         23m

带有 -raw 后缀的报告查询会被其他 ReportQueries 用于构建更为复杂的查询，而不该直接用于报告。

带有namespace- 前缀的查询会按命名空间聚合 pod CPU 和内存请求，根据资源请求提供命名空间及其总体使用量列表。

带有pod- 前缀的查询与带有 namespace- 前缀的查询类似，但会根据 pod 而不是命名空间来聚合信息。这些查询包含 pod 的命名空间和节点。

带有 node- 前缀的查询会返回有关各个节点总可用资源的信息。

带有 aws- 前缀的查询为 AWS 特定查询。带有 -aws 后缀的查询返回的数据与无此后缀的同名查询返回的数据相同，并会将使用量与 EC2 计费数据相关联。

aws-ec2-billing-data 报告可供其他查询使用，但不应用作独立报告。aws-ec2-cluster-cost 报告根据集群中所含节点提供总成本，以及所报告时间段的成本总额。

使用以下命令将 ReportQuery 资源作为 YAML 获取，并检查 spec.columns 字段。例如，运行：

$ oc -n openshift-metering get reportqueries namespace-memory-request -o yaml

apiVersion: metering.openshift.io/v1
kind: ReportQuery
metadata:
  name: namespace-memory-request
  labels:
    operator-metering: "true"
spec:
  columns:
  - name: period_start
    type: timestamp
    unit: date
  - name: period_end
    type: timestamp
    unit: date
  - name: namespace
    type: varchar
    unit: kubernetes_namespace
  - name: pod_request_memory_byte_seconds
    type: double
    unit: byte_seconds

spec.schedule 配置块用于定义报告的运行时间。schedule 部分的主要字段为 period。根据 period 的值，还可通过 hourly、daily、weekly 和 monthly 字段来微调报告运行时间。

例如：如果 period 设置为 weekly，您则可将 weekly 字段添加至 spec.schedule 块中。以下示例中报告将于每周三下午 1 点 (13:00) 运行一次。

...
  schedule:
    period: "weekly"
    weekly:
      dayOfWeek: "wednesday"
      hour: 13
...

要根据现有数据运行报告，可将 spec.reportingStart 字段设置为 RFC3339 时间戳，以告知报告根据其 schedule 从 reportingStart 而非当前时间开始运行。

例如，如果您已收集 2019 年 1 月 1 日的数据，且希望在 Report 对象中包含这些数据，则可使用以下值创建报告：

apiVersion: metering.openshift.io/v1
kind: Report
metadata:
  name: pod-cpu-request-hourly
spec:
  query: "pod-cpu-request"
  schedule:
    period: "hourly"
  reportingStart: "2019-01-01T00:00:00Z"

要将报告配置为仅运行至指定时间，您可将 spec.reportingEnd 字段设置为 RFC3339 时间戳。此字段值将导致报告生成从开始时间至 reportingEnd 周期的数据报告后随即按时间表停止运行。

因为调度很可能与 reportingEnd 不一致，所以调度中的最后周期将被缩短至指定的 reportingEnd 时间。如果未设置，则报告将会一直运行，或直到报告设置了 reportingEnd。

例如，为 7 月创建每周运行一次的报告，使用以下命令：

apiVersion: metering.openshift.io/v1
kind: Report
metadata:
  name: pod-cpu-request-hourly
spec:
  query: "pod-cpu-request"
  schedule:
    period: "weekly"
  reportingStart: "2019-07-01T00:00:00Z"
  reportingEnd: "2019-07-31T00:00:00Z"

添加 expiration 字段，以在调度的 metering 报告上设置保留周期。您可以通过设置 expiration 持续时间值来避免手动删除报告。报告保留周期等于 Report 对象 creationDate 再加上 expiration 持续时间。如果没有其他报告或报告查询取决于报告过期，则报告会在保留周期结束时从集群中删除。从集群中删除报告可能需要几分钟。

例如，以下调度的报告会在报告的 creationDate 设置时间的 30 分钟后删除：

apiVersion: metering.openshift.io/v1
kind: Report
metadata:
  name: pod-cpu-request-hourly
spec:
  query: "pod-cpu-request"
  schedule:
    period: "weekly"
  reportingStart: "2020-09-01T00:00:00Z"
  expiration: "30m" 1

当 runImmediately 设置为 true时，报告将立即运行。这个行为可确保立即处理报告并将报告放入队列，而无需额外的调度参数。

Report 对象的 spec.inputs 字段可用于覆盖或设置 ReportQuery 资源的 spec.inputs 字段中定义的值。

spec.inputs 是一个名称值对列表：

spec:
  inputs:
  - name: "NamespaceCPUUsageReportName" 1
    value: "namespace-cpu-usage-hourly" 2

报告数据存储在数据库中，与指标数据非常相似，因此可用于聚合或汇总报告。卷起报告的一个简单用例是将生成报告所需时间分散到更长时间内。这与通过每月的报告来查询和添加整个月的所有数据。例如，任务可以被分成每日报告，每个报告大约有 1/30 的数据。

自定义汇总报告需要自定义报告查询。ReportQuery 资源模板处理器提供了一个 reportTableName 功能，它可从 Report 对象的 metadata.name 中获取必要表名称。

下面是内置查询中的一个片段：

spec:
...
  inputs:
  - name: ReportingStart
    type: time
  - name: ReportingEnd
    type: time
  - name: NamespaceCPUUsageReportName
    type: Report
  - name: PodCpuUsageRawDataSourceName
    type: ReportDataSource
    default: pod-cpu-usage-raw
...

  query: |
...
    {|- if .Report.Inputs.NamespaceCPUUsageReportName |}
      namespace,
      sum(pod_usage_cpu_core_seconds) as pod_usage_cpu_core_seconds
    FROM {| .Report.Inputs.NamespaceCPUUsageReportName | reportTableName |}
...

spec:
  query: "namespace-cpu-usage"
  inputs:
  - name: "NamespaceCPUUsageReportName"
    value: "namespace-cpu-usage-hourly"