@tsuga / cli

用于管理Tsuga资源的命令行接口。

安装

npm install -g @tsuga/cli

tsuga --help

更新

更新至最新发布的版本：

tsuga self-update

这个运行 npm install -g @tsuga/cli@latest。CLI还每天检查一次新版本，并在有新版本可用时打印通知。

壳完成

用制表符完成命令和标记 bash， zsh，或者 fish.

为 bash 和 zsh，将匹配的行添加到shell启动文件中：

# ~/.bashrc
eval "$(tsuga --completions bash)"

# ~/.zshrc
eval "$(tsuga --completions zsh)"

然后打开一个新的shell(或 source 文件)。

为 fish，将脚本写入完成目录：

tsuga --completions fish > ~/.config/fish/completions/tsuga.fish

鱼会自动把它装进新壳里。

身份验证

所有身份验证都在 tsuga auth.

以用户身份登录（推荐）

对于交互式使用，使用浏览器授权流程以用户身份登录：

# Opens your browser to an authorization URL, or prints the URL if it can't be opened.
tsuga auth login

# Print the saved user access token
tsuga auth token

# Show the saved authentication method, and when the session expires or expired
tsuga auth status

# Ask Tsuga which credential this CLI authenticates as, and what it is allowed to do
tsuga auth whoami

# Clear the saved user session
tsuga auth logout

后 tsuga auth login，命令在没有操作API密钥的情况下工作。会话更新自己，直到刷新令牌过期或被撤销。

操作API密钥

对于非交互式使用（CI、脚本），使用操作API密钥进行身份验证。从你的 Tsuga帐户设置，然后保存一次：

tsuga auth operation-key <OPERATION_API_KEY>

这将操作API密钥写入 $XDG_CONFIG_HOME/tsuga/config.json，或者 ~/.config/tsuga/config.json 当 XDG_CONFIG_HOME 是设置。或者，每个会话设置它而不保存：

export TSUGA_OPERATION_API_KEY=<OPERATION_API_KEY>

一、 TSUGA_OPERATION_API_KEY Env var覆盖为该调用保存的凭据。

配置

显示当前配置（包括默认值）：

tsuga config

使用数据

在交互式终端中，命令第一次执行成功时，CLI会询问是否发送使用情况数据。 用 tsuga config set telemetry on (或 off）。 TSUGA_TELEMETRY=1 (或 0)将覆盖已保存的答案。

违约

命令具有内置默认值，因此您可以忽略常见标志：

持久覆盖默认值。给出的值是 --value：

tsuga config set default from --value=-1h
tsuga config set default query --value 'level:ERROR'

默认值存在于 from， to， query， max-results 和 cluster (见 集群）; 任何其他名称都将被拒绝。 from 和 to 必须是有效的 时间 和 max-results 一个正整数，因此在设置默认值时报告拼写错误，而不是在以后的每个命令中报告。

当前默认值按 tsuga config (自定义覆盖标记为 *）。

重置所有自定义默认值：

tsuga config reset defaults

通过将单个默认值设置为空值来清除它。它的内置默认值，如果有，将再次应用：

tsuga config set default cluster --value ''

集群

如果您的租户有多个集群，请列出它们：

tsuga clusters list

通过默认机制选择你想默认使用的集群：

tsuga config set default cluster --value <CLUSTER_ID>

覆盖每个命令而不持久化：

# Environment variable
export TSUGA_CLUSTER_ID=<CLUSTER_ID>

# CLI flag (highest priority)
tsuga --cluster <CLUSTER_ID> logs search

优先顺序: --cluster 国旗→ TSUGA_CLUSTER_ID 环境变量→ defaults.cluster。如果不设置，则单集群组织使用其集群；如果有多个集群，遥测和资源命令将失败，并列出要选择的集群。

使用

大多数资源遵循相同的CRUD模式：

tsuga <RESOURCE> list
tsuga <RESOURCE> get <ID>
tsuga <RESOURCE> create -f payload.json
tsuga <RESOURCE> update <ID> -f payload.json
tsuga <RESOURCE> delete <ID>

也可以内联地传递JSON -d。命令从 -f 或者 -d，从不两者兼而有之；

tsuga teams create -d '{"name": "platform", "visibility": "public"}'

分页

list 默认情况下返回前100项。接受分页资源 --limit （最多1000）和 --offset：

tsuga monitors list --limit 500
tsuga monitors list --limit 500 --offset 500

# Follow every page and print one list
tsuga monitors list --all

当页面留下了项时，CLI打印一个通知 stderr 叶子是 纯JSON，所以 | jq 和 -o csv 不受影响:

Showing 100 of 4212 (offset 0). Use --limit (max 1000) and --offset 100 for the next page.

对于具有服务器端过滤器的资源，缩小查询范围胜过对所有内容进行分页。

可用的资源

adaptive-notification-rules， cloud-resources， custom-roles， dashboard-folders， dashboards， ingestion-api-keys， investigations， log-routes， metric-routes， monitor-folders， monitors， notification-integrations， notification-rules， notification-silences， public-tokens， quality-reports， retention-policies， services， slos， tag-policies， team-memberships， teams， users

注:

• ingestion-api-keys 不支持 get <ID>.
• services 和 users 是只读的(list， get）。
• cloud-resources 只读，仅支持 list.
• quality-reports 是只读的并且支持 list 加上 examples <ID>.
• team-memberships 支持 list， create 和 delete. delete 需要一个 {userId, teamId} body而不是ID。
• investigations 是测试版：它需要一个操作API密钥与 investigations 权限和API可能会更改。
• public-tokens 管理在浏览器和移动sdk中配置的RUM公共令牌。的操作API密钥 RUM公共代币 （rum-public-token)许可。

tsuga public-tokens create --generate-skeleton > app.json
# edit app.json
tsuga public-tokens create -f app.json | jq -r .token
tsuga public-tokens list | jq -r '.[0].token'

生成请求骨架

任何 create 或者 update 命令接受 --generate-skeleton 打印预期请求体的JSON模板：

tsuga monitors create --generate-skeleton
tsuga notification-rules update abc-123 --generate-skeleton

将输出管道输出到一个文件，将其填充，然后将其传递回 -f：

tsuga monitors create --generate-skeleton > monitor.json
# edit monitor.json
tsuga monitors create -f monitor.json

遥测

时间格式

使用等号表示负偏移量，例如 --from=-1h.

--from 和 --to 接受下列任何一项：

从一个狭窄的窗口开始，只有当结果为空时才逐步扩大它。每个查询都在您的集群上运行，而广泛的未过滤扫描会减慢每个人的速度。

搜索日志

tsuga logs search --from=-1h --query 'level:ERROR'
tsuga logs search --from 1704067200 --to 1704153600 --query 'context.service.name:api'

# JSON array projected to selected fields (preserves nested objects)
tsuga logs search --from=-10m \
  --fields timestamp,level,message,context.k8s.pod.name

# TSV with default columns: timestamp, level, message
tsuga logs search --from=-10m --query 'level:ERROR' -o tsv

# CSV with custom columns
tsuga logs search --from=-10m -o csv \
  --fields timestamp,level,message,context.k8s.pod.name

日志属性

tsuga logs attributes --from=-1h

# Only dot-paths containing "k8s", case-insensitively
tsuga logs attributes --from=-1h --search k8s

日志模式

# Group recent logs into patterns
tsuga logs patterns --from=-1h --query 'level:ERROR'

# List new error patterns observed in the time range
tsuga logs new-error-patterns --from=-24h --team my-team --service api --env prod

# List error patterns whose volume increased for a team
tsuga logs error-pattern-increases --from=-24h --team my-team --env prod

搜索痕迹

tsuga traces search --from=-30m --query 'span.name:GET'

# TSV with default columns: start_time, duration, context.service.name, span.name, status_code, trace_id
tsuga traces search --from=-30m --query 'span.name:GET' -o tsv

搜索RUM事件

为查询字段加上它们所属的流(measurements.， events.，或者 exceptions.)，并在每个查询上过滤一个流。不带前缀字段的查询，包括 默认的 *，搜索 events 流:

tsuga rum search --from=-1h --query 'events.view.name:/checkout'
tsuga rum search --from=-1h --query 'exceptions.exception.type:*' --max-results 20

朗姆酒的属性

列出您可以查询的每个RUM属性：

tsuga rum attributes

两个RUM命令都需要操作API密钥 朗姆酒的事件 （rum)读权限。

总结跟踪

将相似跨度的组聚合为合成的汇总跨度(标记为 span_attributes.aggregation.is_summary)以获得大轨迹的紧凑视图；

tsuga traces summarize --trace-id 78c99c5bb1e4a30297fa134b9dbec64f --from=-30m

跟踪延迟汇总

在跟踪中总结挂钟时间花费的位置：时间线的每个片段 归因于具有活动叶跨度的服务，每个服务的总数：

tsuga traces latency-summary --trace-id 78c99c5bb1e4a30297fa134b9dbec64f --from=-30m

对比组

将目标组的跨度与基线进行比较，并返回属性 在目标中被过度表示的值——这些跨度有什么共同点 而基线则不然。每个组都有自己的过滤器和时间范围。

过滤器是用TQL编写的，TQL与 --query。时间范围为Unix秒。 错误跨越健康的范围：

tsuga traces contrast-sets -d '{
  "targetGroup":   {"filter": "context.service.name:checkout status_code:error", "timeRange": {"from": 1704067200, "to": 1704070800}},
  "baselineGroup": {"filter": "context.service.name:checkout NOT status_code:error", "timeRange": {"from": 1704067200, "to": 1704070800}}
}'

运行 tsuga traces contrast-sets --generate-skeleton 获取完整的请求正文。

指标

# List metrics, sorted by name, one page at a time
tsuga metrics list --from=-1h --limit 500 --offset 1000

# List metrics whose name contains "http" (case-insensitive)
tsuga metrics list --from=-1h --search http

# Get a specific metric
tsuga metrics get my.metric.name --from=-1h

# List dashboards and monitors that use a metric
tsuga metrics assets-usage my.metric.name

聚合

使用JSON主体运行聚合查询：

tsuga aggregation scalar -f query.json
tsuga aggregation timeseries -f query.json

使用 --generate-skeleton 获取模板：

tsuga aggregation scalar --generate-skeleton > query.json

服务图

检查服务依赖关系图：

tsuga service-graph get <SERVICE_ID> --from=-1h --query 'env:prod'

Kubernetes

通过遥测，探索整个组织中观察到的Kubernetes资源：

tsuga kubernetes pods --search my-service
tsuga kubernetes clusters
tsuga kubernetes nodes --search ip-10-0
tsuga kubernetes events --search my-pod
tsuga kubernetes pod-details --k8s-cluster prod --k8s-namespace default --pod-name my-pod-abc123

可用资源: pods， clusters， namespaces， nodes， deployments， statefulsets， daemonsets， events (列表，带有可选的 --search), pod-details， pod-manifest， deployment-details （单资源查找，需要标识标志）。

队列

列出从生产者和消费者消息传递范围推断出的消息队列，以及它们的发布、消费和消费者错误率：

tsuga queues list --env prod --stats-window 24h
tsuga queues get --name orders --messaging-system kafka --env prod

心意相通

在日志路由中使用示例日志行之前，测试grok解析规则：

tsuga grok parse --generate-skeleton > grok-test.json
# edit grok-test.json
tsuga grok parse -f grok-test.json

PromQL

对指标后端运行一个PromQL查询。返回时间序列形状匹配 tsuga aggregation timeseries.

tsuga promql query --generate-skeleton > query.json
# edit query.json
tsuga promql query -f query.json

或内联:

tsuga promql query -d '{"query":"sum by (\"context.service.name\") (sum_over_time({\"traces.span.metrics.calls\", \"span.kind\"=\"SPAN_KIND_SERVER\"}[5m]))","timeRange":{"from":1704067200,"to":1704070800},"step":"30s"}'

timeRange.from / timeRange.to 是以秒为单位的Unix时间戳。

连续的分析

# Rank functions by self (flat) and inclusive (cum) sample value, like `go tool pprof -top`
tsuga profiles top --service api --type cpu --from=-1h
tsuga profiles top --service api --type alloc_space --from=-1h --limit 10 -o tsv

# Download the merged profile as raw pprof protobuf and open it with pprof
tsuga profiles pprof --service api --type cpu --from=-1h -O cpu.pb
go tool pprof -http=: cpu.pb

# Raw folded stacks (`root;...;leaf` with a value), with the usual -f / -d / --generate-skeleton
tsuga profiles query -d '{"service":"api","type":"cpu","timeRange":{"from":1704067200,"to":1704070800}}'

--type pprof示例类型是否为 cpu， samples， wall， off_cpu， alloc_space， inuse_space， alloc_objects， inuse_objects，或者 goroutine. --filter 对配置文件标签进行Tsuga查询；只接受标签相等、反和通配符。

LLM遥测

配置本地Claude代码(~/.claude/settings.json)或法典(~/.codex/config.toml)将OpenTelemetry数据发送到Tsuga集群。需要OTLP基础URL和 摄入API密钥 （与您的操作API密钥不同）。

tsuga setup claude-code --endpoint <OTLP_ENDPOINT> --ingestion-api-key <INGESTION_API_KEY>
tsuga setup codex --endpoint <OTLP_ENDPOINT> --ingestion-api-key <INGESTION_API_KEY>

这两个选项也从env (TSUGA_OTLP_ENDPOINT， TSUGA_INGESTION_API_KEY）. 通过 --no-include-prompts 从遥测中剥离用户提示（默认：include）；为 claude-code 这也剥离了工具内容，但是 codex 只删除用户提示。之前的配置备份在文件旁边；重新启动任何运行 claude / codex 会议之后。

LLM插件

tsuga install plugin claude-code
tsuga install plugin codex

添加了 tsuga 市场(tsuga-dev/agent-plugins)，并安装 tsuga 插件通过目标CLI (claude / codex 一定开着 PATH）. 对于《Claude Code》，它还开启了市场自动更新功能；通过 --no-auto-update 跳过。重新启动任何运行 claude / codex 会议之后。

分享链接

展开从Logs或Traces复制的短链接，或小部件共享链接，并解码其携带的查询、过滤器、时间范围、集群和Analytics设置。一个完整的 app.tsuga.com URL在没有API调用的情况下被本地解码：

tsuga unshorten https://app.tsuga.com/l/<CODE>
tsuga unshorten https://api.tsuga.com/v0/widget-shares/<ORG_ID>/<CODE>
tsuga unshorten 'https://app.tsuga.com/logs?query=level%3AERROR'

文档

搜索Tsuga文档和完整的API参考，然后通过path获取页面：

tsuga docs search 'log routes'
tsuga docs get explore/query-syntax
tsuga docs get api/aggregateScalar

反馈

报告与Tsuga工具或api的摩擦（失败的命令，不可用的输出，混乱的行为）：

tsuga feedback the traces command keeps timing out on large services

提示

默认输出是JSON，因此您可以管道到 jq：

tsuga dashboards list | jq '.[].name'
tsuga monitors list | jq '.[] | select(.priority == 1)'

从stdin中读取 -f -：

echo '{"name": "my-team", "visibility": "public"}' | tsuga teams create -f -

命令模式

tsuga schema 将命令树打印为JSON：命令路径、描述、位置参数和标志。