/cx-cost-optimization

name: cx-cost-optimization
description: >
  Use this skill when the user asks to "check data usage", "list TCO policies",
  "reduce Coralogix costs", "optimize observability spend", "lower our logging bill",
  "data budget exceeded", "TCO policy", "retention tier", "archive storage", "ingestion costs",
  "frequent search vs archive", "why is our bill so high", "spending too much on logs",
  "data retention settings", "cost analysis", "usage breakdown",
  "optimize log volume", "control data ingestion", "archive cold data",
  "billing units", "plan consumption", "daily plan", "overage", "PAYG",
  "usage anomaly", "usage trend", "cx_data_usage_units",
  or wants to investigate, analyze, or reduce Coralogix data costs.
metadata:
  version: "0.1.0"

Cost Optimization Skill

Use this skill when investigating or reducing Coralogix data costs. It covers the full cost management lifecycle: measuring current spend, reviewing TCO policies, adjusting retention periods, and configuring archive storage for cold data.

---

CLI Commands

| Command | Subcommands | Purpose | |---|---|---| | `cx usage` | `summary`, `daily`, `logs-count`, `spans-count`, `export-status`, `capabilities`, `query` | Measure current data consumption and billable usage | | `cx tco` | `list`, `get`, `create`, `update`, `delete`, `reorder`, `test`, `settings`, `settings-update` | Manage TCO (Total Cost of Ownership) policies | | `cx retentions` | `list`, `update`, `activate`, `status` | Manage data retention periods | | `cx archive logs` | `get`, `set` | Configure logs archive target | | `cx archive metrics` | `get`, `create`, `update`, `enable`, `disable`, `validate` | Configure metrics archive storage | | `cx metrics query` | `<promql>` (positional), `--time` | Query billing and usage metrics via PromQL (instant) | | `cx metrics query-range` | `<promql>` (positional), `--start`/`--end` | Query billing and usage metrics via PromQL (range) |

Key flags:

• All commands support `-o json` for structured output and `-p <profile>` for profile selection
• `cx usage daily` accepts `--type processed-gbs|units|evaluation-tokens` and `--start`/`--end` time filters
• `cx usage summary` accepts `--start`/`--end` time filters
• `cx usage logs-count` and `cx usage spans-count` accept `--start`/`--end` time filters, defaulting to the last 24h, plus `--resolution` (default `1h`), `--subsystem-aggregation`, `--application-aggregation`, and repeated `--param KEY=VALUE` for API filter query params
• Data usage summary and count endpoints are documented as newline-delimited JSON over `Accept: text/event-stream`; the CLI handles that transport and normalizes count chunks into `.result.logsCount[]` or `.result.spansCount[]`.
• `cx usage capabilities` is the required first step: it returns the labels, measurements, units, and request limits that the public Data Usage Query API currently supports for the selected tenant
• `cx usage query` is the required second step: submit only a JSON request derived from the immediately preceding `capabilities` response with exactly one of `--query '<json>'` or `--from-file <path>` (`--from-file -` reads stdin)
• `cx tco create/update`, `cx retentions update`, `cx archive logs set`, `cx archive metrics create/update/validate` use `--from-file <path>` (or `-` for stdin)

---

Authoritative Billable Usage Queries

For billable totals, quota units, plan consumption, or a supported usage breakdown, use this mandatory two-step workflow:

1. Run `cx usage capabilities` in the current session. 2. Build and run `cx usage query` using only that response.

Do not call `cx usage query` first and do not guess labels, measurement kinds, units, filter values, intervals, or request limits. They are tenant-specific and can change.

# 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

Load [`references/data-usage-query-api.md`](references/data-usage-query-api.md) before creating the query body. It defines the capability and response schemas, valid interval forms, and limits.

---

Cost Investigation Workflow

Follow these steps to diagnose and reduce costs:

Step 1: Measure Current Usage

For billable totals, quota units, plan consumption, or supported breakdowns, first follow the mandatory two-step workflow above:

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

Build `usage-query.json` only from the immediately preceding capabilities response. Do not use the legacy commands below as a substitute for an authoritative billing answer.

For a legacy consumption overview and log/span record counts, use:

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

Identify which data types consume the most volume. Use `jq` to sort:

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

Step 2: Review TCO Policies

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

TCO policies control which logs go to Frequent Search (expensive, fast) vs. Archive (cheap, slower). Check if high-volume, low-value logs are on Frequent Search:

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

Step 3: Check Retention Settings

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

Long retention periods increase storage costs. Identify indic