@x12i/countex 1.8.3 → 1.9.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.
- package/LICENSE +21 -21
- package/README.md +866 -858
- package/dist/cli.js +6 -6
- package/dist/index.d.ts +1 -0
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +1 -0
- package/dist/index.js.map +1 -1
- package/dist/insights/advisors/resource-advisor.d.ts.map +1 -1
- package/dist/insights/advisors/resource-advisor.js +5 -1
- package/dist/insights/advisors/resource-advisor.js.map +1 -1
- package/dist/insights/types.d.ts +4 -0
- package/dist/insights/types.d.ts.map +1 -1
- package/dist/storage/postgres.d.ts +104 -0
- package/dist/storage/postgres.d.ts.map +1 -0
- package/dist/storage/postgres.js +1023 -0
- package/dist/storage/postgres.js.map +1 -0
- package/dist/types/index.d.ts +11 -5
- package/dist/types/index.d.ts.map +1 -1
- package/docs/DEPLOYMENT.md +399 -375
- package/docs/END_TO_END_EXAMPLE.md +316 -316
- package/docs/INSIGHTS.md +59 -59
- package/docs/INSIGHTS_ANOMALY_DETECTION.md +33 -33
- package/docs/INSIGHTS_LLM_COST_AND_TOKENS.md +26 -26
- package/docs/INSIGHTS_RESOURCE_ADVISOR.md +33 -31
- package/docs/countex_gap_analysis_complete_checklist.md +1340 -1340
- package/docs/guides/README.md +36 -34
- package/docs/guides/adapter-memory.md +60 -60
- package/docs/guides/adapter-mongo.md +64 -62
- package/docs/guides/adapter-postgres.md +90 -0
- package/docs/guides/adapter-redis.md +89 -89
- package/docs/guides/backup-export.md +135 -135
- package/docs/guides/cardinality.md +50 -50
- package/docs/guides/cli.md +53 -53
- package/docs/guides/client-events.md +65 -65
- package/docs/guides/counter-maps.md +160 -160
- package/docs/guides/idempotency.md +39 -39
- package/docs/guides/ingestion-and-flush.md +67 -67
- package/docs/guides/insights-advisors-and-optimization.md +39 -39
- package/docs/guides/insights-anomalies-and-rules.md +48 -48
- package/docs/guides/insights-comparison-and-trends.md +47 -47
- package/docs/guides/insights-forecasting-and-budget.md +61 -61
- package/docs/guides/insights-overview.md +82 -82
- package/docs/guides/insights-ranking.md +81 -81
- package/docs/guides/measures.md +71 -71
- package/docs/guides/migrating-mongo-to-postgres.md +127 -0
- package/docs/guides/preview.md +92 -92
- package/docs/guides/querying.md +178 -178
- package/docs/guides/simulation-profiles.md +33 -33
- package/docs/guides/simulation-resource-estimation.md +31 -30
- package/docs/guides/simulation.md +36 -36
- package/docs/guides/timeframes-and-bucketing.md +55 -55
- package/docs/internals/README.md +21 -21
- package/docs/internals/internal-architecture-overview.md +65 -65
- package/docs/internals/internal-backup-stream.md +23 -23
- package/docs/internals/internal-buffer-merge-and-flush.md +51 -51
- package/docs/internals/internal-cardinality.md +30 -30
- package/docs/internals/internal-dimension-hash.md +34 -34
- package/docs/internals/internal-idempotency.md +36 -36
- package/docs/internals/internal-ingest-pipeline.md +52 -52
- package/docs/internals/internal-insights-layer.md +36 -36
- package/docs/internals/internal-mapping-validation-and-extraction.md +59 -59
- package/docs/internals/internal-measures-and-scales.md +35 -35
- package/docs/internals/internal-query-path.md +46 -46
- package/docs/internals/internal-storage-memory.md +13 -13
- package/docs/internals/internal-storage-mongo.md +44 -44
- package/docs/internals/internal-storage-postgres.md +32 -0
- package/docs/internals/internal-storage-redis.md +63 -63
- package/docs/internals/internal-timeframe-bucketing.md +33 -33
- package/docs/use-cases/README.md +56 -56
- package/docs/use-cases/audit-security-log-counts.md +550 -550
- package/docs/use-cases/llm-cost-and-token-metering.md +255 -255
- package/docs/use-cases/multi-tenant-isolation.md +203 -203
- package/docs/use-cases/ops-dashboard-daily-rollups.md +255 -255
- package/docs/use-cases/processing-workflow-activity.md +165 -165
- package/docs/use-cases/product-feature-usage.md +240 -240
- package/docs/use-cases/webhook-idempotent-ingestion.md +188 -188
- package/package.json +184 -169
|
@@ -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)
|