cx-cost-optimization

成本优化 Skill

在调查或降低 Coralogix 数据成本时使用此技能。它涵盖成本管理的完整生命周期：衡量当前支出、审查 TCO 策略、调整保留期限，以及为冷数据配置归档存储。

---

CLI 命令

命令	子命令	用途
cx usage	summary、daily、logs-count、spans-count、export-status、capabilities、query	衡量当前数据消耗量和计费用量
cx tco	list、get、create、update、delete、reorder、test、settings、settings-update	管理 TCO（总拥有成本）策略
cx retentions	list、update、activate、status	管理数据保留期限
cx archive logs	get、set	配置日志归档目标
cx archive metrics	get、create、update、enable、disable、validate	配置指标归档存储
cx metrics query	<promql>（位置参数）、--time	通过 PromQL 查询计费和用量指标（即时）
cx metrics query-range	<promql>（位置参数）、--start/--end	通过 PromQL 查询计费和用量指标（范围）

关键标志：

• 所有命令均支持 -o json 以输出结构化结果，以及 -p <profile> 以选择配置文件
• cx usage daily 接受 --type processed-gbs|units|evaluation-tokens 和 --start/--end 时间筛选条件
• cx usage summary 接受 --start/--end 时间筛选条件
• cx usage logs-count 和 cx usage spans-count 接受 --start/--end 时间筛选条件，默认为最近 24h；还支持 --resolution（默认 1h）、--subsystem-aggregation、--application-aggregation，以及用于 API 筛选查询参数的重复 --param KEY=VALUE
• 数据用量摘要和计数端点文档规定以 Accept: text/event-stream 返回以换行符分隔的 JSON；CLI 会处理该传输方式，并将计数数据块规范化为 .result.logsCount[] 或 .result.spansCount[]。
• cx usage capabilities 是必需的第一步：它会返回当前所选租户的公共 Data Usage Query API 支持的标签、测量项、单位和请求限制
• cx usage query 是必需的第二步：只能基于紧接在前的 capabilities 响应构建 JSON 请求，并且必须且只能使用 --query '<json>' 或 --from-file <path> 之一（--from-file - 从标准输入读取）
• cx tco create/update、cx retentions update、cx archive logs set、cx archive metrics create/update/validate 使用 --from-file <path>（或通过 - 从标准输入读取）

---

权威计费用量查询

对于计费总量、配额单位、计划用量或受支持的用量细分，必须使用以下两步工作流：

1. 在当前会话中运行 cx usage capabilities。
2. 仅使用该响应构建并运行 cx usage query。

不要先调用 cx usage query，也不要猜测标签、测量类型、单位、筛选值、时间间隔或请求限制。这些内容因租户而异，也可能发生变化。

# Inspect the currently valid dimensions and constraints
cx usage capabilities -o json

# Submit a capabilities-derived request inline
cx usage query --query '{"daily":{"relativeRange":"DAILY_RELATIVE_RANGE_LAST_7_DAYS"}}' -o json

# Or read the same request from a file or stdin
cx usage query --from-file usage-query.json -o json
printf '%s' '{"daily":{"relativeRange":"DAILY_RELATIVE_RANGE_LAST_7_DAYS"}}' \
  | cx usage query --from-file - -o json

创建查询主体前，请加载 references/data-usage-query-api.md。其中定义了能力和响应架构、有效的时间间隔格式及限制。

---

成本调查工作流

按照以下步骤诊断并降低成本：

步骤 1：衡量当前用量

对于计费总量、配额单位、计划用量或受支持的细分数据，请先遵循上述必需的两步工作流：

cx usage capabilities -o json
cx usage query --from-file usage-query.json -o json

仅根据紧接在前的能力响应构建 usage-query.json。不要用以下旧版命令替代权威计费数据。

如需查看旧版消耗概览和日志／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

找出消耗量最大的 data type。使用 jq 排序：

cx usage summary -o json | jq '[.[] | {name, daily_avg: .avg_daily_gb}] | sort_by(.daily_avg) | reverse'

第 2 步：查看 TCO 策略

cx tco list -o json
cx tco settings -o json

TCO 策略决定哪些日志进入 Frequent Search（成本高、速度快），哪些进入 Archive（成本低、速度较慢）。检查高流量、低价值的日志是否进入了 Frequent Search：

cx tco list -o json | jq '.[] | select(.priority == "LOW") | {name, application, subsystem, archive_retention}'

第 3 步：检查保留设置

cx retentions list -o json
cx retentions status -o json

较长的保留期限会增加存储成本。找出保留期限过长的索引。

第 4 步：检查归档配置

cx archive logs get -o json
cx archive metrics get -o json

确认是否已为冷数据配置归档存储。如果尚未设置归档，这是一个节省成本的机会。

第 5 步：提出优化建议

根据检查结果，按优先级（影响最大的排在最前）提出变更建议。

---

常见优化模式

症状	诊断命令	优化方案
高流量、低价值的日志	cx usage summary -o json	通过 cx tco create --from-file policy.json 将其移至归档层
冷数据的保留期限过长	cx retentions list -o json	使用 cx retentions update --from-file 缩短保留期限
未配置冷存储	cx archive logs get -o json	启用归档：cx archive logs set --from-file --yes（需先获得用户批准）
未查询但成本高昂的指标	cx archive metrics get -o json	启用指标归档：cx archive metrics create --from-file --yes（需先获得用户批准）

---

jq 示例

使用情况分析

# Top consumers by daily volume
cx usage summary -o json | jq '[.[] | {name, daily_avg: .avg_daily_gb}] | sort_by(.daily_avg) | reverse | .[0:10]'

# Daily trend for the past week
cx usage daily --type processed-gbs --start now-7d -o json | jq '[.[] | {date, gb: .processed_gbs}]'

# Total logs and spans counts
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'

TCO 策略分析

# Policies routing to archive tier
cx tco list -o json | jq '[.[] | select(.archive_retention != null)]'

# Policies by priority
cx tco list -o json | jq 'group_by(.priority) | map({priority: .[0].priority, count: length})'

# Test if a log pattern matches a policy
cx tco test --from-file test-definition.json -o json

保留设置检查

# All retention settings
cx retentions list -o json | jq '.[]'

# Check if retention is active
cx retentions status -o json

归档状态

# Logs archive configuration
cx archive logs get -o json | jq '{active: .active, bucket: .bucket}'

# Metrics archive configuration
cx archive metrics get -o json | jq '{enabled: .enabled, bucket: .bucket}'

---

应用变更

重要：未经用户明确批准，绝不能传入 --yes。 所有涉及归档、TCO 和保留设置的写入操作都需要交互式确认；要以非交互方式执行，还必须使用 --yes 标志。执行任何写入操作前，请向用户说明具体变更，并等待用户批准后再传入 --yes。

只读模式： 使用 --read-only（或 CX_READ_ONLY=1）安全地查看成本数据，避免意外写入。在只读模式下，所有查询命令（usage、tco list/get、retentions list、archive get）都能正常工作。

Agent 模式： 在 AI Agent 中运行时，cx 会在写入操作时快速失败，而不是停在 stdin 提示处。先获得用户确认，再使用 --yes 重新运行。

修改 TCO 策略、保留设置或归档配置时：

1. 以现有配置为模板： 以 JSON 格式获取当前配置，修改后再应用：

   cx tco get <policy-id> -o json > policy.json
   # Edit policy.json
   cx tco update --from-file policy.json
   

2. 变更后验证： 重新运行诊断命令，确认变更已生效。

3. TCO 策略顺序很重要： 使用 cx tco reorder --from-file 设置优先级顺序。策略会从上到下进行评估；首个匹配项优先。

---

基于指标的成本分析

cx usage API 可以提供汇总信息，但要进行与账单准确对齐的分析、异常检测以及按支柱/功能拆分查询，请使用 PromQL 查询客户指标导出器。

关键指标

指标	含义	查询后缀
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 评估令牌数	_total
cx_data_usage_samples_total	已处理指标样本数	_total

概念与指标的对应关系

• 账单／套餐使用量／消耗量 -> cx_data_usage_units + cx_data_plan_units_per_day
• 已处理字节数／数据量 -> cx_data_usage_total
• AI 评估令牌数 -> cx_data_usage_tokens_total
• 指标样本数 -> cx_data_usage_samples_total
• 超额／按量付费（PAYG） -> cx_data_usage_payg_units

常用 PromQL 查询

# Today's billable units consumed so far
cx metrics query 'sum(cx_data_usage_units)' --time now -o json

# Units breakdown by pillar
cx metrics query 'sum by (pillar) (cx_data_usage_units)' --time now -o json

# Daily plan quota
cx metrics query 'cx_data_plan_units_per_day' --time now -o json

# Plan consumption percentage
cx metrics query '100 * sum(cx_data_usage_units) / cx_data_plan_units_per_day' --time now -o json

# Units by feature group
cx metrics query 'sum by (feature_group_id) (cx_data_usage_units)' --time now -o json

# PAYG overage (if any)
cx metrics query 'cx_data_usage_payg_units' --time now -o json

UTC 日分桶规则

所有用量指标从 UTC 午夜开始累计，并在 00:00 UTC 重置：

• 当天执行即时查询时，返回“今日截至目前”的数据
• 要获取已完成日期的总量，请使用午夜前的最后一个样本
• 切勿跨越 UTC 午夜边界相减
• 进行周度／月度分析时，请先计算已完成日期的总量，再汇总
• 计算趋势或平均值时，请排除当前尚未结束的 UTC 日期

异常检测

调查用量异常时：

1. 比较已完成的 UTC 日期（排除当前尚未结束的日期）
2. 按以下维度拆分：measurement_type -> pillar -> entity_type -> priority -> feature_group_id -> application_name -> subsystem_name
3. 季节性流量优先进行相同星期几的比较
4. 账单异常使用 cx_data_usage_units，用量异常使用 cx_data_usage_total

拆分标签

用量指标支持以下分组维度：pillar、entity_type、priority、measurement_type、feature_group_id、feature_id、application_name、subsystem_name。

---

关键原则

• 先衡量再更改 - 修改策略前务必先运行用量／摘要命令
• 搭配 jq 使用 -o json - 结构化输出有助于进行精确分析
• 验证更改 - 每次修改后都要重新查询，以确认更改已生效
• 关注多配置文件 - 使用 -p <profile> 或 --all-profiles 比较不同环境的成本
• 基于现有配置创建模板 - 创建或更新前，先以 JSON 格式获取当前配置
• TCO 是最大的成本杠杆 - 将日志从 Frequent Search 层移至 Archive 层对成本的影响最大

---

相关技能

• cx-telemetry-querying - 调查正在摄取哪些数据（查询日志、指标和跨度，以识别高流量来源）

参考文件

• references/data-usage-query-api.md - 功能和查询架构、间隔规则、限制及响应解读