data-health-monitor

数据健康监控

目的

通过一条命令回答“我的数据流动是否正常？”。汇总数据流、作业、架构和事件配额的健康信号，生成统一且可执行的报告。完全只读。

环境

需要经过身份验证的 API 访问权限。凭据解析请参阅 ../references/auth.md。

流程

运行全部四项健康检查，然后呈现统一报告。如果用户询问特定领域，则重点检查该维度，但仍须展示其他维度的摘要。

检查 1：数据流健康状况

curl -s "${LYTICS_API_URL:-https://api.lytics.io}/v2/stream" \
  -H "Authorization: ${LYTICS_API_TOKEN}"

对每个数据流进行评估：

信号	检测方法	严重程度
活跃	last_msg_ts 在过去 1 小时内	HEALTHY
数据流陈旧（持续型）	last_msg_ts 为 1–24 小时前	WARNING
数据流陈旧（批处理型）	last_msg_ts 为 2–7 天前	WARNING
停止运行	last_msg_ts 超过 24 小时（持续型）或超过 7 天（批处理型）	ERROR
从未接收数据	ct == 0	ERROR

通过检查数据流是否关联具有定期计划的作业，区分批处理型和持续型数据流。

对于存在问题的数据流，获取近期统计信息以了解更多详情：

curl -s "${LYTICS_API_URL:-https://api.lytics.io}/v2/stream/${STREAM_NAME}/stats" \
  -H "Authorization: ${LYTICS_API_TOKEN}"

检查 2：作业健康状况

# Active jobs (default: non-terminal states)
curl -s "${LYTICS_API_URL:-https://api.lytics.io}/v2/job" \
  -H "Authorization: ${LYTICS_API_TOKEN}"

# Also check recently failed jobs
curl -s "${LYTICS_API_URL:-https://api.lytics.io}/v2/job?show_completed=true" \
  -H "Authorization: ${LYTICS_API_TOKEN}"

评估每个作业：

状态	严重程度	操作
runnable	HEALTHY	正常运行
sleeping	HEALTHY	已安排，等待下次运行
paused	WARNING	已主动暂停，但应予以关注
fault	ERROR	需要调查——获取日志
failed	ERROR	终止失败——获取日志
killed	INFO	已手动停止

对于出现故障或失败的作业，获取日志：

curl -s "${LYTICS_API_URL:-https://api.lytics.io}/v2/job/${JOB_ID}/logs" \
  -H "Authorization: ${LYTICS_API_TOKEN}"

还要检查是否存在陈旧作业：如果 runnable 作业的 updated 时间已超过 1 小时，则可能卡住了。

检查 3：架构健康状况

# Get all fields with metadata
curl -s "${LYTICS_API_URL:-https://api.lytics.io}/v2/schema/user/field" \
  -H "Authorization: ${LYTICS_API_TOKEN}"

检查：

• 身份字段：统计 IsIdentifier == true 的字段数。如果少于 2 个，则标记。
• PII 字段：统计标记为 IsPII == true 的字段数，以便了解情况。
• 陈旧字段：Modified 时间戳早于 30 天且仍在积极使用的字段。

如需深入分析覆盖情况：

curl -s "${LYTICS_API_URL:-https://api.lytics.io}/api/schema/user/fieldinfo" \
  -H "Authorization: ${LYTICS_API_TOKEN}"

检查字段存在/缺失比例。对于覆盖率极低且出现在细分 FilterQL 中的字段予以标记。

检查 4：事件配额

curl -s "${LYTICS_API_URL:-https://api.lytics.io}/v2/control/eventquota/thresholds" \
  -H "Authorization: ${LYTICS_API_TOKEN}"

报告当前用量及其相对于 50%、75%、100% 和 125% 阈值的情况。

可选：深入分析指标

用户需要了解趋势或进行更深入的分析时：

# Stream throughput over last 24h
curl -s "${LYTICS_API_URL:-https://api.lytics.io}/v2/metric?dimension=stream&range=now-24h" \
  -H "Authorization: ${LYTICS_API_TOKEN}"

# Job execution metrics over last 24h
curl -s "${LYTICS_API_URL:-https://api.lytics.io}/v2/metric?dimension=works&range=now-24h" \
  -H "Authorization: ${LYTICS_API_TOKEN}"

# Segment size trends
curl -s "${LYTICS_API_URL:-https://api.lytics.io}/v2/metric?dimension=segment&range=now-24h" \
  -H "Authorization: ${LYTICS_API_TOKEN}"

以趋势形式呈现：“数据流吞吐量较昨日下降 40%”或“细分规模保持稳定”。

输出格式

按以下格式呈现报告：

## Data Health Report

### Overall: HEALTHY | NEEDS ATTENTION | UNHEALTHY

### Streams (N total)
  HEALTHY: X streams actively receiving data
  WARNING: 'stream_name' -- last event 3 days ago
  ERROR: 'stream_name' -- never received events

### Jobs (N active)
  HEALTHY: X jobs running normally
  FAULT: 'job_name' -- error message from logs
  PAUSED: 'job_name' -- paused since date

### Schema (user table, N fields)
  Identity fields: N configured (field1, field2, ...)
  Low coverage: 'field' at X%
  Stale: 'field' not updated in N days

### Event Quota
  Current usage: X% of monthly quota

### Recommendations
1. Specific actionable recommendation
2. Another recommendation
3. ...

严重程度逻辑

总体状态	条件
HEALTHY	所有数据流均活跃，所有作业均在运行，没有故障，配额 < 75%
NEEDS ATTENTION	任一情况：数据流陈旧、作业暂停、字段覆盖率低、配额为 75–100%
UNHEALTHY	任一情况：作业出现故障/失败、数据流停止运行、配额 > 100%

建议生成规则

根据检查结果生成具体且可执行的建议：

• 作业出现故障 → “调查 ‘job_name’ 故障。检查身份验证凭据或重新启动该作业。”
• 数据流停止运行 → “数据流 ‘name’ 已有 N 天未收到数据。检查源集成。”
• 数据流事件数为零 → “数据流 ‘name’ 已配置，但从未收到数据。确认集成设置正确。”
• 身份字段过少 → “仅配置了 N 个身份字段。考虑将更多字段标记为标识符，以便更好地解析用户档案。”
• 配额接近上限 → “事件配额已达到 X%。考虑检查高流量数据流或升级套餐。”
• 字段陈旧 → “字段 ‘name’ 已有 N 天未更新。检查源集成是否仍在运行。”

错误处理

• 任意检查出现 API 错误：报告该维度的错误，并继续执行其他检查。绝不能让单项检查失败阻断整份报告。
• 响应为空：报告“未找到[数据流/作业/字段]”——这可能表示账户是新建的或尚未配置。
• 超时：如果某项检查耗时过长，则附注后跳过，并继续执行。

Dependencies

• Composes: stream-inspector skill, job-manager skill, schema-manager skill
• References: ../references/auth.md, ../references/api-client.md