第 4 章 Reports

4.1. 关于报告

报告（Report）是一个 API 对象，提供了一种使用 SQL 查询来管理定期 ETL（Extract Transform and Load）任务的方法。这类报告通过使用其他 Metering 资源编制而成，资源包括提供要运行的实际 SQL 查询的 ReportQueries，以及定义 ReportQueries 和 Reports 可用数据的 ReportDataSources。

很多用例均可通过与 metering 一同安装的预定义 ReportQueries 和 ReporDataSources 解决，因此，除非您有未被预定义的用例，否则将不需要自行定义用例。

4.1.1. Reports

报告自定义资源用于管理报告的执行和状态。metering 会生成通过使用量数据源导出的报告，用于进一步分析和过滤。

一个报告资源即代表一个任务，该任务管理数据库表并根据时间表使用新信息来更新报告。报告通过 reporting-operator HTTP API 来公开表中数据。带有 spec.schedule 字段集的报告会始终运行，并跟踪所收集数据的时间段。这样可确保如果 metering 关闭或不可用，报告将从停止处开始回填数据。如果未设置时间表，则报告将在 reportingStart 和 reportingEnd 处指定的时间运行一次。报告默认会等待 ReportDataSources 完全导入报告周期内的所有数据。如果报告有时间表，则会等到当前处理周期内的数据导入完成后才会开始运行。

4.1.1.1. 有时间表的报告示例

以下报告示例将包含每个 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

4.1.1.2. 无时间表的报告示例（运行一次）

以下报告示例将包含 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"

4.1.1.3. 查询

ReportQuery 用于生成报告的名称。报告查询会控制报告的架构以及结果的处理方式。

query 为必填字段。

使用 oc CLI 获取可用 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 会被其他 ReportQueries 用于构建更为复杂的查询，而不该直接用于报告。

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

带有 pod- 前缀的查询与带有 namespace- 前缀的查询类似，区别在于前者通过 Pod 而非命名空间来聚合信息。这些查询包含 Pod 的命名空间和节点。

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

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

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

要获取完整字段列表，请使用 oc CLI 以 YAMl 格式获取 ReportQuery，并检查 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

4.1.1.4. 时间表

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
...

4.1.1.4.1. 周期

下面列出一些 schedule.period 有效值，同时还列出了给定周期内的可设置选项。

hourly
- minute
- second
daily
- hour
- minute
- second
weekly
- dayOfWeek
- hour
- minute
- second
monthly
- dayOfMonth
- hour
- minute
- second
cron
- expression

一般来说，hour、minute、second 字段控制报告在一天中的哪个时间运行，如果为按周或按月运行，则可使用 dayOfWeek/dayOfMonth 来控制报告在一周或一个月中的哪一天运行。

以上各个字段均设有有效值区间：

hour 为整数值，介于 0-23 之间。
minute 为整数值，介于 0-59 之间。
second 为整数值，介于 0-59 之间。
Dayofweek 为字符串值，应为一周中的某一天（需要拼写）。
dayOfMonth 为整数值，介于 1-31 之间。

对于 cron 周期，只要为正常 cron 表达式即有效：

表达式："*/5 * * * *"

4.1.1.5. reportingStart

要根据现有数据运行报告，可将 spec.reportingStart 字段设置为 RFC3339 时间戳，以告知报告根据其 schedule 从 reportingStart 而非当前时间开始运行。务必要了解，这会导致 reporting-operator 按照时间表在 reportingStart 时间和当前时间之间的各个间隔内连续运行多个查询。如果周期短于每日，且 reportingStart 在数月之前，则可能会进行数千次查询。如果不设置 reportingStart，则报告将在报告创建后的下一个完整 reportingPeriod 内运行。

例如，如果您已收集 2019 年 1 月 1 日的数据，且希望在报告中添加该数据，则可使用以下值创建报告：

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"

4.1.1.6. reportingEnd

要将报告配置为仅运行至指定时间，您可将 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"

4.1.1.7. runImmediately

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

注意

当将 runImmediately 设为 true 时，您必须设置 reportingEnd 和 reportingStart 值。

4.1.1.8. 输入

报告的 spec.inputs 字段可用于覆盖或设置 ReportQuery 的 spec.inputs 字段中定义的值。

这是一个“名称-值”对列表：

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

name 输入值必须存在于 ReportQuery 的 inputs 列表中。Value 输入值必须为正确的输入 type。

4.1.1.9. 汇总报告

报告数据存储在数据库中，与指标数据非常相似，因此可用于聚合或汇总报告。汇总报告的一个简单用例是将生成报告所需时间分散到更长时间内；无需通过每月报告来查询和添加整个月的所有数据，而是可以将任务分成每日报告，每份报告运行三十分之一的数据。

自定义汇总报告需要自定义报告查询。ReportQuery 模板处理器提供 reportTableName 功能，可通过报告的 metadata.name 获取必要表名称。

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

# Taken from pod-cpu.yaml
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 |}
...

# aggregated-report.yaml
spec:
  query: "namespace-cpu-usage"
  inputs:
  - name: "NamespaceCPUUsageReportName"
    value: "namespace-cpu-usage-hourly"

4.1.1.9.1. 报告状态

已调度报告的执行可通过其状态字段进行跟踪。报告准备过程中出现的任何错误均会记录在此处。

报告 status 字段目前包含两个字段：

conditions：是一个状况列表，每个状况均包含 type、status、reason 和 message 字段。状况中 type 字段的可能值包括 Running 和 Failure，表明已调度报告的当前状态。reason 字段揭示其 condition 处于当前状态的原因，status 值可为 true、false 或 unknown。message 字段提供一条人类可读信息，揭示该状况处于当前状态的原因。有关 reason 字段值的详细信息请见 pkg/apis/metering/v1/util/report_util.go。
lastReportTime：指定 Metering 最后一次收集数据的时间。