structured-logging
構造化ログのスキーマ設計、ログレベル設計、PIIマスキング、JSONログ実装を支援するスキル。ログ要件整理から検証までを一貫して整理する。Anchors:• Observability Engineering / 適用: ログ設計 / 目的: 可観測性向上• 12-Factor App / 適用: 構造化ログ / 目的: JSONログ標準化Trigger:Use when designing JSON log schemas, defining log levels, applying PII masking, or improving observability.structured logging, json logs, log schema, log levels, pii masking
When & Why to Use This Skill
This Claude skill provides a comprehensive framework for designing and implementing structured logging systems. It helps developers and SREs transition from plain-text logs to standardized JSON schemas, ensuring high observability, 12-Factor App compliance, and robust security through automated PII masking and log-level optimization.
Use Cases
- Case 1: Designing a standardized JSON log schema for microservices to enable efficient querying and aggregation in observability platforms like ELK, Datadog, or New Relic.
- Case 2: Implementing automated PII (Personally Identifiable Information) masking patterns to ensure security compliance and prevent sensitive data from being exposed in log files.
- Case 3: Establishing a consistent log-level hierarchy (DEBUG to FATAL) across a distributed system to reduce log noise and improve the accuracy of incident alerting.
- Case 4: Validating application log outputs against predefined schemas during the CI/CD process to prevent breaking changes in monitoring dashboards and log parsers.
| name | structured-logging |
|---|---|
| description | | |
| • Observability Engineering / 適用 | ログ設計 / 目的: 可観測性向上 |
| • 12-Factor App / 適用 | 構造化ログ / 目的: JSONログ標準化 |
structured-logging
概要
ログの要件整理からスキーマ設計、PIIマスキング、検証までを体系化する。
ワークフロー
Phase 1: 要件整理
目的: ログ対象イベントと保存要件を整理する
アクション:
references/Level1_basics.mdで基本指針を確認する- イベント一覧と検索要件を整理する
Task: agents/slog-001-requirements.md を参照
Phase 2: スキーマとレベル設計
目的: ログスキーマとレベル体系を定義する
アクション:
references/log-schema-design.mdを参照するreferences/log-level-guide.mdを参照するassets/log-format-examples.jsonを確認する
Task: agents/slog-002-schema-design.md を参照
Phase 3: 実装と検証
目的: PIIマスキングとログ検証を行う
アクション:
references/pii-masking-patterns.mdを参照するassets/logger-template.tsを適用するscripts/validate-log-format.mjsでログ形式を検証する
Task: agents/slog-003-implementation-review.md を参照
Task仕様ナビ
| Task | 起動タイミング | 入力 | 出力 |
|---|---|---|---|
| slog-001-requirements | Phase 1開始時 | システム概要、監視目的 | ログ要件メモ |
| slog-002-schema-design | Phase 2開始時 | ログ要件メモ、既存ログ例 | ログスキーマ |
| slog-003-implementation-review | Phase 3開始時 | ログスキーマ、ログ出力例 | 実装検証レポート |
詳細仕様: 各Taskの詳細は agents/ ディレクトリを参照
注記: Task名は目的に合わせて定義する
ベストプラクティス
すべきこと
| 推奨事項 | 理由 |
|---|---|
| JSON形式で統一する | 検索と集計が容易になる |
| 必須フィールドを固定化する | 分析の一貫性が保てる |
| PIIを分類してマスキングする | セキュリティ事故を防ぐ |
| ログレベルの基準を定義する | 重要度の優先順位が明確になる |
避けるべきこと
| 禁止事項 | 問題点 |
|---|---|
| プレーンテキストのみのログ | 解析が難しくなる |
| INFOの乱用 | ノイズが増えて監視精度が下がる |
| PIIの生ログ出力 | セキュリティリスクが高まる |
| スキーマ変更の未記録 | 監視ルールが破綻する |
リソース参照
scripts/(決定論的処理)
| スクリプト | 機能 |
|---|---|
scripts/validate-log-format.mjs |
ログ形式の検証 |
scripts/validate-skill.mjs |
スキル構造の検証 |
scripts/log_usage.mjs |
使用記録の保存 |
references/(詳細知識)
| リソース | パス | 読込条件 |
|---|---|---|
| 基礎指針 | references/Level1_basics.md | 要件整理時 |
| 実務指針 | references/Level2_intermediate.md | 実装計画時 |
| 応用指針 | references/Level3_advanced.md | 運用設計時 |
| 専門指針 | references/Level4_expert.md | 高度な最適化時 |
| レベル設計 | references/log-level-guide.md | ログレベル定義時 |
| スキーマ設計 | references/log-schema-design.md | スキーマ設計時 |
| PIIマスキング | references/pii-masking-patterns.md | マスキング設計時 |
assets/(テンプレート・素材)
| アセット | 用途 |
|---|---|
assets/log-format-examples.json |
ログ形式の例 |
assets/logger-template.ts |
ロガー実装テンプレート |