Menu Close

第 5 章 Reports

5.1. 关于报告

重要

Metering 是一个已弃用的功能。弃用的功能仍然包含在 OpenShift Container Platform 中,并将继续被支持。但是,这个功能会在以后的发行版本中被删除,且不建议在新的部署中使用。

有关 OpenShift Container Platform 中已弃用或删除的主要功能的最新列表,请参阅 OpenShift Container Platform 发行注记中已弃用和删除的功能部分。

Report 自定义资源提供了一种使用 SQL 查询来管理定期执行性能转换和 Load(ETL)作业的方法。报告由其他 metering 资源组成,如提供要运行的实际 SQL 查询的 ReportQuery 资源,以及定义 ReportQueryReport 资源可用数据的 ReportDataSource 资源。

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

5.1.1. Reports

Report 自定义资源用于管理报告的执行和状态。metering 会生成通过使用量数据源导出的报告,用于进一步分析和过滤。一个 Report 资源代表一个任务,该任务管理数据库表并根据时间表使用新信息来更新报告。报告通过 Reporting Operator HTTP API 来公开表中数据。

带有 spec.schedule 字段集的报告会始终运行,并跟踪所收集数据的时间段。这样可确保如果 metering 关闭或不可用,报告将从停止处开始回填数据。如果未设置调度,则报告将在 reportingStartreportingEnd 处指定的时间运行一次。报告默认会等待 ReportDataSource 资源完全导入报告周期内的所有数据。如果报告设置了调度,则会等到当前处理周期内的数据导入完成后才会开始运行。

5.1.1.1. 带有调度的报告示例

以下示例 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

5.1.1.2. 没有调度的报告示例(运行一次)

以下 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"

5.1.1.3. 查询

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

5.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
...
5.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 * * * *"

5.1.1.5. reportingStart

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

注意

spec.reportingStart 字段设置为指定时间会导致报告 Operator 在 reportingStart 时间和当前时间之间的调度中为每个间隔运行多个查询。如果周期短于每日,且 reportingStart 在数月之前,则可能会进行数千次查询。如果未设置 reportingStart,则报告将在报告创建后的下一个完整 reportingPeriod 内运行。

例如,如果您已收集 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"

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

5.1.1.7. 过期

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

注意

对于汇总报告,不建议设置 expiration 字段。如果报告由其他报告或报告查询依赖,则不会在保留周期结束时删除报告。您可以在 debug 级别查看 report-operator 日志,以了解与报告保留决定相关的时间输出。

例如,以下调度的报告会在报告的 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
1
expiration 可用的时间单位是 nsus(或 µs)、mssmh
注意

Report 对象的 expiration 保留周期不完全精确,它是按几分钟而不是几纳秒的来工作的。

5.1.1.8. runImmediately

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

注意

当将 runImmediately 设为 true 时,您必须设置 reportingEndreportingStart 值。

5.1.1.9. 输入

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

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

spec:
  inputs:
  - name: "NamespaceCPUUsageReportName" 1
    value: "namespace-cpu-usage-hourly" 2
1
name 输入值必须存在于 ReportQuery 的 inputs 列表中。
2
Value 输入值必须为正确的输入 type

5.1.1.10. 卷起(roll-up)报告

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

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

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

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 roll-up 报告示例

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

5.1.1.10.1. 报告状态

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

Report 对象的 status 字段目前包含两个字段:

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