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

8.1 KiB
Raw Blame History

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 禁止记录清单逐项对照。