---
name: managing-observability
description: "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."
allowed-tools:
  - Read
  - Glob
  - Grep
  - Bash
argument-hint: "$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 格式一致

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

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

---

## Execute（执行步骤）

### 添加结构化日志
```go
import log "github.com/sirupsen/logrus"

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

### 添加审计记录
```go
auditLog.Record(AuditEntry{
    UserID:     userID,
    Action:     "UPDATE_USER",
    ResourceID: targetUserID,
    Details:    changes,
    Timestamp:  time.Now(),
    IP:         clientIP,
})
```

### 添加 Prometheus 指标
```go
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/log-format.md) |
| 指标命名 | [reference/metrics-naming.md](reference/metrics-naming.md) |
| 审计对齐 | [reference/audit-alignment.md](reference/audit-alignment.md) |