はじめに

プロダクトの成長とともに、システムの内側から状態を可視化するためのセルフメトリクス（self-instrumentation）が求められるようになる。
関数単位の実行時間や回数、エラー率などを自前で計測し、ログやメトリクスツールに送信する仕組みだ。

しかし、こうした計測の実装は粒度の過不足や記録方式の選定、オーバーヘッドの発生といった設計的判断が問われる構造でもある。

レビューアーは、これらのセルフメトリクス設計が本当に意味のある可観測性を生み出すか？、コストに見合うか？という観点から評価を行う必要がある。

レビュー観点1：どの粒度で何を測っているのか？

最初に見るべきは、どの単位でメトリクスが計測されているかという粒度の問題である。

import time

def process():
    start = time.time()
    ...
    duration = time.time() - start
    print(f"process took {duration:.3f}s")

@Reviewer: 単体関数での実行時間測定は有用ですが、呼び出し頻度や処理量に応じて粒度が適切か評価する必要があります。呼び出し頻度が高すぎるとログが過多になる懸念があります。

レビュー視点：

• 関数全体の計測で十分か？ それとも内部処理ごとに分解すべきか？
• イベント粒度が大きすぎないか？
• 一方で、過剰な細分化で可読性を損ねていないか？

レビュー観点2：ロギングとメトリクスの分離

ログ（人が読む情報）とメトリクス（システムが集計する値）は設計目的が異なる。
これらが混在しているコードはレビュー対象となる。

logger.info("start process")
start = time.time()
...
logger.info(f"duration={time.time() - start}")

@Reviewer: ログ出力とメトリクス収集が混在しており、観測目的が曖昧になっています。ログと数値系メトリクスは用途・設計責任が異なるため、分離構造を検討してください。

理想的には以下のように分離される：

duration = time.time() - start
metrics.record("process_duration", duration)
logger.info("process finished")

レビュー観点3：可観測性とオーバーヘッドのバランス

メトリクス挿入には実行時間・リソース・処理量が伴うため、軽量な処理であってもオーバーヘッドに注意する必要がある。

特に以下のような状況では注意が必要：

• 毎フレーム・毎ループで記録される
• 再帰関数・多段関数に挿入されている
• print()ベースで書かれており、非同期処理と競合している

@Reviewer: 軽量関数内での逐次print出力により、I/Oオーバーヘッドが発生している可能性があります。バッファリングやメトリクスサンプリングをご検討ください。

レビュー観点4：失敗と成功の分離、メトリクスの意味づけ

単に回数を記録しているだけの構造では、失敗率や異常パターンの検知が困難になる。
たとえば、以下のように記録されている場合：

metrics.increment("db_query_count")

このようなメトリクスは異常傾向を見抜くには不十分であり、失敗・例外・リトライなどの分離記録が求められる。

@Reviewer: 失敗/成功の区別なくカウントされており、異常系の可視化が困難です。ステータス別にメトリクスを記録することでトレンド把握が容易になります。

適切な記録：

try:
    result = db.query(...)
    metrics.increment("db_query.success")
except:
    metrics.increment("db_query.failure")
    raise

レビュー観点5：構成可能性とメトリクスの集中管理

メトリクス名・単位・記録方法がコード中に分散して記述されている構造は、
集計・可視化・命名統一が困難になる。

print(f"task_x completed in {elapsed}s")

@Reviewer: メトリクス出力が関数内部にベタ書きされており、全体設計との整合性が保てていません。メトリクス名・命名規則・単位を一元管理する設計が望まれます。

レビュー視点：

• メトリクス名や単位がコード上から明確に定義されているか？
• 既存の監視系（Prometheus, Datadogなど）との整合があるか？
• リファクタ時にメトリクス名が壊れない構造になっているか？

補助視点：レビューでの確認質問例

• このメトリクスは誰が見る前提で設計されているか？（開発者？運用者？非技術者？）
• アラート設定や監視ルールに接続するための意図が明確か？
• 他の処理と比較可能なスケール・単位で記録されているか？
• 記録方式が軽量で、本番運用に耐えうる設計か？

レビュー観点チェックリスト

おわりに

セルフメトリクスの導入は「システムを見える化」する試みだが、
可視化の設計が甘いと、かえって見えなくなる情報が増えてしまう。

レビューアーは、単にtime.time()やprint()が入っているかではなく、
それが何を目的に、誰のために、どのように使われるかを見極め、
構造的な観測性設計と実装のギャップを補う役割を果たすべきである。