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