@tsuga/cli 1.35.0 → 1.36.0

package/README.md

@@ -358,6 +358,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