ln-627-observability-auditor

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Observability Auditor (L3 Worker)

可观测性审计器（L3级工作器）

Specialized worker auditing logging, monitoring, and observability.

专注于审计日志、监控和可观测性的工作器。

Purpose & Scope

目标与范围

Worker in ln-620 coordinator pipeline
Audit observability (Category 10: Medium Priority)
Check logging, health checks, metrics, tracing
Calculate compliance score (X/10)

ln-620协调器流水线中的工作器
审计可观测性（类别10：中等优先级）
检查日志、健康检查、指标、追踪
计算合规分数（X/10）

Inputs (from Coordinator)

输入（来自协调器）

Receives

contextStore

with tech stack, framework, codebase root.

接收包含技术栈、框架、代码库根目录的

contextStore

。

Workflow

工作流程

Parse context
Check observability patterns
Collect findings
Calculate score
Return JSON

解析上下文
检查可观测性模式
收集检测结果
计算分数
返回JSON

Audit Rules

审计规则

1. Structured Logging

1. 结构化日志

Detection:

Grep for
```
console.log
```
(unstructured)
Check for proper logger: winston, pino, logrus, zap

Severity:

MEDIUM: Production code using console.log
LOW: Dev code using console.log

Recommendation: Use structured logger (winston, pino)

Effort: M (add logger, replace calls)

检测方式：

用Grep查找
```
console.log
```
（非结构化）
检查是否使用标准日志库：winston、pino、logrus、zap

严重程度：

中等： 生产代码中使用console.log
低：开发代码中使用console.log

建议： 使用结构化日志库（winston、pino）

修复工作量： M（添加日志库，替换调用）

2. Health Check Endpoints

2. 健康检查端点

Detection:

Grep for
```
/health
```
,
```
/ready
```
,
```
/live
```
routes
Check API route definitions

Severity:

HIGH: No health check endpoint (monitoring blind spot)

Recommendation: Add

/health

endpoint

Effort: S (add simple route)

检测方式：

用Grep查找
```
/health
```
、
```
/ready
```
、
```
/live
```
路由
检查API路由定义

严重程度：

高：无健康检查端点（监控盲区）

建议： 添加

/health

端点

修复工作量： S（添加简单路由）

3. Metrics Collection

3. 指标收集

Detection:

Check for Prometheus client, StatsD, CloudWatch
Grep for metric recording:
```
histogram
```
,
```
counter
```

Severity:

MEDIUM: No metrics instrumentation

Recommendation: Add Prometheus metrics

Effort: M (instrument code)

检测方式：

检查是否存在Prometheus客户端、StatsD、CloudWatch
用Grep查找指标记录：
```
histogram
```
、
```
counter
```

严重程度：

中等： 未配置指标埋点

建议： 添加Prometheus指标

修复工作量： M（为代码添加埋点）

4. Request Tracing

4. 请求追踪

Detection:

Check for correlation IDs in logs
Verify trace propagation (OpenTelemetry, Zipkin)

Severity:

MEDIUM: No correlation IDs (hard to debug distributed systems)

Recommendation: Add request ID middleware

Effort: M (add middleware, propagate IDs)

检测方式：

检查日志中是否包含关联ID
验证追踪传播（OpenTelemetry、Zipkin）

严重程度：

中等： 无关联ID（分布式系统调试困难）

建议： 添加请求ID中间件

修复工作量： M（添加中间件，传播ID）

5. Log Levels

5. 日志级别

Detection:

Check if logger supports levels (info, warn, error, debug)
Verify proper level usage

Severity:

LOW: Only error logging (insufficient visibility)

Recommendation: Add info/debug logs

Effort: S (add log statements)

检测方式：

检查日志库是否支持级别（info、warn、error、debug）
验证日志级别的正确使用

严重程度：

低：仅记录错误日志（可见性不足）

建议： 添加info/debug级别的日志

修复工作量： S（添加日志语句）

Scoring Algorithm

评分算法

See

shared/references/audit_scoring.md

for unified formula and score interpretation.

统一公式和分数解读请参考

shared/references/audit_scoring.md

。

Output Format

输出格式

json

{
  "category": "Observability",
  "score": 6,
  "total_issues": 5,
  "critical": 0,
  "high": 1,
  "medium": 3,
  "low": 1,
  "checks": [
    {"id": "structured_logging", "name": "Structured Logging", "status": "warning", "details": "3 console.log calls in production code"},
    {"id": "health_endpoints", "name": "Health Endpoints", "status": "failed", "details": "No /health endpoint found"},
    {"id": "metrics_collection", "name": "Metrics Collection", "status": "passed", "details": "Prometheus client configured"},
    {"id": "request_tracing", "name": "Request Tracing", "status": "warning", "details": "Correlation IDs missing in 2 services"}
  ],
  "findings": [
    {
      "severity": "HIGH",
      "location": "src/api/server.ts",
      "issue": "No /health endpoint for monitoring",
      "principle": "Observability / Health Checks",
      "recommendation": "Add GET /health route returning { status: 'ok', uptime, ... }",
      "effort": "S"
    }
  ]
}

json

{
  "category": "Observability",
  "score": 6,
  "total_issues": 5,
  "critical": 0,
  "high": 1,
  "medium": 3,
  "low": 1,
  "checks": [
    {"id": "structured_logging", "name": "Structured Logging", "status": "warning", "details": "3 console.log calls in production code"},
    {"id": "health_endpoints", "name": "Health Endpoints", "status": "failed", "details": "No /health endpoint found"},
    {"id": "metrics_collection", "name": "Metrics Collection", "status": "passed", "details": "Prometheus client configured"},
    {"id": "request_tracing", "name": "Request Tracing", "status": "warning", "details": "Correlation IDs missing in 2 services"}
  ],
  "findings": [
    {
      "severity": "HIGH",
      "location": "src/api/server.ts",
      "issue": "No /health endpoint for monitoring",
      "principle": "Observability / Health Checks",
      "recommendation": "Add GET /health route returning { status: 'ok', uptime, ... }",
      "effort": "S"
    }
  ]
}

Reference Files

参考文件

Audit scoring formula:
```
shared/references/audit_scoring.md
```

Audit output schema:

shared/references/audit_output_schema.md

Version: 3.0.0 Last Updated: 2025-12-23

审计评分公式：
```
shared/references/audit_scoring.md
```

审计输出 schema：

shared/references/audit_output_schema.md

版本： 3.0.0 最后更新时间： 2025-12-23