ProjectAGiPrompt/1-AgentSkills/managing-observability/SKILL.md

name, description, allowed-tools, argument-hint

name	description	allowed-tools	argument-hint
managing-observability	Guides observability implementation including structured logging, metrics, tracing, and audit log alignment for RMDC system. Triggered when adding log statements, defining metrics, implementing traces, or ensuring audit compliance. Keywords: structured log, metrics, trace, audit, Prometheus, OpenTelemetry, rmdc-audit-log.	Read Glob Grep Bash	$ARGUMENTS: <aspect> [module] — aspect: logging|metrics|tracing|audit

managing-observability

概述

本 Skill 指导 RMDC 系统的可观测性实现，确保日志、指标、追踪与审计的一致性。

动态上下文注入

查找日志调用

!grep -rn "log\.\(Info\|Error\|Warn\|Debug\)" --include="*.go" | head -20

查找审计相关代码

!grep -rn "audit\|Audit\|AuditLog" --include="*.go" | head -20

---

Plan（规划阶段）

可观测性维度

维度	工具	对齐模块
日志	结构化日志	rmdc-audit-log
指标	Prometheus	-
追踪	OpenTelemetry	-
审计	PostgreSQL	rmdc-audit-log

决策点

• 日志级别是否合适？
• 是否需要添加审计记录？
• 指标命名是否符合规范？
• trace_id 是否正确传递？

---

Verify（验证清单）

日志规范检查

• 使用结构化日志格式
• 包含 request_id / trace_id
• 敏感信息已脱敏
• 日志级别正确

审计对齐检查

• 关键操作有审计记录
• 审计字段完整（who/when/what/where）
• 审计记录不可篡改
• 与 rmdc-audit-log 格式一致

验证命令

# 检查日志调用规范
grep -rn "log\." --include="*.go" | grep -v "WithFields" | head -20

# 检查审计记录
grep -rn "AuditLog\|audit" --include="*.go" | head -20

---

Execute（执行步骤）

添加结构化日志

import log "github.com/sirupsen/logrus"

log.WithFields(log.Fields{
    "user_id":    userID,
    "action":     "login",
    "request_id": requestID,
}).Info("用户登录成功")

添加审计记录

auditLog.Record(AuditEntry{
    UserID:     userID,
    Action:     "UPDATE_USER",
    ResourceID: targetUserID,
    Details:    changes,
    Timestamp:  time.Now(),
    IP:         clientIP,
})

添加 Prometheus 指标

var loginCounter = prometheus.NewCounterVec(
    prometheus.CounterOpts{
        Name: "rmdc_user_auth_login_total",
        Help: "Total number of login attempts",
    },
    []string{"status"},
)

// 使用
loginCounter.WithLabelValues("success").Inc()

---

Pitfalls（常见坑）

1. 日志泄露敏感信息：密码、Token、身份证号等未脱敏直接打印。
2. 审计字段缺失：无法追溯操作人（user_id）或操作内容（details）。
3. 日志级别滥用：DEBUG 日志在生产环境大量输出影响性能。
4. 审计记录可被删除：审计表需要设置写保护，禁止 DELETE/UPDATE。
5. trace_id 未传递：跨服务调用时未将 trace_id 传递到下游，无法串联请求链路。
6. 指标命名不规范：未遵循 模块_资源_动作_单位 格式。

---

相关文件

用途	路径
日志格式	reference/log-format.md
指标命名	reference/metrics-naming.md
审计对齐	reference/audit-alignment.md