cx-service-catalog

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Service Catalog Skill

Service Catalog 技能

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.

使用此技能可通过v2 Service Catalog API发现并查询Service Catalog实体——服务、数据库、操作、数据库操作、JVM、JVM GC、Kubernetes Pod和事务——以及它们的列指标（延迟、错误率、健康状态、资源使用率等）。

CLI Commands

CLI命令

Command	Purpose	Key flags
`cx service-catalog entity-types`	List entity types this account has data for	-
`cx service-catalog schema <entity-type>`	Columns/labels schema for one entity type	-
`cx service-catalog entities <entity-type>`	Known entities of one type (e.g. service names)	-
`cx service-catalog data <entity-type>`	Aggregated column data across every entity of a type	`--start` , `--end` , `--column` (required, repeatable); `--group-by` , `--filter` , `--aggregation` , `--limit` , `--sort-column` , `--sort-order`
`cx service-catalog entity-data <entity-type> <entity-id>`	Column data for one named entity (drilldown)	`--start` , `--end` , `--column` (required, repeatable); `--group-by` , `--filter` , `--aggregation`

All commands are read-only and support
```
-o json
```
/
```
-o agents
```
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
```
/
```
.

命令	用途	关键参数
`cx service-catalog entity-types`	列出当前账户有数据的实体类型	-
`cx service-catalog schema <entity-type>`	单个实体类型的列/标签schema	-
`cx service-catalog entities <entity-type>`	某一类型的已知实体（如服务名称）	-
`cx service-catalog data <entity-type>`	某一类型所有实体的聚合列数据	`--start` , `--end` , `--column` （必填，可重复）； `--group-by` , `--filter` , `--aggregation` , `--limit` , `--sort-column` , `--sort-order`
`cx service-catalog entity-data <entity-type> <entity-id>`	单个命名实体的列数据（钻取）	`--start` , `--end` , `--column` （必填，可重复）； `--group-by` , `--filter` , `--aggregation`

所有命令均为只读，并支持
```
-o json
```
/
```
-o agents
```
以输出结构化数据。
实体类型支持简写：
```
service
```
、
```
database
```
、
```
operation
```
、
```
database-operation
```
、
```
jvm
```
、
```
jvm-gc
```
、
```
k8s-pod
```
、
```
transaction
```
（大小写不敏感，连字符或下划线均可）。完整的proto名称（如
```
ENTITY_TYPE_K8S_POD
```
）同样有效。未知值会在发送请求前被客户端拒绝。
```
--start
```
/
```
--end
```
接受
```
now
```
、
```
now-1h
```
这类相对表达式，或RFC3339格式的时间戳。
```
--column
```
为必填项且可重复——需先通过
```
cx service-catalog schema <entity-type>
```
发现有效的列ID；API会拒绝未知的列ID。
```
--filter label=value1,value2
```
仅可针对不同标签重复使用（多个过滤器为逻辑与关系）；同一标签的多个值需用逗号组合，而非重复使用该参数——重复同一标签会被客户端拒绝。
```
--aggregation
```
可选值为
```
table
```
（当与
```
--limit
```
/
```
--sort-column
```
/
```
--sort-order
```
组合时的默认行为）或
```
timeseries
```
。--limit
、
--sort-column
和
--sort-order
仅适用于
table
模式——后端在
```
timeseries
```
模式下会静默忽略这些参数，因此CLI会提前拒绝这种组合，避免发送参数被悄悄丢弃的请求。
```
entity-data
```
会自动对实体ID进行百分号编码——直接传入
```
entities
```
命令返回的ID即可（如
```
checkout/api
```
），若包含
```
/
```
需加引号。

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.

Discover what entity types exist — never guess, they vary by account:
bash
```
cx service-catalog entity-types -o json
```
Check the schema for one entity type to find valid column ids and filterable/groupable labels:
bash
```
cx service-catalog schema service -o json
```
List known entities of that type (e.g. service names):
bash
```
cx service-catalog entities service -o json
```

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:

bash

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

分为四个步骤，每个步骤的输出作为下一个步骤的输入：

entity-types

提供有效的

<entity-type>

值，

schema

提供有效的

--column

ID，

entities

提供钻取所需的

entity-id

。

发现存在的实体类型——切勿猜测，不同账户的实体类型可能不同：
bash
```
cx service-catalog entity-types -o json
```
检查某一实体类型的schema，找到有效的列ID以及可过滤/可分组的标签：
bash
```
cx service-catalog schema service -o json
```
列出该类型的已知实体（如服务名称）：
bash
```
cx service-catalog entities service -o json
```
查询数据——可针对所有实体的聚合数据，或单个实体的专属数据。以下示例中的列ID、过滤器标签、分组标签和实体ID均为占位符——需始终替换为对应实体类型的
```
schema
```
/
```
entities
```
命令返回的值，不同账户和实体类型的值可能不同：
bash
```
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.

以下命令以

service

和

k8s-pod

为例，但所有

<column-id>

、

<filterable-label>

、

<groupable-label>

和

<entity-id>

均需来自对应实体类型的

schema

entities

输出——切勿假设某一实体类型的列或标签在另一实体类型中存在。

Top 5 entities by a metric in the last hour

过去一小时内指标排名前5的实体

bash

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

bash

cx service-catalog schema service -o json  # 先发现列ID
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

过滤到单个标签值

bash

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

bash

cx service-catalog schema service -o json  # 先发现可过滤标签
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

按标签分组

bash

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

bash

cx service-catalog schema service -o json  # 先发现可分组标签
cx service-catalog data service --start now-1h --end now \
  --column <column-id> --group-by <groupable-label> -o json

Kubernetes pod resource saturation

Kubernetes Pod资源饱和度

bash

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

bash

cx service-catalog schema k8s-pod -o json  # 先发现列ID
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

单个实体的延迟随时间变化

bash

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

bash

cx service-catalog entities service -o json  # 先发现实体ID
cx service-catalog entity-data service <entity-id> --start now-24h --end now \
  --column <column-id> --aggregation timeseries -o json

Just the rows

仅获取行数据

bash

undefined

bash

undefined

Table responses live under .rows; timeseries under .series

表格响应位于.rows下；时间序列响应位于.series下

cx service-catalog data service --start now-1h --end now
--column <column-id> -o json | jq '.rows'

undefined

cx service-catalog data service --start now-1h --end now
--column <column-id> -o json | jq '.rows'

undefined

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 agents
```
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.

先发现再查询——
```
entity-types
```
和
```
schema
```
命令开销低，能在发起
```
data
```
/
```
entity-data
```
查询前回答“此处哪些内容是有效的”，避免盲目猜测。
--column
值与实体类型绑定——某一实体类型（如
```
service
```
）有效的列，在另一实体类型（如
```
k8s-pod
```
）中可能不存在；切换实体类型时务必重新检查
```
schema
```
。
格式错误的响应会触发错误，而非静默返回空结果——若某列既非有效值也非错误（或两者皆是），会直接报错，而非返回部分或空行；因此非零退出码意味着需要排查问题，而非“无数据”。
列级错误不代表命令执行失败——单个列可能在成功返回的行中显示为
```
{"error": "..."}
```
（例如仅该列查询超时）；在假设整个请求失败前，需检查每一列的状态。
table
与
timeseries
是互斥的结果格式——
```
table
```
响应是扁平的行数据，适合通过
```
-o json | jq '.rows'
```
处理；
```
timeseries
```
响应按序列嵌套数据点，最好直接以原始JSON格式使用，而非强行转换为表格。
结合
-o json
与
jq
进行过滤；在Agent环境中使用
```
-o agents
```
以获得高效的令牌输出。
多配置文件扩展适用于所有子命令——重复使用
```
-p <profile>
```
可跨账户比较同一实体类型/数据；当指定多个配置文件时，行和序列会标记对应的
```
profile
```
。

cx-service-catalog

Original

Translation

Service Catalog Skill

Service Catalog 技能

CLI Commands

CLI命令

Inspection Workflow

检查流程

Examples

示例

Top 5 entities by a metric in the last hour

过去一小时内指标排名前5的实体

Filter to one label value

过滤到单个标签值

Group by a label

按标签分组

Kubernetes pod resource saturation

Kubernetes Pod资源饱和度

Latency over time for one entity

单个实体的延迟随时间变化

Just the rows

仅获取行数据

Table responses live under .rows; timeseries under .series

表格响应位于.rows下；时间序列响应位于.series下

Key Principles

核心原则

Related Skills

相关技能