用 Coralogix CLI…

当需要检查 Coralogix 数据用量、分析账单、定位高成本来源并优化日志/指标开销时使用。

适用场景

解决思路

1. 先测量再改动：在修改任何策略前，先运行 usage/summary 类命令了解当前消耗。
2. 要获取权威的计费总量、配额单位、套餐消耗或受支持的用量细分时，必须走两步流程：先运行 `cx usage capabilities`，再仅基于该响应构建并运行 `cx usage query`。
3. 不要先调用 `cx usage query`，也不要猜测标签、measurement 类型、单位、过滤值、间隔或请求限制，因为它们因租户而异且会变化。
4. 构建查询体前先加载 `references/data-usage-query-api.md`，它定义了 capability 与响应 schema、合法间隔形式和限制。
5. 用 `cx usage query --query '<json>'` 或 `cx usage query --from-file <path>`（`--from-file -` 读 stdin）提交查询。
6. 用旧版命令做消耗概览和日志/span 记录计数：`cx usage summary -o json`、`cx usage summary --start now-30d -o json`、`cx usage daily --type processed-gbs --start now-7d -o json`、`cx usage logs-count --start now-7d --end now -o json`、`cx usage spans-count --start now-7d --end now -o json`。
7. 用 jq 排序找出消耗最大的数据类型：`cx usage summary -o json | jq '[.[] | {name, daily_avg: .avg_daily_gb}] | sort_by(.daily_avg) | reverse'`。
8. 审查 TCO 策略：`cx tco list -o json` 和 `cx tco settings -o json`；TCO 策略控制哪些日志进入 Frequent Search（贵、快）还是 Archive（便宜、慢）。
9. 检查高流量低价值日志是否在 Frequent Search：`cx tco list -o json | jq '.[] | select(.priority == "LOW") | {name, application, subsystem, archive_retention}'`。
10. 检查保留期设置：`cx retentions list -o json` 和 `cx retentions status -o json`，找出保留期过长导致存储成本升高的索引。
11. 检查归档配置：`cx archive logs get -o json` 和 `cx archive metrics get -o json`，确认冷数据是否已配置归档存储。
12. 按影响从高到低给出优化建议。
13. 常见优化：高流量低价值日志用 `cx tco create --from-file policy.json` 移到归档层；冷数据保留期过长用 `cx retentions update --from-file` 缩短；未配置冷存储用 `cx archive logs set --from-file --yes`（需用户批准）启用归档；昂贵但未被查询的指标用 `cx archive metrics create --from-file --yes`（需用户批准）启用指标归档。
14. 用 jq 做用量分析：`cx usage summary -o json | jq '[.[] | {name, daily_avg: .avg_daily_gb}] | sort_by(.daily_avg) | reverse | .[0:10]'`；`cx usage daily --type processed-gbs --start now-7d -o json | jq '[.[] | {date, gb: .processed_gbs}]'`。
15. 统计日志与 span 总量：`cx usage logs-count --start now-7d --end now -o json | jq '[.result.logsCount[]?.logsCount | tonumber] | add // 0'`；`cx usage spans-count --start now-7d --end now -o json | jq '[.result.spansCount[]? | ((.successSpanCount | tonumber) + (.errorSpanCount | tonumber) + (.lowSuccessSpanCount | tonumber) + (.lowErrorSpanCount | tonumber) + (.mediumSuccessSpanCount | tonumber) + (.mediumErrorSpanCount | tonumber))] | add // 0'`。
16. 用 jq 分析 TCO 策略：`cx tco list -o json | jq '[.[] | select(.archive_retention != null)]'`；`cx tco list -o json | jq 'group_by(.priority) | map({priority: .[0].priority, count: length})'`；用 `cx tco test --from-file test-definition.json -o json` 测试日志模式是否匹配某策略。
17. 用 jq 审查保留期与归档状态：`cx retentions list -o json | jq '.[]'`；`cx retentions status -o json`；`cx archive logs get -o json | jq '{active: .active, bucket: .bucket}'`；`cx archive metrics get -o json | jq '{enabled: .enabled, bucket: .bucket}'`。
18. 写操作前必须获得用户明确批准，绝不能在未获批准时传 `--yes`；先向用户描述确切变更并等待批准，再传 `--yes` 执行。
19. 用 `--read-only`（或 `CX_READ_ONLY=1`）安全探索成本数据，避免误写；所有查询命令在只读模式下正常工作。
20. 在 AI agent 中运行时，cx 对写操作会快速失败而非卡在 stdin 提示；先获取用户确认，再用 `--yes` 重跑。
21. 修改 TCO 策略、保留期或归档时，先从现有配置模板化：`cx tco get <policy-id> -o json > policy.json`，编辑后再 `cx tco update --from-file policy.json`。
22. 变更后验证：重跑诊断命令确认变更已生效。
23. TCO 策略顺序很重要：用 `cx tco reorder --from-file` 设置优先级顺序；策略自上而下评估，第一个匹配者生效。
24. 要做计费精确分析、异常检测和按 pillar/feature 细分时，用 PromQL 查询客户指标导出器。
25. 关键指标：`cx_data_usage_units`（每日计费单位，权威计费指标，无 `_total`）、`cx_data_plan_units_per_day`（当前每日套餐配额快照，无 `_total`）、`cx_data_usage_payg_units`（每日超额/PAYG 单位，无 `_total`）、`cx_data_usage_total`（处理数据字节数，带 `_total`）、`cx_data_usage_tokens_total`（AI 评估 token，带 `_total`）、`cx_data_usage_samples_total`（处理指标样本，带 `_total`）。
26. 概念到指标映射：计费/套餐用量/消耗 -> `cx_data_usage_units` + `cx_data_plan_units_per_day`；处理字节/数据量 -> `cx_data_usage_total`；AI 评估 token -> `cx_data_usage_tokens_total`；指标样本 -> `cx_data_usage_samples_total`；超额/PAYG -> `cx_data_usage_payg_units`。
27. 常用 PromQL：`cx metrics query 'sum(cx_data_usage_units)' --time now -o json`；`cx metrics query 'sum by (pillar) (cx_data_usage_units)' --time now -o json`；`cx metrics query 'cx_data_plan_units_per_day' --time now -o json`；`cx metrics query '100 * sum(cx_data_usage_units) / cx_data_plan_units_per_day' --time now -o json`；`cx metrics query 'sum by (feature_group_id) (cx_data_usage_units)' --time now -o json`；`cx metrics query 'cx_data_usage_payg_units' --time now -o json`。
28. UTC 日分桶规则：所有用量指标从 UTC 午夜累积并在 `00:00 UTC` 重置；白天即时查询返回“今日至今”；要完整日总量用午夜前最后一个样本；绝不跨 UTC 午夜边界相减；周/月分析先得出完整日总量再汇总；计算趋势或均值时排除当前不完整的 UTC 日。
29. 异常检测：比较完整的 UTC 日（排除当前不完整日）；按 `measurement_type` -> `pillar` -> `entity_type` -> `priority` -> `feature_group_id` -> `application_name` -> `subsystem_name` 细分；季节性流量优先用同一星期几比较；计费异常用 `cx_data_usage_units`，数据量异常用 `cx_data_usage_total`。
30. 用量指标支持的分组维度：`pillar`、`entity_type`、`priority`、`measurement_type`、`feature_group_id`、`feature_id`、`application_name`、`subsystem_name`。
31. 用 `-o json` 配合 jq 获得结构化输出以做精确分析。
32. 用 `-p <profile>` 或 `--all-profiles` 跨环境比较成本。
33. TCO 是最大的杠杆：把日志从 Frequent Search 移到 Archive 层对成本影响最大。

适用边界 · 注意事项

• 不适用于非 Coralogix 的可观测性/日志平台，本技能依赖 cx CLI 和 Coralogix 租户。
• 不要在未获得用户明确批准时执行任何写操作（TCO、保留期、归档），也不要传 `--yes`。
• 不要用旧版 usage 命令替代权威计费答案，计费总量必须走 capabilities + query 两步流程。