実運用に落とし込もうとすると、どの指標をいつ、どう出すかで立ち止まることが多いはずです。SOPやSLOは設計済みだけれど「具体的に手元で動くレポート」がない、あるいは自動実行や通知の作り方が曖昧で怖い──そんな方に向けて、最短で動くテンプレートと注意点を示します。この記事を読めば手元のログで一度走らせられることを目標にしています。
1) KPIとレポート要件の決め方（SLOとの対応表）
まずはSLOや運用上の目的に直結するKPIを厳選します。重要なのは「運用で何を判断するか」が明確であることです。
| SLO / 目的 | 代表KPI | 表示形式（推奨） | 更新頻度 |
|---|---|---|---|
| 応答品質（SLO: accuracy ≥ 95%） | 正解率、誤答率、カテゴリ別エラー | 時系列グラフ＋カテゴリ比率（棒・円） | 日次 |
| レイテンシ（SLO: p95 < 500ms） | 平均応答時間、p50/p95/p99 | 時系列+分位点テーブル | 日次／時間 |
| 利用状況 | リクエスト数、ユーザー数、APIコスト | 時系列、累積 | 日次 |
KPI→チャート対応のテンプレート（CSV例）
このCSVを作っておくと、実装時にどのクエリでどのチャートに結びつけるか明確になります。
実装メモ: コード例は環境に合わせて調整してください。例: metric_id,metric_name,sql_query,chart_type,frequency
2) データソース整理と取り出し手順（ログ、メトリクス、モデル応答）
まずはデータの所在と更新タイミングを整理します。接続情報は運用用の秘匿ストア（Vaultや環境変数）で管理してください。
| データソース | 主な項目 | 取り出し注意点 |
|---|---|---|
| DB（Postgres等） | リクエストログ、latency、ステータス | 遅延分の補正・タイムゾーン、重複レコードの判定 |
| ログストレージ（S3等） | バッチログ、モデル入力/出力 | 圧縮・パーティションを考慮して部分取得 |
| メトリクス（Prometheus等） | リアルタイム監視用の数値 | 集計方法（カウンタの差分計算）を明記 |
3) PythonでのETLテンプレート（pandas/SQLAlchemyでの抽出・集計）
ここではsingle-fileで動く最小実装を示します。環境変数から接続情報を読み、集計してHTMLを出力します。
実装メモ: コード例は環境に合わせて調整してください。例: #!/usr/bin/env python3
このスクリプトを自分のクエリに合わせて直せば、まずは静的なHTMLレポートが得られます。
4) 可視化とHTML化（plotly/matplotlib -> to_html / jinja2でのレポート生成）
Plotlyのto_htmlはセルフホスト可能な静的HTMLが作れるため、まずはこれでOKです。複数チャートをまとめる場合はJinja2でテンプレートを作ると再利用性が高くなります。
Jinja2テンプレート例（抜粋）
実装メモ: コード例は環境に合わせて調整してください。例: <!– templates/report.html –>
5) 定期実行と配信の実装例（cron / GitHub Actions / Airflowの比較 + サンプルワークフロー）
運用規模や信頼性に応じて実行方法を選びます。まずはcronやGitHub Actionsで始め、要件が増えたらAirflowへ移行する採用が多いです。
| 方式 | メリット | 注意点 |
|---|---|---|
| cron | 設定が単純、すぐ動く | 障害検知や再実行の仕組みを自前で作る必要あり |
| GitHub Actions | コード管理と統合しやすい、Secretsで認証管理 | 実行時間やストレージに制限、ログ保管の設計が必要 |
| Airflow | 依存関係・再実行・監視が豊富 | 運用コストが高い（インフラ、学習コスト） |
cron 例（毎朝6時）
実装メモ: コード例は環境に合わせて調整してください。例: # crontab -e
GitHub Actions workflow のサンプル
実装メモ: コード例は環境に合わせて調整してください。例: name: daily-report
Airflow DAG（雛形）
実装メモ: コード例は環境に合わせて調整してください。例: from airflow import DAG
6) アラート連携（Slack webhook、メール、チケット連携の実装例）
重要な閾値を越えたときにのみ通知する設計にします。ノイズを減らすために閾値のヒステリシス（回数や時間）を入れると良いです。
Slack通知の最小例（requests）
実装メモ: コード例は環境に合わせて調整してください。例: import os
画像を送る場合は、PlotlyでPNG書き出し（fig.to_image）してmultipartで送る方法や、HTMLの要約をテキストで送る方法が現実的です。
7) テスト・監査ポイントと運用チェックリスト
実行前に最低限確認すべき点をチェックリスト化します。定期的な見直しも忘れずに。
| チェック項目 | 理由 | 頻度 |
|---|---|---|
| 接続情報（Secrets）の有効性 | 認証失敗で全て止まるため | 週次 |
| サンプルデータでの集計結果確認 | クエリ変更やデータスキーマ変更の検出 | デプロイ時／重要変更時 |
| アラートのフロー（Slack/メールの到達） | 通知が届かないと意味がない | 月次 |
| PII混入チェック | 出力に個人情報が含まれていないか確認 | データ変更時 |
8) 次に進める拡張（インタラクティブダッシュボード、BI接続、アクセス管理）
- インタラクティブ化: Dash / Streamlit / Supersetなどで掘り下げ分析を可能にする
- BI連携: BigQuery / Redshift などのデータウェアハウスへ集約してBIツールで接続
- アクセス管理: レポートの公開範囲やログの監査を整備（RBAC, ログ保持ポリシー）
配布物 / テンプレート
- KPI→チャート対応表（CSV） — 記事内のCSV例をコピーして使用してください。
- Python ETL + 可視化の最小実装 — 上記のsingle-fileスクリプトをベースにしてください。
- GitHub Actions workflow YAML — 上記のworkflowをそのまま .github/workflows/daily-report.yml に置けます。
- Slack通知サンプルとエラーハンドリング例 — requests を使った例を示しました。
運用上の注意とよくある落とし穴
- データ遅延: バッチ遅延があると不完全な日次集計を出すため、再実行戦略（遅延ウィンドウ）を設ける。
- 重複/欠損: 累積カウンタは差分計算、ログはユニークキーで重複排除を行う。
- コスト: API呼び出しやストレージのコストをモニタリングし、不要な頻度は避ける。
- 権限とPII: 出力テンプレートに氏名やメールなどが入らないか必ずサニタイズする。
- チャート解釈: スライス／ラベルを明記して誤読を防ぐ注釈を付ける。
まとめ
SLO設計をスタート地点に、KPIを絞ってからデータ抽出、可視化、定期実行、通知の順で実装すると短期間で初版を立ち上げられます。まずは上に示したsingle-fileスクリプトを自分の接続情報で動かし、 GitHub Actions や cron に組み込んでSlackへ出力するところまでやってみてください。運用を回しつつ閾値や表示をチューニングすることで、実務で役立つダッシュボードが育っていきます。
読了後の次の一歩（アクションリスト）
- ① 自分のSOP/SLOから最重要3指標を決める
- ② 記事のETLスクリプトを自分のデータ接続に合わせて動かす
- ③ GitHub Actions / cronで定期実行してSlackに出力を流す
- ④ 1週間運用して表示・アラートのチューニングを行う
このシリーズは次回以降で、チャートの解釈ガイドやアクセス制御の実装例を深掘りしていきます。まずはここまでで一度動かしてみてください。