Files
crawler-plugin/backend-java/docs/plans/11-plan-observability.md
T
huangzd1997 49c3fc1491 docs(仓库): 规划文档改为入库,落盘品牌库/去重库每公司一套二期方案
`.gitignore` 原先把 docs/plans/ 与 backend-java/docs/plans/ 记成「本地不入库」,
代价有两头:干净 worktree 出包时这些文件根本不存在(门禁要读它们的用例先假红),
跨会话的实施计划也没有留存通道。改为入库,本批把 34 个 md 落进仓库。
2026-10-04 13:51:16 +08:00

246 lines
8.1 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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 禁止记录清单逐项对照。