@tsuga/cli 1.35.0 → 1.37.0

package/README.md

@@ -220,7 +220,7 @@ tsuga logs patterns --rationale "exploring telemetry to investigate prod outage"
 
 ### Available resources
 
-`cloud-resources`, `dashboard-folders`, `dashboards`, `ingestion-api-keys`, `investigations`, `monitors`, `notification-integrations`, `notification-rules`, `notification-silences`, `quality-reports`, `retention-policies`, `log-routes`, `services`, `slos`, `tag-policies`, `teams`
+`cloud-resources`, `dashboard-folders`, `dashboards`, `ingestion-api-keys`, `investigations`, `monitors`, `notification-integrations`, `notification-rules`, `notification-silences`, `public-tokens`, `quality-reports`, `retention-policies`, `log-routes`, `services`, `slos`, `tag-policies`, `teams`
 
 > Notes:
 >
@@ -230,6 +230,14 @@ tsuga logs patterns --rationale "exploring telemetry to investigate prod outage"
 > - For `quality-reports list`, pass `--cluster <CLUSTER_ID>` (or set `TSUGA_CLUSTER_ID` / saved default) when the org has more than one cluster.
 > - Pass `--team <TEAM_NAME>` to `quality-reports list` to scope the response to a single team by name (omits cluster-wide global rows).
 > - `investigations` is beta: it requires an operation API key with the `investigations` permission and the API may change.
+> - `public-tokens` manages the RUM public tokens configured in browser and mobile SDKs. It requires an operation API key with the **RUM public tokens** (`rum-public-token`) permission.
+
+```bash
+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'
+```
 
 ### Generating a request skeleton
 
@@ -358,6 +366,67 @@ tsuga traces latency-summary --trace-id 78c99c5bb1e4a30297fa134b9dbec64f --from
 tsuga traces latency-summary --trace-id 78c99c5bb1e4a30297fa134b9dbec64f --from -30m --min-range-duration-ms 50
 ```
 
+### Contrast sets
+
+Compares a target group of spans against a baseline and returns the attribute
+values that are over-represented in the target — what those spans have in common
+that the baseline ones do not. Each group carries its own filter and time range.
+
+Filters are written in TQL, the same query language as `--query` elsewhere: terms
+are ANDed by whitespace, `span_attributes.*` addresses span attributes, and
+`duration` is in milliseconds. Run `tsuga docs get explore/query-syntax` for the
+full syntax.
+
+```bash
+tsuga traces contrast-sets --generate-skeleton > groups.json
+tsuga traces contrast-sets -f groups.json
+```
+
+Time ranges are Unix seconds, and unlike `--from` / `--to` they are not resolved
+from relative strings — the body takes numbers. The skeleton and the examples
+below carry a fixed window that is long past, so substitute your own:
+
+```bash
+TO=$(date +%s)
+FROM=$((TO - 3600))
+```
+
+Erroring spans against healthy ones, for one service in one window:
+
+```bash
+cat > groups.json <<EOF
+{
+  "targetGroup":   {"filter": "context.service.name:checkout status_code:error", "timeRange": {"from": $FROM, "to": $TO}},
+  "baselineGroup": {"filter": "context.service.name:checkout NOT status_code:error", "timeRange": {"from": $FROM, "to": $TO}}
+}
+EOF
+tsuga traces contrast-sets -f groups.json
+```
+
+Slow spans against normal-latency ones:
+
+```bash
+tsuga traces contrast-sets -d '{
+  "targetGroup":   {"filter": "context.service.name:checkout duration:>2000", "timeRange": {"from": 1704067200, "to": 1704070800}},
+  "baselineGroup": {"filter": "context.service.name:checkout duration:<500", "timeRange": {"from": 1704067200, "to": 1704070800}}
+}'
+```
+
+Before and after a deployment — same filter, two windows:
+
+```bash
+tsuga traces contrast-sets -d '{
+  "targetGroup":   {"filter": "context.service.name:checkout", "timeRange": {"from": 1704070800, "to": 1704074400}},
+  "baselineGroup": {"filter": "context.service.name:checkout", "timeRange": {"from": 1704063600, "to": 1704067200}}
+}'
+```
+
+Each returned value reports `targetSupport` and `baselineSupport` (the percentage
+of each group carrying it), `lift` (`targetSupport / baselineSupport`, omitted
+when the value never appears in the baseline), and `pValue`. Narrow the findings
+with `topK`, `minLift`, and `minSupport`; restrict the attributes tested with
+`candidateAttrs`.
+
 ### Metrics
 
 ```bash