第 4 章 Reports

4.1. 关于报告

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

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

4.1.1. Reports

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

一个报告资源即代表一个任务,该任务管理数据库表并根据时间表使用新信息来更新报告。报告通过 reporting-operator HTTP API 来公开表中数据。带有 spec.schedule 字段集的报告会始终运行,并跟踪所收集数据的时间段。这样可确保如果 metering 关闭或不可用,报告将从停止处开始回填数据。如果未设置时间表,则报告将在 reportingStartreportingEnd 处指定的时间运行一次。报告默认会等待 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 的值,还可通过 hourlydailyweeklymonthly 字段来微调报告运行时间。

例如:如果 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

一般来说,hourminutesecond 字段控制报告在一天中的哪个时间运行,如果为按周或按月运行,则可使用 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 时间戳,以告知报告根据其 schedulereportingStart 而非当前时间开始运行。务必要了解,这会导致 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 时,您必须设置 reportingEndreportingStart 值。

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:是一个状况列表,每个状况均包含 typestatusreasonmessage 字段。状况中 type 字段的可能值包括 RunningFailure,表明已调度报告的当前状态。reason 字段揭示其 condition 处于当前状态的原因,status 值可为 truefalseunknownmessage 字段提供一条人类可读信息,揭示该状况处于当前状态的原因。有关 reason 字段值的详细信息请见 pkg/apis/metering/v1/util/report_util.go
  • lastReportTime:指定 Metering 最后一次收集数据的时间。