49c3fc1491
`.gitignore` 原先把 docs/plans/ 与 backend-java/docs/plans/ 记成「本地不入库」, 代价有两头:干净 worktree 出包时这些文件根本不存在(门禁要读它们的用例先假红), 跨会话的实施计划也没有留存通道。改为入库,本批把 34 个 md 落进仓库。
246 lines
8.1 KiB
Markdown
246 lines
8.1 KiB
Markdown
# 11-plan — 可观测性:指标定义与日志字段规范
|
||
|
||
> 对应 `docs/specs/11-observability.md`。决策:指标名与日志字段规范先行落地;不引入新监控组件(Micrometer 若已依赖则用,未依赖则手动计数器+日志)。
|
||
> 技术栈:Java 21 + Slf4j +(可选 Micrometer)。
|
||
|
||
## 任务 178:日志字段规范落地
|
||
|
||
**所属模块**:11 可观测性 **依赖**:无 **预估**:8-15 分钟
|
||
|
||
### 功能点要求
|
||
业务日志统一携带结构化字段:traceId/taskId/moduleType/stage/submissionId/chunkIndex/chunkTotal/jobId/result/errorType;缺失字段用占位;不删现有日志。
|
||
|
||
### 测试用例(≥8)
|
||
1. test_worker_log_has_task_id — Worker 日志含 taskId
|
||
2. test_worker_log_has_module_type
|
||
3. test_worker_log_has_stage
|
||
4. test_result_log_fields — /result 日志字段
|
||
5. test_heartbeat_log_fields
|
||
6. test_missing_field_placeholder — 缺字段占位
|
||
7. test_log_field_names_frozen — 字段名快照
|
||
8. test_no_log_content_break — 日志内容不破坏
|
||
|
||
## 任务 179:禁止记录清单审计
|
||
|
||
**所属模块**:11 可观测性 **依赖**:178 **预估**:8-15 分钟
|
||
|
||
### 功能点要求
|
||
审计日志代码:Token/Cookie/完整请求体/文件二进制/用户凭据/敏感 API Key 不入日志;发现问题修正。
|
||
|
||
### 测试用例(≥8)
|
||
1. test_no_token_logged — 无 Token
|
||
2. test_no_cookie_logged — 无 Cookie
|
||
3. test_no_full_body_logged — 无完整 body
|
||
4. test_no_binary_logged — 无二进制
|
||
5. test_no_credential_logged — 无凭据
|
||
6. test_no_api_key_logged — 无 API Key
|
||
7. test_allowed_fields_kept — 允许字段保留
|
||
8. test_audit_script — 审计脚本可重复
|
||
|
||
## 任务 180:Worker 日志字段对齐
|
||
|
||
**所属模块**:11 可观测性 **依赖**:73 **预估**:8-15 分钟
|
||
|
||
### 功能点要求
|
||
TaskResultFileJobWorker(04 改造后)日志字段与规范对齐:jobId/taskId/moduleType/stage/errorType;现有 [task-file-job] 前缀保留。
|
||
|
||
### 测试用例(≥8)
|
||
1. test_dispatch_log_fields — dispatch 日志
|
||
2. test_success_log_fields
|
||
3. test_failure_log_fields
|
||
4. test_retry_log_fields
|
||
5. test_heartbeat_log_fields
|
||
6. test_stuck_log_fields
|
||
7. test_field_names_consistent — 与规范一致
|
||
8. test_no_sensitive — 无敏感
|
||
|
||
## 任务 181:task.created/running 指标埋点
|
||
|
||
**所属模块**:11 可观测性 **依赖**:无 **预估**:8-15 分钟
|
||
|
||
### 功能点要求
|
||
任务创建(created 计数)与运行中(running gauge)指标;带 moduleType/instanceId 标签;无监控栈时输出日志记录。
|
||
|
||
### 测试用例(≥8)
|
||
1. test_created_incremented — 创建计数
|
||
2. test_running_gauge — 运行 gauge
|
||
3. test_module_label — 标签
|
||
4. test_instance_label — instanceId 标签
|
||
5. test_created_module_specific — 分模块
|
||
6. test_counter_persistent — 计数正确性
|
||
7. test_gauge_update — 更新
|
||
8. test_metric_name_frozen — 名称快照
|
||
|
||
## 任务 182:task.success/failed/cancelled 指标埋点
|
||
|
||
**所属模块**:11 可观测性 **依赖**:181 **预估**:8-15 分钟
|
||
|
||
### 功能点要求
|
||
终态计数:success/failed/cancelled 各模块独立计数;与状态迁移一致。
|
||
|
||
### 测试用例(≥8)
|
||
1. test_success_counted
|
||
2. test_failed_counted
|
||
3. test_cancelled_counted
|
||
4. test_module_split — 分模块
|
||
5. test_no_double_count — 不重复计
|
||
6. test_terminal_once — 只计一次
|
||
7. test_failed_then_success — 状态反转不重计
|
||
8. test_names_frozen
|
||
|
||
## 任务 183:task.duration 指标埋点
|
||
|
||
**所属模块**:11 可观测性 **依赖**:182 **预估**:8-15 分钟
|
||
|
||
### 功能点要求
|
||
任务耗时(开始→终态)记录;直方图或耗时日志;分模块。
|
||
|
||
### 测试用例(≥8)
|
||
1. test_duration_recorded — 记录
|
||
2. test_duration_positive — 正值
|
||
3. test_module_split
|
||
4. test_short_task — 短任务
|
||
5. test_long_task — 长任务
|
||
6. test_duration_bound — 上界
|
||
7. test_duration_zero_guard — 零保护
|
||
8. test_name_frozen
|
||
|
||
## 任务 184:task.heartbeat.age 指标埋点
|
||
|
||
**所属模块**:11 可观测性 **依赖**:无 **预估**:8-15 分钟
|
||
|
||
### 功能点要求
|
||
心跳年龄 gauge:任务最后心跳距今时间;超阈值可观测(日志告警)。
|
||
|
||
### 测试用例(≥8)
|
||
1. test_age_computed — 年龄计算
|
||
2. test_age_fresh — 新鲜
|
||
3. test_age_stale — 陈旧
|
||
4. test_age_threshold_warn — 阈值告警
|
||
5. test_no_heartbeat — 无心跳处理
|
||
6. test_age_zero — 刚心跳
|
||
7. test_age_clock_negative — 时钟负保护
|
||
8. test_name_frozen
|
||
|
||
## 任务 185:file-job.* 指标埋点
|
||
|
||
**所属模块**:11 可观测性 **依赖**:73 **预估**:8-15 分钟
|
||
|
||
### 功能点要求
|
||
TaskFileJobWorker 指标:pending/running/success/failed/duration/retry;分 moduleType/instanceId。
|
||
|
||
### 测试用例(≥8)
|
||
1. test_pending_counted
|
||
2. test_running_counted
|
||
3. test_success_counted
|
||
4. test_failed_counted
|
||
5. test_duration_recorded
|
||
6. test_retry_counted
|
||
7. test_module_instance_labels
|
||
8. test_names_frozen
|
||
|
||
## 任务 186:上传耗时/大小指标埋点
|
||
|
||
**所属模块**:11 可观测性 **依赖**:无 **预估**:8-15 分钟
|
||
|
||
### 功能点要求
|
||
文件上传:耗时、大小、成功率指标;分 moduleType。
|
||
|
||
### 测试用例(≥8)
|
||
1. test_upload_duration
|
||
2. test_upload_size
|
||
3. test_upload_success_rate
|
||
4. test_module_split
|
||
5. test_upload_failed
|
||
6. test_upload_large
|
||
7. test_size_bound
|
||
8. test_names_frozen
|
||
|
||
## 任务 187:临时磁盘指标埋点
|
||
|
||
**所属模块**:11 可观测性 **依赖**:154 **预估**:8-15 分钟
|
||
|
||
### 功能点要求
|
||
临时磁盘容量/占用指标;与 09 告警联动。
|
||
|
||
### 测试用例(≥8)
|
||
1. test_disk_usage_measured
|
||
2. test_disk_capacity
|
||
3. test_usage_percent
|
||
4. test_threshold_warn
|
||
5. test_empty_dir
|
||
6. test_measure_failure_grace
|
||
7. test_name_frozen
|
||
8. test_no_block
|
||
|
||
## 任务 188:指标标签规范
|
||
|
||
**所属模块**:11 可观测性 **依赖**:181-187 **预估**:8-15 分钟
|
||
|
||
### 功能点要求
|
||
统一标签:moduleType/instanceId 必带;标签值规范化(null→unknown);不记录用户级数据。
|
||
|
||
### 测试用例(≥8)
|
||
1. test_module_label_all_metrics — 全指标带
|
||
2. test_instance_label_all
|
||
3. test_null_module_unknown — null 归一
|
||
4. test_no_user_label — 无用户级
|
||
5. test_label_consistent — 命名一致
|
||
6. test_label_value_clean — 值清洗
|
||
7. test_cardinality_bounded — 基数有界
|
||
8. test_spec_frozen — 规范冻结
|
||
|
||
## 任务 189:指标命名一致性测试
|
||
|
||
**所属模块**:11 可观测性 **依赖**:188 **预估**:8-15 分钟
|
||
|
||
### 功能点要求
|
||
全部指标名与 11 spec §1 标准名一致(aiimage.* 前缀);无拼写漂移。
|
||
|
||
### 测试用例(≥8)
|
||
1. test_prefix_aiimage — 前缀
|
||
2. test_task_metric_names — 任务族
|
||
3. test_file_job_metric_names — 文件族
|
||
4. test_no_typo_drift — 无拼写漂移
|
||
5. test_snapshot_all_metrics — 全指标快照
|
||
6. test_new_metric_must_register — 新指标注册
|
||
7. test_metric_doc_sync — 文档同步
|
||
8. test_case_consistent — 大小写一致
|
||
|
||
## 任务 190:日志脱敏测试
|
||
|
||
**所属模块**:11 可观测性 **依赖**:179 **预估**:8-15 分钟
|
||
|
||
### 功能点要求
|
||
敏感值(Token/Key/凭据)即使传入日志调用点也被脱敏(占位符);断言日志输出无原文。
|
||
|
||
### 测试用例(≥8)
|
||
1. test_token_masked
|
||
2. test_api_key_masked
|
||
3. test_password_masked
|
||
4. test_cookie_masked
|
||
5. test_partial_token_masked — 部分值
|
||
6. test_url_query_masked — URL 查询参数
|
||
7. test_masking_consistent — 一致
|
||
8. test_normal_fields_kept — 正常字段保留
|
||
|
||
## 任务 191:双实例指标区分回归
|
||
|
||
**所属模块**:11 可观测性 **依赖**:188-190 **预估**:8-15 分钟
|
||
|
||
### 功能点要求
|
||
双实例部署:instanceId 标签区分 server-110/server-121;指标不串;日志含实例标识。
|
||
|
||
### 测试用例(≥8)
|
||
1. test_instance_110_label
|
||
2. test_instance_121_label
|
||
3. test_no_cross_instance — 不串
|
||
4. test_instance_unknown — 未配置
|
||
5. test_log_has_instance — 日志实例
|
||
6. test_metric_aggregation_ok — 聚合可用
|
||
7. test_label_stable — 标签稳定
|
||
8. test_snapshot_frozen
|
||
|
||
### 收尾验证(本模块)
|
||
`mvn test` 相关类全绿;11 spec §2 禁止记录清单逐项对照。
|