cx-service-catalog

服务目录技能

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

CLI 命令

命令	用途	关键标志
cx service-catalog entity-types	列出此账户有数据的实体类型	-
cx service-catalog schema <entity-type>	查看一种实体类型的列／标签架构	-
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 toon 输出结构化数据。
• 实体类型接受简写形式：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 可重复，但只能针对不同标签 （过滤条件之间使用 AND）；同一标签的多个值请用逗号组合，而不要重复该标志——客户端会拒绝重复的标签。
• --aggregation 可设为 table（与 --limit／--sort-column／--sort-order 结合时的默认行为）或 timeseries。--limit、--sort-column 和 --sort-order 仅适用于 table——后端会静默忽略它们在 timeseries 中的设置，因此 CLI 会提前拒绝这种组合，而不会发送一个标志会被悄然丢弃的请求。
• entity-data 会为你对实体 ID 进行百分号编码——请传入 entities 返回的原始值 （例如 checkout/api）；如果值中包含 /，请用引号括起来。

检查工作流

分为四个步骤，且每一步都提供了下一步所需的输入： entity-types 提供有效的 <entity-type> 值，schema 提供有效的 --column ID，entities 提供下钻所需的 entity-id。

1. 发现有哪些实体类型——切勿猜测，不同账户的类型可能不同：

   cx service-catalog entity-types -o json
   

2. 检查架构，找到一种实体类型的有效列 ID 和 可用于过滤／分组的标签：

   cx service-catalog schema service -o json
   

3. 列出该类型的已知实体（例如，服务名称）：

   cx service-catalog entities service -o json
   

4. 查询数据——汇总所有实体的数据，或限定到某一个实体。下方的列 ID、过滤／分组标签和实体 ID 都是占位符——请始终替换为 schema／entities 返回的、对应实体类型的值， 因为这些值因账户和实体类型而异：

   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
   

示例

以下命令使用 service 和 k8s-pod 作为示例，但每个 <column-id>、<filterable-label>、<groupable-label> 和 <entity-id> 都必须来自该实体类型自身的 schema／entities 输出——切勿假设一种实体类型的列或标签也存在于另一种实体类型中。

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

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

过滤到一个标签值

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

按标签分组

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 资源饱和度

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

查看一个实体随时间变化的延迟

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

仅显示行

# 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'

核心原则

• 先发现，再查询 —— 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 toon 获取更节省令牌的输出。
• 多配置文件扇出适用于每个子命令 —— 重复使用 -p <profile>，即可跨账户比较相同实体类型或数据；指定多个配置文件时，行和序列会附带 profile 标记。

相关技能

• cx-infra —— 基础设施资源健康状况（主机、容器）与 Service Catalog 实体健康状况是不同概念；主机/实例级监控请使用 cx-infra，应用/服务级 APM 实体请使用此技能。
• cx-telemetry-querying —— 此技能的命令显示服务或 Pod 名称后，可进一步查询原始遥测数据：使用 cx logs "filter $l.subsystemname == '<service>'"，或使用 cx search-fields "<name>" -s value 查找相关日志/跨度字段。将延迟或错误峰值与底层日志/跨度相关联。
• cx-alerts —— cx alerts list --name "<service-name>" 可查找与此技能发现的服务匹配的警报定义。
• cx-dashboards —— cx dashboards search "<service-name> ..." 可查找围绕此处发现的服务构建的仪表板。