Cx Cost Optimization

Applying Changes

IMPORTANT: NEVER pass --yes without explicit user approval. All write operations across archive, TCO, and retentions require interactive confirmation and the --yes flag to execute non-interactively. Before executing any write operation, describe the exact change to the user and wait for their approval before passing --yes.

Read-only mode: Use --read-only (or CX_READ_ONLY=1) to safely explore cost data without risk of accidental writes. All query commands (usage, tco list/get, retentions list, archive get) work normally in read-only mode.

Agent mode: When running inside an AI agent, cx fails fast on write operations instead of hanging on a stdin prompt. Get user confirmation first, then re-run with --yes.

When modifying TCO policies, retention, or archive:

1. Template from existing: Get the current configuration as JSON, modify it, then apply:

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

2. Verify after changes: Re-run the diagnosis commands to confirm the change took effect.

3. TCO policy ordering matters: Use cx tco reorder --from-file to set priority order. Policies are evaluated top-to-bottom; the first match wins.

Metrics-Based Cost Analysis

The cx usage API gives summaries, but for billing-accurate analysis, anomaly detection, and breakdown by pillar/feature, query the customer metrics exporter via PromQL.

Key Metrics

Concept-to-Metric Mapping

• Billing / plan usage / consumption -> cx_data_usage_units + cx_data_plan_units_per_day
• Processed bytes / data volume -> cx_data_usage_total
• AI evaluation tokens -> cx_data_usage_tokens_total
• Metric samples -> cx_data_usage_samples_total
• Overage / PAYG -> cx_data_usage_payg_units

Common PromQL Queries

# 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-Day Bucketing Rules

All usage metrics accumulate from UTC midnight and reset at 00:00 UTC:

• An instant query during the day returns "today so far"
• For completed-day totals, use the last sample before midnight
• Never subtract values across a UTC midnight boundary
• For weekly/monthly analysis, derive completed daily totals first, then roll up
• Exclude the current partial UTC day when computing trends or averages

Anomaly Detection

When investigating usage anomalies:

1. Compare completed UTC days (exclude current partial day)
2. Break down by: measurement_type -> pillar -> entity_type -> priority -> feature_group_id -> application_name -> subsystem_name
3. Prefer same-weekday comparisons for seasonal traffic
4. Use cx_data_usage_units for billing anomalies, cx_data_usage_total for volume anomalies

Breakdown Labels

Usage metrics support these grouping dimensions: pillar, entity_type, priority, measurement_type, feature_group_id, feature_id, application_name, subsystem_name.

Key Principles

• Measure before changing - always run usage/summary commands before modifying policies
• Use -o json with jq - structured output enables precise analysis
• Verify changes - re-query after every modification to confirm it took effect
• Multi-profile awareness - use -p <profile> or --all-profiles to compare costs across environments
• Template from existing - get current config as JSON before creating or updating
• TCO is the biggest lever - moving logs from Frequent Search to Archive tier has the largest cost impact

Related Skills

• cx-telemetry-querying - investigate what data is being ingested (query logs, metrics, and spans to identify high-volume sources)

Reference Files

• references/data-usage-query-api.md - capabilities and query schemas, interval rules, limits, and response interpretation