cx-service-catalog

Service Catalog Skill

Use this skill to discover and query Service Catalog entities — services, databases, operations, database operations, JVMs, JVM GC, Kubernetes pods, and transactions — and their columnar metrics (latency, error rate, health, resource usage, etc.) via the v2 Service Catalog API.

CLI Commands

• All commands are read-only and support -o json / -o toon for

structured output.

• Entity type accepts short forms: service, database, operation,

database-operation, jvm, jvm-gc, k8s-pod, transaction (case-insensitive, hyphens or underscores). The full proto name (ENTITY_TYPE_K8S_POD) also works. Unknown values are rejected client-side before any request is made.

• --start/--end accept now, now-1h-style relative expressions, or

RFC3339 timestamps.

• --column is required and repeatable — discover valid column ids with

cx service-catalog schema <entity-type> first; the API rejects unknown ones.

• --filter label=value1,value2 is repeatable across distinct labels only

(filters AND together); combine multiple values for the same label with commas rather than repeating the flag — repeating a label is rejected client-side.

• --aggregation is table (default behavior when combined with --limit/

--sort-column/--sort-order) or timeseries. `--limit`, `--sort-column`, and `--sort-order` only apply to `table` — the backend silently ignores them for timeseries, so the CLI rejects that combination up front rather than sending a request whose flags are quietly dropped.

• entity-data percent-encodes the entity id for you — pass it as returned by

entities (e.g. checkout/api), quoted if it contains /.

Inspection Workflow

Four steps, and only because each one supplies an input the next one requires: entity-types gives valid <entity-type> values, schema gives valid --column ids, entities gives the entity-id for a drilldown.

1. Discover what entity types exist — never guess, they vary by account:

   cx service-catalog entity-types -o json

1. Check the schema for one entity type to find valid column ids and

filterable/groupable labels:

   cx service-catalog schema service -o json

1. List known entities of that type (e.g. service names):

   cx service-catalog entities service -o json

1. Query data — aggregated across all entities, or scoped to one. Column

ids, filter/group-by labels, and entity ids below are placeholders — always substitute values returned by schema/entities for the entity type in question, they vary by account and entity type:

   cx service-catalog data <entity-type> --start now-1h --end now \
     --column <column-id> --column <column-id> -o json

   cx service-catalog entity-data <entity-type> <entity-id> --start now-1h --end now \
     --column <column-id> -o json

Examples

The commands below use service and k8s-pod for concreteness, but every <column-id>, <filterable-label>, <groupable-label>, and <entity-id> must come from that entity type's own schema/entities output — never assume a column or label from one entity type exists on another.

Top 5 entities by a metric in the last hour

cx service-catalog schema service -o json  # discover column ids first
cx service-catalog data service --start now-1h --end now \
  --column <column-id> --aggregation table \
  --sort-column <column-id> --sort-order desc --limit 5 -o json

Filter to one label value

cx service-catalog schema service -o json  # discover filterable_labels first
cx service-catalog data service --start now-1h --end now \
  --column <column-id> --column <column-id> \
  --filter <filterable-label>=<value> -o json

Group by a label

cx service-catalog schema service -o json  # discover groupable_labels first
cx service-catalog data service --start now-1h --end now \
  --column <column-id> --group-by <groupable-label> -o json

Kubernetes pod resource saturation

cx service-catalog schema k8s-pod -o json  # discover column ids first
cx service-catalog data k8s-pod --start now-1h --end now \
  --column <column-id> --column <column-id> --column <column-id> -o json

Latency over time for one entity

cx service-catalog entities service -o json  # discover entity ids first
cx service-catalog entity-data service <entity-id> --start now-24h --end now \
  --column <column-id> --aggregation timeseries -o json

Just the rows

# Table responses live under .rows; timeseries under .series
cx service-catalog data service --start now-1h --end now \
  --column <column-id> -o json | jq '.rows'

Key Principles

• Discover before querying — entity-types and schema are cheap and

answer "what's valid here" before spending a data/entity-data call on a guess.

• `--column` values are per-entity-type — a column valid for service may

not exist for k8s-pod; always re-check schema when switching entity types.

• Malformed responses are errors, not silent empty results — a column that

is neither a value nor an error (or both) fails loudly rather than producing a partial or empty row, so a non-zero exit means investigate, not "no data".

• A column-level error is not a command failure — an individual column can

come back as {"error": "..."} inside an otherwise successful row (e.g. a query timeout for just that column); check per-column before assuming the whole request failed.

• `table` vs `timeseries` are mutually exclusive result shapes — table

responses are flat rows suitable for -o json | jq '.rows'; timeseries responses nest datapoints per series and are best consumed as raw JSON rather than forced into a table.

• Use `-o json` with `jq` for filtering; use -o toon for token-efficient

output in agent contexts.

• Multi-profile fan-out works on every subcommand — repeat -p <profile> to

compare the same entity type/data across accounts; rows and series are tagged with profile when more than one is given.

Related Skills

• `cx-infra` — infrastructure resource health (hosts, containers) is a

distinct concept from Service Catalog entity health; use cx-infra for host/instance-level monitoring and this skill for application/service-level APM entities.

• `cx-telemetry-querying` — once a service or pod name surfaces from this

skill's commands, pivot to raw telemetry: cx logs "filter $l.subsystemname == '<service>'" or cx search-fields "<name>" -s value to find related log/span fields. Correlate a latency or error spike with the underlying logs/spans.

• `cx-alerts` — cx alerts list --name "<service-name>" finds alert

definitions matching a service surfaced by this skill.

• `cx-dashboards` — cx dashboards search "<service-name> ..." finds

dashboards built around a service found here.