第4章 Report
4.1. Report について
Report は、SQL クエリーを使用して定期的な ETL (Extract Transform および Load) ジョブを管理する方法を提供する API オブジェクトです。これらは、実行する実際の SQL クエリーを提供する ReportQueries や、ReportQuery および Report で利用できるデータを定義する ReportDataSources などの他のメータリングリソースを使用して構成されます。
多くのユースケースは、メータリングと共にインストールされる事前定義の ReportQueries および ReportDataSources によって追加設定なしで対応されるため、事前定義されている内容で対応できないユースケースでない限り、独自の定義は不要になります。
4.1.1. Report
Report カスタムリソースは、レポートの実行およびステータスを管理するために使用されます。メータリングは、使用状況のデータソースから派生するレポートを生成します。これは、詳細な分析およびフィルターで使用できます。
単一 Report リソースは、データベーステーブルを管理するジョブを示し、これをスケジュールに応じて新しい情報で更新します。Report は、テーブルのデータを reporting-operator HTTP API 経由で公開します。spec.schedule フィールドが設定された Report は常に実行された状態となり、データの収集期間を追跡します。メータリングが長期間シャットダウンするか、または使用できない状態になる場合、データの停止時点からデータをバックフィルします。スケジュールが設定されていない場合、Report は reportingStart および reportingEnd で指定された期間に 1 回実行されます。デフォルトで、Report は ReportDataSource がレポート期間内のデータを完全にインポートするのを待機します。Report にスケジュールがある場合、現在処理されている期間内のデータのインポートがすべて完了するまで待機します。
4.1.1.1. スケジュールが設定された Report の例
以下のサンプル Report にはすべての Pod の CPU 要求についての情報が含まれ、1 時間に 1 回実行され、Report が実行されるごとにその 1 時間前からの関連データが追加されます。
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: 04.1.1.2. スケジュールなしのサンプル Report (1 回のみ実行)
以下のサンプル 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"
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 サフィックスのある ReportQuery は、より複雑なクエリーを作成するために他の ReportQuery によって使用されます。これらはレポートに直接使用できません。
namespace- のプレフィックスが付けられたクエリーは namespace 別に Pod CPU/メモリー要求を集計し、リソース要求に基づいて namespace およびそれらの全体の使用状況の一覧を提供します。
pod- のプレフィックスが付けられたクエリーは namespace- のプレフィックスが付けられたクエリーと同様ですが、情報を namespace 別ではなく Pod 別に集計します。これらのクエリーには、Pod の namespace およびノードが含まれます。
node- のプレフィックスが付けられたクエリーは各ノードの利用可能な合計リソースについての情報を返します。
aws- のプレフィックスが付けられたクエリーは AWS に固有のものです。aws のサフィックスが付けられたクエリーは、サフィックスなしの同じ名前のクエリーと同じデータを返し、使用状況を EC2 請求データに関連付けます。
aws-ec2-billing-data レポートは他のクエリーによって使用され、スタンドアロンのレポートとしては使用できません。aws-ec2-cluster-cost レポートは、クラスターに含まれるノードに基づく総コストと、レポート期間のコストの合計を提供します。
フィールドの詳細の一覧については、oc CLI を使用して 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_seconds4.1.1.4. スケジュール
spec.schedule 設定ブロックは、レポートが実行される時を定義します。schedule セクションの主なフィールドは period であり、period の値によって、hourly、daily、weekly、および monthly フィールドでレポートが実行されるタイミングをさらに調整できます。
たとえば、period が weekly に設定されている場合、weekly フィールドを spec.schedule ブロックに追加できます。以下の例は、週ごとに毎週水曜日の 1 pm (hour 13) に実行されます。
...
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 フィールドは 1 日のどの時間にレポートが実行されるかを制御し、dayOfWeek/dayOfMonth は、レポートの期間が週または月ごとに区切られている場合にレポートが実行される曜日または日を制御します。
上記の各フィールドには、有効な値の範囲があります。
-
hourは 0-23 の整数値です。 -
minuteは 0-59 の整数値です。 -
secondは 0-59 の整数値です。 -
dayOfWeekは曜日が入ることが予想される文字列の値です (略さずに入力します)。 -
dayOfMonthは 1-31 の整数値です。
cron 期間については、通常の cron 式は有効です。
-
expression: "*/5 * * * *"
4.1.1.5. reportingStart
既存データに対する Report の実行をサポートするには、spec.reportingStart フィールドを RFC3339 タイムスタンプ に設定し、Report が現在の時間ではなく、reportingStart から始まる schedule に基づいて実行するように指示します。1 つの重要な点として、これにより、reporting-operator が reportingStart の時間から現在の時間までの間のスケジュール期間に連続して多数のクエリーを実行する点に留意してください。レポート期間が日次よりも短く区切られ、reportingStart が数ヶ月前に遡る場合、クエリーの数は数千に上る可能性があります。reportingStart が未設定のままの場合、Report はレポート作成後の次の reportingPeriod 全体で実行されます。
このフィールドの使い方を示す一例として、Report に組み込む必要のある 2019 年月 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
指定された時点までのみ実行されるように Report を設定するには、spec.reportingEnd フィールドを RFC3339 タイムスタンプ に設定できます。このフィールドの値により、Report は開始時点から reportingEnd までの期間のレポートデータの生成の終了後にスケジュールに基づいて実行を停止します。スケジュールと reportingEnd は連動しない場合が多いため、スケジュールの最終期間は指定の reportingEnd 時間に終了するように短縮されます。これが未設定のままの場合、Report は永久に実行されるか、または reportingEnd が Report に設定されるまで実行されます。
たとえば、7 月に週 1 回実行されるレポートを作成する場合は、以下のようになります。
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. inputs
Report の spec.inputs フィールドは、ReportQuery の spec.inputs フィールドで定義された値を上書きまたは設定するために使用できます。
名前と値のペアの一覧です。
spec:
inputs:
- name: "NamespaceCPUUsageReportName"
value: "namespace-cpu-usage-hourly"
inputs の name は ReportQuery の inputs 一覧に存在している必要があります。inputs の value は inputs の type に適切なタイプである必要があります。
4.1.1.9. ロールアップレポート
Report データはメトリクス自体と同様にデータベースに保存されるため、集計またはロールアップレポートで使用できます。ロールアップレポートの単純なユースケースとして、レポートの生成のタイミングを長期間にまたがって分散し、月次レポートで月全体のすべてのデータをクエリーし、追加するのではなく、タスクを日次レポートに分割し、それぞれのレポートが 30 番目のデータに対して実行されるようにします。
カスタムのロールアップレポートには、カスタムレポートクエリーが必要です。ReportQuery テンプレートプロセッサーは、Report の metadata.name から必要なテーブル名を取得できる reportTableName 機能を提供します。
以下は、組み込みクエリーのスニペットです。
# 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 フィールドを使用して追跡できます。レポートの作成中に発生したエラーはここに記録されます。
現時点で Report の status フィールドには 2 つのフィールドがあります。
-
conditions: これは、それぞれにtype、status、reason、およびmessageフィールドのある状態についての一覧です。状態のtypeフィールドに使用できる値はRunningおよびFailureであり、スケジュールされたレポートの現在の状態を示します。reasonは、conditionがtrue、falseまたは、unknownのいずれかのstatusで示される現在の状態にある理由を示します。messageは、condition が現在の状態にある理由についての人が判別できる情報を提供します。reasonの値の詳細情報については、pkg/apis/metering/v1/util/report_util.goを参照してください。 -
lastReportTime: メータリングが最後にデータを収集した時を示します。