@x12i/countex 1.8.5 → 1.10.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (105) hide show
  1. package/LICENSE +21 -21
  2. package/README.md +867 -860
  3. package/dist/cli.js +6 -6
  4. package/dist/core/countex.d.ts +61 -1
  5. package/dist/core/countex.d.ts.map +1 -1
  6. package/dist/core/countex.js +241 -0
  7. package/dist/core/countex.js.map +1 -1
  8. package/dist/core/managed.d.ts +200 -0
  9. package/dist/core/managed.d.ts.map +1 -0
  10. package/dist/core/managed.js +431 -0
  11. package/dist/core/managed.js.map +1 -0
  12. package/dist/core/timeframe.d.ts +5 -0
  13. package/dist/core/timeframe.d.ts.map +1 -1
  14. package/dist/core/timeframe.js +36 -0
  15. package/dist/core/timeframe.js.map +1 -1
  16. package/dist/index.d.ts +6 -2
  17. package/dist/index.d.ts.map +1 -1
  18. package/dist/index.js +9 -1
  19. package/dist/index.js.map +1 -1
  20. package/dist/insights/advisors/resource-advisor.d.ts.map +1 -1
  21. package/dist/insights/advisors/resource-advisor.js +5 -1
  22. package/dist/insights/advisors/resource-advisor.js.map +1 -1
  23. package/dist/insights/types.d.ts +4 -0
  24. package/dist/insights/types.d.ts.map +1 -1
  25. package/dist/storage/managed-memory.d.ts +33 -0
  26. package/dist/storage/managed-memory.d.ts.map +1 -0
  27. package/dist/storage/managed-memory.js +211 -0
  28. package/dist/storage/managed-memory.js.map +1 -0
  29. package/dist/storage/memory.d.ts +7 -4
  30. package/dist/storage/memory.d.ts.map +1 -1
  31. package/dist/storage/memory.js.map +1 -1
  32. package/dist/storage/postgres.d.ts +123 -0
  33. package/dist/storage/postgres.d.ts.map +1 -0
  34. package/dist/storage/postgres.js +1325 -0
  35. package/dist/storage/postgres.js.map +1 -0
  36. package/dist/storage/redis.d.ts +6 -0
  37. package/dist/storage/redis.d.ts.map +1 -1
  38. package/dist/storage/redis.js +21 -0
  39. package/dist/storage/redis.js.map +1 -1
  40. package/dist/types/index.d.ts +63 -5
  41. package/dist/types/index.d.ts.map +1 -1
  42. package/dist/utils/errors.d.ts +12 -0
  43. package/dist/utils/errors.d.ts.map +1 -1
  44. package/dist/utils/errors.js +22 -1
  45. package/dist/utils/errors.js.map +1 -1
  46. package/docs/DEPLOYMENT.md +399 -375
  47. package/docs/END_TO_END_EXAMPLE.md +316 -316
  48. package/docs/INSIGHTS.md +59 -59
  49. package/docs/INSIGHTS_ANOMALY_DETECTION.md +33 -33
  50. package/docs/INSIGHTS_LLM_COST_AND_TOKENS.md +26 -26
  51. package/docs/INSIGHTS_RESOURCE_ADVISOR.md +33 -31
  52. package/docs/countex_gap_analysis_complete_checklist.md +1340 -1340
  53. package/docs/guides/README.md +37 -34
  54. package/docs/guides/adapter-memory.md +60 -60
  55. package/docs/guides/adapter-mongo.md +64 -62
  56. package/docs/guides/adapter-postgres.md +92 -0
  57. package/docs/guides/adapter-redis.md +89 -89
  58. package/docs/guides/backup-export.md +135 -135
  59. package/docs/guides/cardinality.md +50 -50
  60. package/docs/guides/cli.md +53 -53
  61. package/docs/guides/client-events.md +65 -65
  62. package/docs/guides/counter-maps.md +160 -160
  63. package/docs/guides/idempotency.md +39 -39
  64. package/docs/guides/ingestion-and-flush.md +67 -67
  65. package/docs/guides/insights-advisors-and-optimization.md +39 -39
  66. package/docs/guides/insights-anomalies-and-rules.md +48 -48
  67. package/docs/guides/insights-comparison-and-trends.md +47 -47
  68. package/docs/guides/insights-forecasting-and-budget.md +61 -61
  69. package/docs/guides/insights-overview.md +82 -82
  70. package/docs/guides/insights-ranking.md +81 -81
  71. package/docs/guides/managed-commit.md +119 -0
  72. package/docs/guides/measures.md +72 -71
  73. package/docs/guides/migrating-mongo-to-postgres.md +127 -0
  74. package/docs/guides/preview.md +92 -92
  75. package/docs/guides/querying.md +178 -178
  76. package/docs/guides/simulation-profiles.md +33 -33
  77. package/docs/guides/simulation-resource-estimation.md +31 -30
  78. package/docs/guides/simulation.md +36 -36
  79. package/docs/guides/timeframes-and-bucketing.md +55 -55
  80. package/docs/internals/README.md +21 -21
  81. package/docs/internals/internal-architecture-overview.md +65 -65
  82. package/docs/internals/internal-backup-stream.md +23 -23
  83. package/docs/internals/internal-buffer-merge-and-flush.md +51 -51
  84. package/docs/internals/internal-cardinality.md +30 -30
  85. package/docs/internals/internal-dimension-hash.md +34 -34
  86. package/docs/internals/internal-idempotency.md +36 -36
  87. package/docs/internals/internal-ingest-pipeline.md +52 -52
  88. package/docs/internals/internal-insights-layer.md +36 -36
  89. package/docs/internals/internal-mapping-validation-and-extraction.md +59 -59
  90. package/docs/internals/internal-measures-and-scales.md +35 -35
  91. package/docs/internals/internal-query-path.md +46 -46
  92. package/docs/internals/internal-storage-memory.md +13 -13
  93. package/docs/internals/internal-storage-mongo.md +44 -44
  94. package/docs/internals/internal-storage-postgres.md +32 -0
  95. package/docs/internals/internal-storage-redis.md +63 -63
  96. package/docs/internals/internal-timeframe-bucketing.md +33 -33
  97. package/docs/use-cases/README.md +56 -56
  98. package/docs/use-cases/audit-security-log-counts.md +550 -550
  99. package/docs/use-cases/llm-cost-and-token-metering.md +255 -255
  100. package/docs/use-cases/multi-tenant-isolation.md +203 -203
  101. package/docs/use-cases/ops-dashboard-daily-rollups.md +255 -255
  102. package/docs/use-cases/processing-workflow-activity.md +165 -165
  103. package/docs/use-cases/product-feature-usage.md +240 -240
  104. package/docs/use-cases/webhook-idempotent-ingestion.md +188 -188
  105. package/package.json +190 -170
@@ -1,48 +1,48 @@
1
- # Guide: Insights — anomalies and rules
2
-
3
- Detect unusual periods relative to a baseline and evaluate declarative **rules** over stored aggregates.
4
-
5
- ## Step 1: Detect anomalies
6
-
7
- ```ts
8
- const { anomalies } = await insights.detectAnomalies({
9
- scope: "org_1",
10
- counterId: "usage",
11
- timeframe: { type: "day", from: "2026-05-01", to: "2026-05-14" },
12
- groupBy: [],
13
- measure: "count",
14
- baseline: {
15
- timeframe: { type: "day", from: "2026-04-01", to: "2026-04-30" },
16
- minBuckets: 12,
17
- },
18
- });
19
- ```
20
-
21
- Notes:
22
-
23
- - **`timeframe.type: "all"`** is not supported; you’ll receive an empty list and an `insufficient_data` event.
24
- - Emits **`anomaly`** events with severity for each finding.
25
-
26
- ## Step 2: Evaluate rules
27
-
28
- ```ts
29
- const rules = await insights.evaluateRules({
30
- scope: "org_1",
31
- counterId: "usage",
32
- timeframe: { type: "week", from: "2026-W18", to: "2026-W19" },
33
- rules: [
34
- {
35
- id: "spike_cost",
36
- when: { measure: "cost.sum", op: "gt", value: 10_000 },
37
- recommend: { title: "Investigate cost spike" },
38
- },
39
- ],
40
- });
41
- ```
42
-
43
- Rule evaluation reuses the insights query helper so timeouts and group caps stay consistent.
44
-
45
- ## See also
46
-
47
- - `docs/INSIGHTS_ANOMALY_DETECTION.md`
48
- - Internal: [Insights layer](../internals/internal-insights-layer.md)
1
+ # Guide: Insights — anomalies and rules
2
+
3
+ Detect unusual periods relative to a baseline and evaluate declarative **rules** over stored aggregates.
4
+
5
+ ## Step 1: Detect anomalies
6
+
7
+ ```ts
8
+ const { anomalies } = await insights.detectAnomalies({
9
+ scope: "org_1",
10
+ counterId: "usage",
11
+ timeframe: { type: "day", from: "2026-05-01", to: "2026-05-14" },
12
+ groupBy: [],
13
+ measure: "count",
14
+ baseline: {
15
+ timeframe: { type: "day", from: "2026-04-01", to: "2026-04-30" },
16
+ minBuckets: 12,
17
+ },
18
+ });
19
+ ```
20
+
21
+ Notes:
22
+
23
+ - **`timeframe.type: "all"`** is not supported; you’ll receive an empty list and an `insufficient_data` event.
24
+ - Emits **`anomaly`** events with severity for each finding.
25
+
26
+ ## Step 2: Evaluate rules
27
+
28
+ ```ts
29
+ const rules = await insights.evaluateRules({
30
+ scope: "org_1",
31
+ counterId: "usage",
32
+ timeframe: { type: "week", from: "2026-W18", to: "2026-W19" },
33
+ rules: [
34
+ {
35
+ id: "spike_cost",
36
+ when: { measure: "cost.sum", op: "gt", value: 10_000 },
37
+ recommend: { title: "Investigate cost spike" },
38
+ },
39
+ ],
40
+ });
41
+ ```
42
+
43
+ Rule evaluation reuses the insights query helper so timeouts and group caps stay consistent.
44
+
45
+ ## See also
46
+
47
+ - `docs/INSIGHTS_ANOMALY_DETECTION.md`
48
+ - Internal: [Insights layer](../internals/internal-insights-layer.md)
@@ -1,47 +1,47 @@
1
- # Guide: Insights — comparison and trends
2
-
3
- Compare two time windows or derive simple **trend** statistics from a timeseries query.
4
-
5
- ## Step 1: Compare periods
6
-
7
- ```ts
8
- const cmp = await insights.comparePeriods({
9
- scope: "org_1",
10
- counterId: "usage",
11
- current: { type: "day", from: "2026-05-08", to: "2026-05-08" },
12
- previous: { type: "day", from: "2026-05-07", to: "2026-05-07" },
13
- groupBy: ["metric"],
14
- measure: "count",
15
- minPercentChange: 10,
16
- minAbsoluteChange: 5,
17
- });
18
- ```
19
-
20
- The helper issues **two** queries (current and previous) and merges rows by group keys.
21
-
22
- ## Step 2: Trend from timeseries
23
-
24
- ```ts
25
- const trend = await insights.trend({
26
- scope: "org_1",
27
- counterId: "usage",
28
- timeframe: { type: "day", from: "2026-05-01", to: "2026-05-14" },
29
- groupBy: [],
30
- measure: "cost.sum",
31
- method: "linear",
32
- movingAverageWindow: 3,
33
- });
34
- ```
35
-
36
- Underlying query uses `format: "timeseries"`; post-processing computes growth / smoothing per configuration.
37
-
38
- ## Options shared with other insights
39
-
40
- - `filters` — subject/metric/dimension filters compatible with core queries
41
- - `bypassCache`, `signal`
42
- - `maxBuckets`, `maxGroups`
43
-
44
- ## See also
45
-
46
- - [Timeframes](./timeframes-and-bucketing.md)
47
- - Internal: [Insights layer](../internals/internal-insights-layer.md)
1
+ # Guide: Insights — comparison and trends
2
+
3
+ Compare two time windows or derive simple **trend** statistics from a timeseries query.
4
+
5
+ ## Step 1: Compare periods
6
+
7
+ ```ts
8
+ const cmp = await insights.comparePeriods({
9
+ scope: "org_1",
10
+ counterId: "usage",
11
+ current: { type: "day", from: "2026-05-08", to: "2026-05-08" },
12
+ previous: { type: "day", from: "2026-05-07", to: "2026-05-07" },
13
+ groupBy: ["metric"],
14
+ measure: "count",
15
+ minPercentChange: 10,
16
+ minAbsoluteChange: 5,
17
+ });
18
+ ```
19
+
20
+ The helper issues **two** queries (current and previous) and merges rows by group keys.
21
+
22
+ ## Step 2: Trend from timeseries
23
+
24
+ ```ts
25
+ const trend = await insights.trend({
26
+ scope: "org_1",
27
+ counterId: "usage",
28
+ timeframe: { type: "day", from: "2026-05-01", to: "2026-05-14" },
29
+ groupBy: [],
30
+ measure: "cost.sum",
31
+ method: "linear",
32
+ movingAverageWindow: 3,
33
+ });
34
+ ```
35
+
36
+ Underlying query uses `format: "timeseries"`; post-processing computes growth / smoothing per configuration.
37
+
38
+ ## Options shared with other insights
39
+
40
+ - `filters` — subject/metric/dimension filters compatible with core queries
41
+ - `bypassCache`, `signal`
42
+ - `maxBuckets`, `maxGroups`
43
+
44
+ ## See also
45
+
46
+ - [Timeframes](./timeframes-and-bucketing.md)
47
+ - Internal: [Insights layer](../internals/internal-insights-layer.md)
@@ -1,61 +1,61 @@
1
- # Guide: Insights — forecasting and budget
2
-
3
- Forecast simple forward curves and relate measures to **budgets**, **cost drivers**, and **token ceilings**.
4
-
5
- ## Step 1: Forecast
6
-
7
- ```ts
8
- const fc = await insights.forecast({
9
- scope: "org_1",
10
- counterId: "usage",
11
- timeframe: { type: "day", from: "2026-05-01", to: "2026-05-14" },
12
- measure: "count",
13
- horizonBuckets: 7,
14
- });
15
- ```
16
-
17
- Recommendations may emit `recommendation` events on the insights client.
18
-
19
- ## Step 2: Budget projection
20
-
21
- ```ts
22
- const budget = await insights.budgetProjection({
23
- scope: "org_1",
24
- counterId: "usage",
25
- timeframe: { type: "month", from: "2026-05", to: "2026-05" },
26
- measure: "cost.sum",
27
- budget: 50_000,
28
- });
29
- ```
30
-
31
- ## Step 3: Cost drivers
32
-
33
- ```ts
34
- const drivers = await insights.costDrivers({
35
- scope: "org_1",
36
- counterId: "usage",
37
- timeframe: { type: "month", from: "2026-05", to: "2026-05" },
38
- groupBy: ["subject", "dim:model"],
39
- measure: "cost.sum",
40
- });
41
- ```
42
-
43
- ## Step 4: Token recommendations
44
-
45
- ```ts
46
- const tokens = await insights.recommendMaxTokens({
47
- scope: "org_1",
48
- counterId: "usage",
49
- timeframe: { type: "day", from: "2026-05-08", to: "2026-05-08" },
50
- groupBy: ["dim:model"],
51
- outputTokenMeasure: "outputTokens",
52
- safetyFactor: 1.2,
53
- });
54
- ```
55
-
56
- Measure names must exist on your map / cells.
57
-
58
- ## See also
59
-
60
- - `docs/INSIGHTS_LLM_COST_AND_TOKENS.md`
61
- - Internal: [Insights layer](../internals/internal-insights-layer.md)
1
+ # Guide: Insights — forecasting and budget
2
+
3
+ Forecast simple forward curves and relate measures to **budgets**, **cost drivers**, and **token ceilings**.
4
+
5
+ ## Step 1: Forecast
6
+
7
+ ```ts
8
+ const fc = await insights.forecast({
9
+ scope: "org_1",
10
+ counterId: "usage",
11
+ timeframe: { type: "day", from: "2026-05-01", to: "2026-05-14" },
12
+ measure: "count",
13
+ horizonBuckets: 7,
14
+ });
15
+ ```
16
+
17
+ Recommendations may emit `recommendation` events on the insights client.
18
+
19
+ ## Step 2: Budget projection
20
+
21
+ ```ts
22
+ const budget = await insights.budgetProjection({
23
+ scope: "org_1",
24
+ counterId: "usage",
25
+ timeframe: { type: "month", from: "2026-05", to: "2026-05" },
26
+ measure: "cost.sum",
27
+ budget: 50_000,
28
+ });
29
+ ```
30
+
31
+ ## Step 3: Cost drivers
32
+
33
+ ```ts
34
+ const drivers = await insights.costDrivers({
35
+ scope: "org_1",
36
+ counterId: "usage",
37
+ timeframe: { type: "month", from: "2026-05", to: "2026-05" },
38
+ groupBy: ["subject", "dim:model"],
39
+ measure: "cost.sum",
40
+ });
41
+ ```
42
+
43
+ ## Step 4: Token recommendations
44
+
45
+ ```ts
46
+ const tokens = await insights.recommendMaxTokens({
47
+ scope: "org_1",
48
+ counterId: "usage",
49
+ timeframe: { type: "day", from: "2026-05-08", to: "2026-05-08" },
50
+ groupBy: ["dim:model"],
51
+ outputTokenMeasure: "outputTokens",
52
+ safetyFactor: 1.2,
53
+ });
54
+ ```
55
+
56
+ Measure names must exist on your map / cells.
57
+
58
+ ## See also
59
+
60
+ - `docs/INSIGHTS_LLM_COST_AND_TOKENS.md`
61
+ - Internal: [Insights layer](../internals/internal-insights-layer.md)
@@ -1,82 +1,82 @@
1
- # Guide: Insights overview
2
-
3
- The **`@x12i/countex/insights`** module layers ranking, comparison, anomaly detection, forecasting, and advisory helpers on top of ordinary `countex.query` results.
4
-
5
- ## Step 1: Install / import
6
-
7
- ```ts
8
- import { createCountexInsights } from "@x12i/countex/insights";
9
- ```
10
-
11
- No extra peer dependencies beyond what your core Countex setup already uses.
12
-
13
- ## Step 2: Construct insights with your Countex client
14
-
15
- ```ts
16
- const insights = createCountexInsights({
17
- countex,
18
- durable, // optional; required only for estimateResourcesFromActuals
19
- mapsByCounterId: new Map(maps.map((m) => [m.counterId, m])),
20
- defaults: {
21
- maxGroups: 10_000,
22
- maxBuckets: 10_000,
23
- queryTimeoutMs: 10_000,
24
- minBaselineBuckets: 12,
25
- resultLimit: 1_000,
26
- },
27
- });
28
- ```
29
-
30
- Passing **`mapsByCounterId`** enables map-aware advisors (for example map health).
31
-
32
- ## Step 3: Run an insight
33
-
34
- Each method ultimately builds a `QuerySpec`, calls `client.query`, then post-processes rows.
35
-
36
- ```ts
37
- const top = await insights.topN({
38
- scope: "org_1",
39
- counterId: "llm_usage",
40
- timeframe: { type: "month", from: "2026-05", to: "2026-05" },
41
- groupBy: ["subject"],
42
- measure: "cost.sum",
43
- n: 10,
44
- });
45
- ```
46
-
47
- ## Step 4: Observe insight lifecycle events
48
-
49
- `CountexInsights` emits:
50
-
51
- - `insight_query` — timing per underlying query
52
- - `anomaly`, `recommendation`, `insufficient_data` — depending on method
53
-
54
- ```ts
55
- insights.on("insight_query", (e) => console.log(e));
56
- ```
57
-
58
- ## Step 5: Respect limits
59
-
60
- Insights honor **`maxBuckets`** (aligned with core query expansion) and **`maxGroups`**. Prefer narrower filters when grouping heavily.
61
-
62
- ## Distributions, percentiles, and histograms
63
-
64
- Core Countex cells store **additive** measure aggregates (`sum`, `count`, `min`, `max`) per sparse cell — not full distributions. Insights therefore reason about **rankings, deltas, thresholds, and derived averages**, not arbitrary percentile curves across arbitrary slices unless you add **explicit** histogram or sketch storage elsewhere.
65
-
66
- Token and latency **advisors** use those summaries (and sometimes robust z-scores on bucketed series); treat percentile-style language in recommendations as **heuristic** unless you extend storage.
67
-
68
- ## Feature map
69
-
70
- | Area | Methods |
71
- |------|---------|
72
- | Ranking | `topN`, `bottomN`, `topPercent`, `bottomPercent`, `pareto`, `contribution` |
73
- | Comparison | `comparePeriods`, `trend` |
74
- | Anomalies & rules | `detectAnomalies`, `evaluateRules` |
75
- | Forecast & budget | `forecast`, `budgetProjection`, `costDrivers`, `recommendMaxTokens` |
76
- | Advisors | `analyzeMapHealth`, `estimateResourcesFromActuals` |
77
-
78
- ## See also
79
-
80
- - Domain-focused narratives: `docs/INSIGHTS.md`, `docs/INSIGHTS_ANOMALY_DETECTION.md`, etc.
81
- - [Ranking](./insights-ranking.md)
82
- - Internal: [Insights layer](../internals/internal-insights-layer.md)
1
+ # Guide: Insights overview
2
+
3
+ The **`@x12i/countex/insights`** module layers ranking, comparison, anomaly detection, forecasting, and advisory helpers on top of ordinary `countex.query` results.
4
+
5
+ ## Step 1: Install / import
6
+
7
+ ```ts
8
+ import { createCountexInsights } from "@x12i/countex/insights";
9
+ ```
10
+
11
+ No extra peer dependencies beyond what your core Countex setup already uses.
12
+
13
+ ## Step 2: Construct insights with your Countex client
14
+
15
+ ```ts
16
+ const insights = createCountexInsights({
17
+ countex,
18
+ durable, // optional; required only for estimateResourcesFromActuals
19
+ mapsByCounterId: new Map(maps.map((m) => [m.counterId, m])),
20
+ defaults: {
21
+ maxGroups: 10_000,
22
+ maxBuckets: 10_000,
23
+ queryTimeoutMs: 10_000,
24
+ minBaselineBuckets: 12,
25
+ resultLimit: 1_000,
26
+ },
27
+ });
28
+ ```
29
+
30
+ Passing **`mapsByCounterId`** enables map-aware advisors (for example map health).
31
+
32
+ ## Step 3: Run an insight
33
+
34
+ Each method ultimately builds a `QuerySpec`, calls `client.query`, then post-processes rows.
35
+
36
+ ```ts
37
+ const top = await insights.topN({
38
+ scope: "org_1",
39
+ counterId: "llm_usage",
40
+ timeframe: { type: "month", from: "2026-05", to: "2026-05" },
41
+ groupBy: ["subject"],
42
+ measure: "cost.sum",
43
+ n: 10,
44
+ });
45
+ ```
46
+
47
+ ## Step 4: Observe insight lifecycle events
48
+
49
+ `CountexInsights` emits:
50
+
51
+ - `insight_query` — timing per underlying query
52
+ - `anomaly`, `recommendation`, `insufficient_data` — depending on method
53
+
54
+ ```ts
55
+ insights.on("insight_query", (e) => console.log(e));
56
+ ```
57
+
58
+ ## Step 5: Respect limits
59
+
60
+ Insights honor **`maxBuckets`** (aligned with core query expansion) and **`maxGroups`**. Prefer narrower filters when grouping heavily.
61
+
62
+ ## Distributions, percentiles, and histograms
63
+
64
+ Core Countex cells store **additive** measure aggregates (`sum`, `count`, `min`, `max`) per sparse cell — not full distributions. Insights therefore reason about **rankings, deltas, thresholds, and derived averages**, not arbitrary percentile curves across arbitrary slices unless you add **explicit** histogram or sketch storage elsewhere.
65
+
66
+ Token and latency **advisors** use those summaries (and sometimes robust z-scores on bucketed series); treat percentile-style language in recommendations as **heuristic** unless you extend storage.
67
+
68
+ ## Feature map
69
+
70
+ | Area | Methods |
71
+ |------|---------|
72
+ | Ranking | `topN`, `bottomN`, `topPercent`, `bottomPercent`, `pareto`, `contribution` |
73
+ | Comparison | `comparePeriods`, `trend` |
74
+ | Anomalies & rules | `detectAnomalies`, `evaluateRules` |
75
+ | Forecast & budget | `forecast`, `budgetProjection`, `costDrivers`, `recommendMaxTokens` |
76
+ | Advisors | `analyzeMapHealth`, `estimateResourcesFromActuals` |
77
+
78
+ ## See also
79
+
80
+ - Domain-focused narratives: `docs/INSIGHTS.md`, `docs/INSIGHTS_ANOMALY_DETECTION.md`, etc.
81
+ - [Ranking](./insights-ranking.md)
82
+ - Internal: [Insights layer](../internals/internal-insights-layer.md)
@@ -1,81 +1,81 @@
1
- # Guide: Insights — ranking
2
-
3
- Ranking helpers turn grouped query rows into **top/bottom lists**, **percent slices**, **Pareto** views, and **contribution** summaries.
4
-
5
- ## Prerequisites
6
-
7
- - A `CountexInsights` instance — see [Insights overview](./insights-overview.md).
8
- - A measure selector string such as `"count"` or `"cost.sum"`.
9
-
10
- ## Step 1: Top N
11
-
12
- ```ts
13
- const out = await insights.topN({
14
- scope: "org_1",
15
- counterId: "usage",
16
- timeframe: { type: "day", from: "2026-05-01", to: "2026-05-07" },
17
- groupBy: ["metric"],
18
- measure: "count",
19
- n: 10,
20
- includeTotal: true,
21
- });
22
- ```
23
-
24
- ## Step 2: Bottom N
25
-
26
- ```ts
27
- const out = await insights.bottomN({
28
- scope: "org_1",
29
- counterId: "usage",
30
- timeframe: { type: "day", from: "2026-05-01", to: "2026-05-07" },
31
- groupBy: ["dim:region"],
32
- measure: "latencyMs.avg",
33
- n: 5,
34
- includeZeroes: false,
35
- });
36
- ```
37
-
38
- Sparse counters omit zero rows unless you opt in.
39
-
40
- ## Step 3: Top / bottom percent slices
41
-
42
- ```ts
43
- const slice = await insights.topPercent({
44
- scope: "org_1",
45
- counterId: "usage",
46
- timeframe: { type: "month", from: "2026-05", to: "2026-05" },
47
- groupBy: ["subject"],
48
- measure: "cost.sum",
49
- percent: 20,
50
- });
51
- ```
52
-
53
- ## Step 4: Pareto
54
-
55
- ```ts
56
- const pareto = await insights.pareto({
57
- scope: "org_1",
58
- counterId: "usage",
59
- timeframe: { type: "month", from: "2026-05", to: "2026-05" },
60
- groupBy: ["subject"],
61
- measure: "cost.sum",
62
- targetShare: 0.8,
63
- });
64
- ```
65
-
66
- ## Step 5: Contribution
67
-
68
- ```ts
69
- const contrib = await insights.contribution({
70
- scope: "org_1",
71
- counterId: "usage",
72
- timeframe: { type: "month", from: "2026-05", to: "2026-05" },
73
- groupBy: ["dim:model"],
74
- measure: "tokens.sum",
75
- });
76
- ```
77
-
78
- ## See also
79
-
80
- - [Querying](./querying.md)
81
- - Internal: [Insights layer](../internals/internal-insights-layer.md)
1
+ # Guide: Insights — ranking
2
+
3
+ Ranking helpers turn grouped query rows into **top/bottom lists**, **percent slices**, **Pareto** views, and **contribution** summaries.
4
+
5
+ ## Prerequisites
6
+
7
+ - A `CountexInsights` instance — see [Insights overview](./insights-overview.md).
8
+ - A measure selector string such as `"count"` or `"cost.sum"`.
9
+
10
+ ## Step 1: Top N
11
+
12
+ ```ts
13
+ const out = await insights.topN({
14
+ scope: "org_1",
15
+ counterId: "usage",
16
+ timeframe: { type: "day", from: "2026-05-01", to: "2026-05-07" },
17
+ groupBy: ["metric"],
18
+ measure: "count",
19
+ n: 10,
20
+ includeTotal: true,
21
+ });
22
+ ```
23
+
24
+ ## Step 2: Bottom N
25
+
26
+ ```ts
27
+ const out = await insights.bottomN({
28
+ scope: "org_1",
29
+ counterId: "usage",
30
+ timeframe: { type: "day", from: "2026-05-01", to: "2026-05-07" },
31
+ groupBy: ["dim:region"],
32
+ measure: "latencyMs.avg",
33
+ n: 5,
34
+ includeZeroes: false,
35
+ });
36
+ ```
37
+
38
+ Sparse counters omit zero rows unless you opt in.
39
+
40
+ ## Step 3: Top / bottom percent slices
41
+
42
+ ```ts
43
+ const slice = await insights.topPercent({
44
+ scope: "org_1",
45
+ counterId: "usage",
46
+ timeframe: { type: "month", from: "2026-05", to: "2026-05" },
47
+ groupBy: ["subject"],
48
+ measure: "cost.sum",
49
+ percent: 20,
50
+ });
51
+ ```
52
+
53
+ ## Step 4: Pareto
54
+
55
+ ```ts
56
+ const pareto = await insights.pareto({
57
+ scope: "org_1",
58
+ counterId: "usage",
59
+ timeframe: { type: "month", from: "2026-05", to: "2026-05" },
60
+ groupBy: ["subject"],
61
+ measure: "cost.sum",
62
+ targetShare: 0.8,
63
+ });
64
+ ```
65
+
66
+ ## Step 5: Contribution
67
+
68
+ ```ts
69
+ const contrib = await insights.contribution({
70
+ scope: "org_1",
71
+ counterId: "usage",
72
+ timeframe: { type: "month", from: "2026-05", to: "2026-05" },
73
+ groupBy: ["dim:model"],
74
+ measure: "tokens.sum",
75
+ });
76
+ ```
77
+
78
+ ## See also
79
+
80
+ - [Querying](./querying.md)
81
+ - Internal: [Insights layer](../internals/internal-insights-layer.md)