telemetry

テレメトリー

クイックスタート

このスキルを使うと、コードベースをログだらけにせず、動作のデバッグに役立つ軽量なアプリ計装を追加できます。Apple の統合ログ API を優先し、ビルドと実行のサイクル後にイベントを確認してください。

基本ガイドライン

• 構造化アプリログには、OSLog フレームワークの Logger を優先してください。
• 各機能に明確なサブシステムとカテゴリの組み合わせを割り当て、実行時のフィルタリングを容易にしてください。
• 意味のあるユーザーイベントとアプリのライフサイクルイベントをログに記録してください。ウィンドウの表示、サイドバーの選択変更、メニューコマンド、メニューバーエクストラのアクション、同期や読み込みのマイルストーン、予期しないフォールバック経路などが該当します。
• 情報ログは簡潔で安定した内容にしてください。ノイズの多い状態の詳細にはデバッグログを使ってください。
• シークレット、認証トークン、個人データ、生のドキュメント内容はログに記録しないでください。
• サインポストは、時間やパフォーマンスの区間を計測するときに限って追加してください。デフォルトで過剰に計装しないでください。

最小限の Logger パターン

import OSLog

private let logger = Logger(
  subsystem: Bundle.main.bundleIdentifier ?? "SampleApp",
  category: "Sidebar"
)

@MainActor
func selectItem(_ item: SidebarItem) {
  logger.info("Selected sidebar item: \(item.id, privacy: .public)")
  selection = item.id
}

ログをすばやくフィルタリングできるよう、Windowing、Commands、MenuBar、Sidebar、Sync、Import など、機能固有のカテゴリを使ってください。

ワークフロー

1. 可観測性が必要な動作を特定します。

   • ウィンドウの表示／終了
   • サイドバーまたはインスペクタの選択変更
   • メニューまたはキーボードコマンドのアクション
   • メニューバーエクストラのアクション
   • バックグラウンドでの読み込み／同期／インポートイベント
   • エラーと復旧の経路

2. 役に立つ最小限の計装を追加します。

   • 機能領域または型ごとに Logger を1つ作成します。
   • アクションの境界と主要な状態遷移をログに記録します。
   • ノイズの多い値の羅列より、ユーザーアクションごとにシグナルの強い行を1つ記録することを優先します。

3. アプリをビルドして実行します。

   • ビルドと実行のサイクルには build-run-debug を使います。
   • script/build_and_run.sh が存在する場合、ライブのテレメトリ確認には ./script/build_and_run.sh --telemetry、より広範なプロセスログの確認には ./script/build_and_run.sh --logs を優先してください。
   • テレメトリを出力するはずの UI またはコマンド経路を実際に操作します。

4. 実行時ログを読み、イベントが発生したことを確認します。

   • 手動で最も手早く確認できる場合は、プロセス／サブシステムのフィルタを指定して Console.app を使います。
   • ターミナルでリアルタイムに確認するには、log stream --style compact --predicate 'process == "AppName"' を使います。
   • サブシステム／カテゴリがわかっている場合は、より限定的な述語を優先してください。 log stream --style compact --predicate 'subsystem == "com.example.app" && category == "Sidebar"'

5. 計装を調整するか、削除します。

   • イベントが発生したら、今後のデバッグにも役立つログだけを残します。
   • 発生しない場合は、疑わしい制御経路に近い位置へログを移動し、もう一度実行します。

検証チェックリスト

• テレメトリの変更後にアプリをビルドできます。
• 該当するアクションによって、明確なログ行が1行だけ、または少数のまとまったログが出力されます。
• プロセス、サブシステム、カテゴリでログをフィルタリングできます。
• 機密性の高いペイロードが統合ログに書き込まれません。
• 一時的なノイズの多いデバッグログは、作業を終える前に削除するか、重要度を下げます。

ガードレール

• macOS アプリのコードで、主要なアプリテレメトリの仕組みとして print を使わないでください。
• すべての状態変更の周囲に、永続的なデバッグログを過剰に残さないでください。
• Console、log stream、または取得したプロセス出力を通じた具体的な検証経路を確立するまでは、イベントが正しく接続されていると断言しないでください。
• デバッグ作業の大半がアクションのテレメトリではなく、クラッシュやバックトレースの解析に関するものであれば、build-run-debug に切り替えてください。