第 5 章 Reports
5.1. 关于报告
Metering 是一个已弃用的功能。弃用的功能仍然包含在 OpenShift Container Platform 中,并将继续被支持。但是,这个功能会在以后的发行版本中被删除,且不建议在新的部署中使用。
有关 OpenShift Container Platform 中已弃用或删除的主要功能的最新列表,请参阅 OpenShift Container Platform 发行注记中已弃用和删除的功能部分。
Report
自定义资源提供了一种使用 SQL 查询来管理定期执行性能转换和 Load(ETL)作业的方法。报告由其他 metering 资源组成,如提供要运行的实际 SQL 查询的 ReportQuery
资源,以及定义 ReportQuery
和 Report
资源可用数据的 ReportDataSource
资源。
很多用例均可通过与 metering 一同安装的预定义 ReportQuery
和 ReportDataSource
资源解决。因此,除非您有未被这些预定义资源覆盖的用例,否则不需要自行定义您的定义。
5.1.1. Reports
Report
自定义资源用于管理报告的执行和状态。metering 会生成通过使用量数据源导出的报告,用于进一步分析和过滤。一个 Report
资源代表一个任务,该任务管理数据库表并根据时间表使用新信息来更新报告。报告通过 Reporting Operator HTTP API 来公开表中数据。
带有 spec.schedule
字段集的报告会始终运行,并跟踪所收集数据的时间段。这样可确保如果 metering 关闭或不可用,报告将从停止处开始回填数据。如果未设置调度,则报告将在 reportingStart
和 reportingEnd
处指定的时间运行一次。报告默认会等待 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
的值,还可通过 hourly
、daily
、weekly
和 monthly
字段来微调报告运行时间。
例如:如果 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
-
一般来说,hour
、minute
、second
字段控制报告在一天中的哪个时间运行,如果为按周或按月运行,则可使用 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 时间戳,以告知报告根据其 schedule
从 reportingStart
而非当前时间开始运行。
将 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
可用的时间单位是ns
、us
(或µs
)、ms
、s
、m
和h
。
Report
对象的 expiration
保留周期不完全精确,它是按几分钟而不是几纳秒的来工作的。
5.1.1.8. runImmediately
当 runImmediately
设置为 true
时,报告将立即运行。这个行为可确保立即处理报告并将报告放入队列,而无需额外的调度参数。
当将 runImmediately
设为 true
时,您必须设置 reportingEnd
和 reportingStart
值。
5.1.1.9. 输入
Report
对象的 spec.inputs
字段可用于覆盖或设置 ReportQuery
资源的 spec.inputs
字段中定义的值。
spec.inputs
是一个名称值对列表:
spec: inputs: - name: "NamespaceCPUUsageReportName" 1 value: "namespace-cpu-usage-hourly" 2
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
:是一个状况列表,每个状况均包含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 最后一次收集数据的时间。