cx-data-pipeline

数据管道技能

在配置 Coralogix 处理、丰富和转换数据的方式时使用此技能。涵盖解析规则（从原始日志中提取结构化字段）、丰富规则（通过查找表添加上下文）、Events2Metrics（从日志／Span 事件派生指标）以及录制规则（预计算 PromQL 表达式）。

---

CLI 命令

命令	子命令	用途
cx parsing-rules	list、get、create、update、delete、bulk-delete、usage-limits	管理日志解析规则
cx enrichments	list、add、remove、overwrite、limit、settings	管理丰富规则
cx enrichments custom	list、get、create、update、delete、search	管理自定义丰富表
cx e2m	list、get、create、update、delete、labels-cardinality、limits	管理 Events2Metrics 定义
cx recording-rules	list、get、create、update、delete	管理 Prometheus 录制规则组

关键标志：

• 所有创建／更新操作均使用 --from-file <path>（或使用 - 表示标准输入）
• 所有命令均支持 -o json 以生成结构化输出，以及 -p <profile> 以选择配置文件
• cx parsing-rules update 和 cx recording-rules update 都需要 --from-file 和规则组 ID
• cx enrichments custom search 需要 --id <table-id> 和 --query <text>
• cx parsing-rules bulk-delete 需要 --ids <id1> <id2> ...

---

使用 JSON 载荷

这些命令使用复杂的 JSON 结构。始终以现有资源为模板，避免格式错误：

# 1. Get an existing resource as a template
cx parsing-rules get <rule-group-id> -o json > template.json

# 2. Modify the template (change fields, remove the ID for create operations)

# 3. Create or update
cx parsing-rules create --from-file template.json
cx parsing-rules update --from-file template.json <rule-group-id>

此模式适用于全部 4 个命令的所有创建／更新操作。它能防止载荷格式错误；这是操作失败的首要原因。

---

解析规则工作流

1. 列出现有规则

cx parsing-rules list -o json
cx parsing-rules list -o json | jq '[.[] | {id, name, enabled, rule_count: (.rules | length)}]'

2. 获取模板

cx parsing-rules get <existing-rule-group-id> -o json > rule-template.json

3. 创建新规则组

根据你的新服务修改模板，然后：

cx parsing-rules create --from-file rule-template.json

4. 验证解析结果

查询近期日志，确认字段已提取（加载 cx-telemetry-querying 以查询日志）：

cx logs 'source logs | filter $d.subsystem == "my-service" | limit 10' -o json

5. 检查使用限额

cx parsing-rules usage-limits -o json

---

丰富规则工作流

1. 列出丰富规则

cx enrichments list -o json
cx enrichments settings -o json
cx enrichments limit -o json

2. 创建自定义丰富表（如有需要）

cx enrichments custom list -o json
cx enrichments custom create --from-file table-definition.json

table-definition.json 必须使用 v5 JSON 结构（内联文件内容，而非多部分格式的 file=@...）：

{
  "name": "IP Lookup",
  "description": "Maps IPs to locations",
  "file": {
    "textual": "ip,city\n1.2.3.4,London",
    "extension": "csv",
    "name": "lookup.csv",
    "size": 24
  }
}

更新时，需包含 customEnrichmentId（数字）以及相同字段。

3. 添加丰富规则

cx enrichments add --from-file enrichment-rules.json

enrichment-rules.json 必须使用 requestEnrichments（而非列表输出中的 enrichments）。每个 enrichmentType 都是对象，而非字符串：

{
  "requestEnrichments": [
    {
      "fieldName": "sourceIPs",
      "enrichmentType": { "geoIp": { "withAsn": true } }
    }
  ]
}

其他类型：{"aws": {"resourceType": "ec2"}}、{"suspiciousIp": {}}、{"customEnrichment": {"id": 1}}。

4. 搜索自定义表数据

cx enrichments custom search --id <table-id> --query "search term"

5. 验证丰富后的字段

在热存储（FrequentSearch 层）中查询日志，确认丰富后的字段已出现。请勿查询归档数据来进行验证，因为摄取延迟可能导致误报。

cx logs 'source logs | filter $d.enriched_field != null | limit 5' -o json

---

Events2Metrics 工作流

E2M 从日志／Span 事件派生 Prometheus 指标。完整的 JSON 线格式、枚举值和基数规则，请参阅 references/e2m-schemas.md。

E2M 的计算方式（请先阅读）

E2M 会在事件流经实时摄取管道时对其进行聚合，生成指标序列（约 1 分钟分辨率）。它是仅向前处理的——指标从创建 E2M 时开始生成；不会回填数据。

所有摄取的数据都会流经管道；TCO 策略会将每个数据流路由到某个层级，而层级决定了可以执行哪些操作：

TCO 层级	存储	E2M / 告警 / 仪表板
High	Frequent Search（热存储，OpenSearch）	✅ 可用
Medium	S3 存档（非热存储）	✅ 可用——仍由管道处理
Low	仅合规存储	❌ 不支持聚合功能
Blocked	丢弃	❌

判断依据是层级 / 处理级别，而不是“Frequent Search 与存档”（Medium 就是 存档，而且 E2M 可在其上运行）。不要告诉用户“将 E2M 指向存档，而不是 Frequent Search”——这种说法不正确。

1. 设计指标

选择 logs2metrics 或 spans2metrics、源字段及聚合方式，以及标签（请考虑基数——参见 references/e2m-schemas.md）。若要将 E2M 限定到某个数据集，请将可选的 dataSource 字段设为 "<dataspace>/<dataset>"；这需要账户启用功能 e2m_dataset_source_enabled（否则 API 会拒绝请求，并提示“dataSource is not enabled for this company”）。标准日志 / span 流则省略此字段。

2. 评估规模：检查限制和基数

cx e2m limits -o json              # account E2M count limit + used
cx e2m labels-cardinality -o json  # see caveat below

标签基数端点提供的是初步预测——给定拟用的标签和查询条件，它会返回过去 7 天内每天的不同排列数量，便于你在创建前评估设计规模。但 cx e2m labels-cardinality 目前不接受任何参数，因此它不会发送草稿，并会返回空列表（这是 CLI 的功能缺口——目前无法进行预测）。在此功能接入之前，请通过 UI 预测，或手动估算排列数（不同标签值数量的乘积），并设置 permutationsLimit。切勿将高基数字段（ID、原始 URL、IP）用作标签。请注意，该预测仅基于 Frequent-Search（High 层级）数据。

3. 使用现有定义作为模板

只有 cx e2m get 会返回完整负载（{"e2m": {...}}）；list 仅打印摘要。提取 .e2m 并移除只读字段：

cx e2m get <existing-e2m-id> -o json | jq '.e2m | del(.id, .permutations, .createTime, .updateTime, .metricName)' > e2m.json

4. 创建 E2M

cx e2m create --from-file e2m.json

5. 验证指标

确认是否正在生成序列（如需查询指标，请加载 cx-telemetry-querying）：

cx metrics search --name "<targetBaseMetricName>"
cx metrics query "<target_metric_name>" --time now

故障排查：E2M 未生成指标序列

1. 检查源数据的 TCO 层级——如果数据被路由到 Low / 合规存储（或已被阻止），E2M 就无法运行。请修改 TCO（cx tco list / cx-cost-optimization），而不是修改 E2M。
2. 确认查询与流式数据匹配——将 E2M 的 lucene 过滤条件用作实时 cx logs / cx spans 查询，并确认能返回近期结果。请注意，cx logs 默认查询 Frequent-Search（High 层级）；对于 **Medium 层级（存档）**源，请添加 --tier archive，因为数据不会出现在默认的 Frequent-Search 查询结果中，即使 E2M 仍会生成序列。
3. 请记住，它仅向前处理——E2M 创建之前摄取的数据不会生成任何序列。

成本优化：将 High 层级日志转换为指标

当客户最关注的是聚合 / 指标视图时，请将 High 层级日志转换为指标，然后将原始日志从 High 降至 Medium。Medium 仍支持 E2M / 告警 / 仪表板，且成本更低（S3 存档，无热存储）——这样既能保留成本低且详细的指标，也能减少昂贵的 Frequent-Search 保留成本。

1. 找出流量较大的 High 层级数据源：cx usage summary / cx tco list（参见 cx-cost-optimization）。
2. 确认驱动仪表板 / 告警的字段（参见 cx-telemetry-querying）。
3. 先创建并验证 E2M（参见上述步骤）。
4. 然后修改 TCO 策略，将原始日志从 High 移至 Medium。数据应保留在 High 或 Medium（两者都支持 E2M）；如果仍需要指标或告警，不要将其降至 Low / 合规存储。

---

录制规则工作流

1. 列出现有录制规则

cx recording-rules list -o json
cx recording-rules list -o json | jq '[.[] | {id, name, rules: [.rules[]?.record]}]'

2. 获取模板

cx recording-rules get <existing-id> -o json > recording-rule-template.json

3. 创建录制规则组

cx recording-rules create --from-file recording-rule-group.json

4. 使用 PromQL 验证

确认预计算指标可用（查询指标前加载 cx-telemetry-querying）：

cx metrics query "new_precomputed_metric" --time now

---

核心原则

• 始终以现有规则为模板 - 创建前运行 cx <command> get <id> -o json > template.json
• 创建后进行验证 - 查询日志/指标，确认管道变更已生效
• 使用 -o json - 检查和创建所有负载时都应使用 JSON 输出
• 先检查限制 - 创建前运行 cx parsing-rules usage-limits 和 cx e2m limits，避免触及上限
• 批量操作 - 清理时使用 cx parsing-rules bulk-delete --ids，而不是逐个删除

---

其他资源

参考文件

• references/e2m-schemas.md - 完整的 Events2Metrics JSON 线格式：type/aggType 枚举值、logsQuery/spansQuery 过滤器、指标标签和字段、TCO 层级计算模型、基数/排列组合规模估算，以及注意事项

---

相关技能

• cx-telemetry-querying - 在配置管道前了解有哪些数据可用，并通过日志/指标查询验证解析结果、丰富字段和 E2M 指标序列
• cx-cost-optimization - 找出值得转换为指标的高流量 High 层级数据源，并在 E2M 验证通过后将原始日志从 High 层级移至 Medium 层级（TCO）