cx-service-catalog

name: cx-service-catalog description: > Query Coralogix's Service Catalog (APM v2 entities) with the cx service-catalog CLI — discover entity types, list known entities, check their schema, and pull aggregated or timeseries data for services, databases, operations, JVMs, and Kubernetes pods. Use when the user asks to "list services", "what entity types exist", "show me service latency", "check error rate for a service", "which pods are using the most memory", "database operation performance", "JVM GC pauses", "service health over time", "compare services by latency", "what columns are available for this entity type", "service catalog schema", or wants to explore APM entities and their metrics. metadata: version: "0.1.0"

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
   

2. Check the schema for one entity type to find valid column ids and filterable/groupable labels:

   cx service-catalog schema service -o json
   

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

   cx service-catalog entities service -o json
   

4. 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.