@x12i/countex 1.0.0 → 1.2.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/README.md +192 -3
- package/dist/backup/export.d.ts +2 -0
- package/dist/backup/export.d.ts.map +1 -1
- package/dist/backup/export.js +2 -0
- package/dist/backup/export.js.map +1 -1
- package/dist/cli.d.ts +12 -0
- package/dist/cli.d.ts.map +1 -0
- package/dist/cli.js +190 -0
- package/dist/cli.js.map +1 -0
- package/dist/core/buffer.d.ts +4 -3
- package/dist/core/buffer.d.ts.map +1 -1
- package/dist/core/buffer.js +65 -9
- package/dist/core/buffer.js.map +1 -1
- package/dist/core/countex.d.ts.map +1 -1
- package/dist/core/countex.js +30 -3
- package/dist/core/countex.js.map +1 -1
- package/dist/core/extraction.d.ts +14 -2
- package/dist/core/extraction.d.ts.map +1 -1
- package/dist/core/extraction.js +117 -1
- package/dist/core/extraction.js.map +1 -1
- package/dist/core/mapping.d.ts.map +1 -1
- package/dist/core/mapping.js +44 -1
- package/dist/core/mapping.js.map +1 -1
- package/dist/core/timeframe.d.ts +7 -0
- package/dist/core/timeframe.d.ts.map +1 -1
- package/dist/core/timeframe.js +88 -0
- package/dist/core/timeframe.js.map +1 -1
- package/dist/index.d.ts +1 -1
- package/dist/index.d.ts.map +1 -1
- package/dist/insights/advisors/fanout-health.d.ts +3 -0
- package/dist/insights/advisors/fanout-health.d.ts.map +1 -0
- package/dist/insights/advisors/fanout-health.js +3 -0
- package/dist/insights/advisors/fanout-health.js.map +1 -0
- package/dist/insights/advisors/map-health.d.ts +6 -0
- package/dist/insights/advisors/map-health.d.ts.map +1 -0
- package/dist/insights/advisors/map-health.js +154 -0
- package/dist/insights/advisors/map-health.js.map +1 -0
- package/dist/insights/advisors/resource-advisor.d.ts +4 -0
- package/dist/insights/advisors/resource-advisor.d.ts.map +1 -0
- package/dist/insights/advisors/resource-advisor.js +102 -0
- package/dist/insights/advisors/resource-advisor.js.map +1 -0
- package/dist/insights/advisors/retention-advisor.d.ts +2 -0
- package/dist/insights/advisors/retention-advisor.d.ts.map +1 -0
- package/dist/insights/advisors/retention-advisor.js +6 -0
- package/dist/insights/advisors/retention-advisor.js.map +1 -0
- package/dist/insights/advisors-subpath.d.ts +4 -0
- package/dist/insights/advisors-subpath.d.ts.map +1 -0
- package/dist/insights/advisors-subpath.js +10 -0
- package/dist/insights/advisors-subpath.js.map +1 -0
- package/dist/insights/anomaly/baseline.d.ts +4 -0
- package/dist/insights/anomaly/baseline.d.ts.map +1 -0
- package/dist/insights/anomaly/baseline.js +54 -0
- package/dist/insights/anomaly/baseline.js.map +1 -0
- package/dist/insights/anomaly/detect-anomalies.d.ts +6 -0
- package/dist/insights/anomaly/detect-anomalies.d.ts.map +1 -0
- package/dist/insights/anomaly/detect-anomalies.js +245 -0
- package/dist/insights/anomaly/detect-anomalies.js.map +1 -0
- package/dist/insights/anomaly/ewma.d.ts +2 -0
- package/dist/insights/anomaly/ewma.d.ts.map +1 -0
- package/dist/insights/anomaly/ewma.js +15 -0
- package/dist/insights/anomaly/ewma.js.map +1 -0
- package/dist/insights/anomaly/missing-activity.d.ts +3 -0
- package/dist/insights/anomaly/missing-activity.d.ts.map +1 -0
- package/dist/insights/anomaly/missing-activity.js +8 -0
- package/dist/insights/anomaly/missing-activity.js.map +1 -0
- package/dist/insights/anomaly/robust-zscore.d.ts +2 -0
- package/dist/insights/anomaly/robust-zscore.d.ts.map +1 -0
- package/dist/insights/anomaly/robust-zscore.js +9 -0
- package/dist/insights/anomaly/robust-zscore.js.map +1 -0
- package/dist/insights/anomaly-subpath.d.ts +7 -0
- package/dist/insights/anomaly-subpath.d.ts.map +1 -0
- package/dist/insights/anomaly-subpath.js +20 -0
- package/dist/insights/anomaly-subpath.js.map +1 -0
- package/dist/insights/comparison/compare-periods.d.ts +5 -0
- package/dist/insights/comparison/compare-periods.d.ts.map +1 -0
- package/dist/insights/comparison/compare-periods.js +64 -0
- package/dist/insights/comparison/compare-periods.js.map +1 -0
- package/dist/insights/comparison/growth-rate.d.ts +3 -0
- package/dist/insights/comparison/growth-rate.d.ts.map +1 -0
- package/dist/insights/comparison/growth-rate.js +3 -0
- package/dist/insights/comparison/growth-rate.js.map +1 -0
- package/dist/insights/comparison/moving-average.d.ts +2 -0
- package/dist/insights/comparison/moving-average.d.ts.map +1 -0
- package/dist/insights/comparison/moving-average.js +6 -0
- package/dist/insights/comparison/moving-average.js.map +1 -0
- package/dist/insights/comparison/trend.d.ts +5 -0
- package/dist/insights/comparison/trend.d.ts.map +1 -0
- package/dist/insights/comparison/trend.js +84 -0
- package/dist/insights/comparison/trend.js.map +1 -0
- package/dist/insights/errors.d.ts +25 -0
- package/dist/insights/errors.d.ts.map +1 -0
- package/dist/insights/errors.js +54 -0
- package/dist/insights/errors.js.map +1 -0
- package/dist/insights/forecast/budget.d.ts +2 -0
- package/dist/insights/forecast/budget.d.ts.map +1 -0
- package/dist/insights/forecast/budget.js +6 -0
- package/dist/insights/forecast/budget.js.map +1 -0
- package/dist/insights/forecast/capacity.d.ts +2 -0
- package/dist/insights/forecast/capacity.d.ts.map +1 -0
- package/dist/insights/forecast/capacity.js +3 -0
- package/dist/insights/forecast/capacity.js.map +1 -0
- package/dist/insights/forecast/forecast.d.ts +5 -0
- package/dist/insights/forecast/forecast.d.ts.map +1 -0
- package/dist/insights/forecast/forecast.js +103 -0
- package/dist/insights/forecast/forecast.js.map +1 -0
- package/dist/insights/forecast/retention.d.ts +2 -0
- package/dist/insights/forecast/retention.d.ts.map +1 -0
- package/dist/insights/forecast/retention.js +3 -0
- package/dist/insights/forecast/retention.js.map +1 -0
- package/dist/insights/index.d.ts +4 -0
- package/dist/insights/index.d.ts.map +1 -0
- package/dist/insights/index.js +23 -0
- package/dist/insights/index.js.map +1 -0
- package/dist/insights/insights-client.d.ts +33 -0
- package/dist/insights/insights-client.d.ts.map +1 -0
- package/dist/insights/insights-client.js +344 -0
- package/dist/insights/insights-client.js.map +1 -0
- package/dist/insights/llm-subpath.d.ts +4 -0
- package/dist/insights/llm-subpath.d.ts.map +1 -0
- package/dist/insights/llm-subpath.js +10 -0
- package/dist/insights/llm-subpath.js.map +1 -0
- package/dist/insights/optimization/cost-optimizer.d.ts +6 -0
- package/dist/insights/optimization/cost-optimizer.d.ts.map +1 -0
- package/dist/insights/optimization/cost-optimizer.js +98 -0
- package/dist/insights/optimization/cost-optimizer.js.map +1 -0
- package/dist/insights/optimization/latency-optimizer.d.ts +3 -0
- package/dist/insights/optimization/latency-optimizer.d.ts.map +1 -0
- package/dist/insights/optimization/latency-optimizer.js +3 -0
- package/dist/insights/optimization/latency-optimizer.js.map +1 -0
- package/dist/insights/optimization/threshold-advisor.d.ts +2 -0
- package/dist/insights/optimization/threshold-advisor.d.ts.map +1 -0
- package/dist/insights/optimization/threshold-advisor.js +3 -0
- package/dist/insights/optimization/threshold-advisor.js.map +1 -0
- package/dist/insights/optimization/token-optimizer.d.ts +4 -0
- package/dist/insights/optimization/token-optimizer.d.ts.map +1 -0
- package/dist/insights/optimization/token-optimizer.js +133 -0
- package/dist/insights/optimization/token-optimizer.js.map +1 -0
- package/dist/insights/ranking/contribution.d.ts +2 -0
- package/dist/insights/ranking/contribution.d.ts.map +1 -0
- package/dist/insights/ranking/contribution.js +6 -0
- package/dist/insights/ranking/contribution.js.map +1 -0
- package/dist/insights/ranking/helpers.d.ts +22 -0
- package/dist/insights/ranking/helpers.d.ts.map +1 -0
- package/dist/insights/ranking/helpers.js +88 -0
- package/dist/insights/ranking/helpers.js.map +1 -0
- package/dist/insights/ranking/pareto.d.ts +2 -0
- package/dist/insights/ranking/pareto.d.ts.map +1 -0
- package/dist/insights/ranking/pareto.js +6 -0
- package/dist/insights/ranking/pareto.js.map +1 -0
- package/dist/insights/ranking/slices.d.ts +2 -0
- package/dist/insights/ranking/slices.d.ts.map +1 -0
- package/dist/insights/ranking/slices.js +6 -0
- package/dist/insights/ranking/slices.js.map +1 -0
- package/dist/insights/ranking/top-bottom.d.ts +2 -0
- package/dist/insights/ranking/top-bottom.d.ts.map +1 -0
- package/dist/insights/ranking/top-bottom.js +7 -0
- package/dist/insights/ranking/top-bottom.js.map +1 -0
- package/dist/insights/recommendations/evidence.d.ts +2 -0
- package/dist/insights/recommendations/evidence.d.ts.map +1 -0
- package/dist/insights/recommendations/evidence.js +3 -0
- package/dist/insights/recommendations/evidence.js.map +1 -0
- package/dist/insights/recommendations/recommendation.d.ts +6 -0
- package/dist/insights/recommendations/recommendation.d.ts.map +1 -0
- package/dist/insights/recommendations/recommendation.js +25 -0
- package/dist/insights/recommendations/recommendation.js.map +1 -0
- package/dist/insights/recommendations/severity.d.ts +2 -0
- package/dist/insights/recommendations/severity.d.ts.map +1 -0
- package/dist/insights/recommendations/severity.js +3 -0
- package/dist/insights/recommendations/severity.js.map +1 -0
- package/dist/insights/rules/evaluate-rules.d.ts +5 -0
- package/dist/insights/rules/evaluate-rules.d.ts.map +1 -0
- package/dist/insights/rules/evaluate-rules.js +156 -0
- package/dist/insights/rules/evaluate-rules.js.map +1 -0
- package/dist/insights/types.d.ts +405 -0
- package/dist/insights/types.d.ts.map +1 -0
- package/dist/insights/types.js +3 -0
- package/dist/insights/types.js.map +1 -0
- package/dist/insights/utils/formatting.d.ts +4 -0
- package/dist/insights/utils/formatting.d.ts.map +1 -0
- package/dist/insights/utils/formatting.js +21 -0
- package/dist/insights/utils/formatting.js.map +1 -0
- package/dist/insights/utils/grouping.d.ts +2 -0
- package/dist/insights/utils/grouping.d.ts.map +1 -0
- package/dist/insights/utils/grouping.js +8 -0
- package/dist/insights/utils/grouping.js.map +1 -0
- package/dist/insights/utils/query-builder.d.ts +21 -0
- package/dist/insights/utils/query-builder.d.ts.map +1 -0
- package/dist/insights/utils/query-builder.js +107 -0
- package/dist/insights/utils/query-builder.js.map +1 -0
- package/dist/insights/utils/row-value.d.ts +5 -0
- package/dist/insights/utils/row-value.d.ts.map +1 -0
- package/dist/insights/utils/row-value.js +36 -0
- package/dist/insights/utils/row-value.js.map +1 -0
- package/dist/insights/utils/stats.d.ts +28 -0
- package/dist/insights/utils/stats.d.ts.map +1 -0
- package/dist/insights/utils/stats.js +125 -0
- package/dist/insights/utils/stats.js.map +1 -0
- package/dist/query/formatter.d.ts.map +1 -1
- package/dist/query/formatter.js +202 -24
- package/dist/query/formatter.js.map +1 -1
- package/dist/query/planner.d.ts +10 -2
- package/dist/query/planner.d.ts.map +1 -1
- package/dist/query/planner.js +39 -2
- package/dist/query/planner.js.map +1 -1
- package/dist/storage/memory.d.ts.map +1 -1
- package/dist/storage/memory.js +78 -4
- package/dist/storage/memory.js.map +1 -1
- package/dist/storage/mongo.d.ts.map +1 -1
- package/dist/storage/mongo.js +61 -16
- package/dist/storage/mongo.js.map +1 -1
- package/dist/storage/redis.d.ts +6 -7
- package/dist/storage/redis.d.ts.map +1 -1
- package/dist/storage/redis.js +108 -39
- package/dist/storage/redis.js.map +1 -1
- package/dist/types/index.d.ts +88 -4
- package/dist/types/index.d.ts.map +1 -1
- package/docs/INSIGHTS.md +59 -0
- package/docs/INSIGHTS_ANOMALY_DETECTION.md +33 -0
- package/docs/INSIGHTS_LLM_COST_AND_TOKENS.md +26 -0
- package/docs/INSIGHTS_RESOURCE_ADVISOR.md +31 -0
- package/docs/guides/README.md +29 -0
- package/docs/guides/adapter-memory.md +48 -0
- package/docs/guides/adapter-mongo.md +50 -0
- package/docs/guides/adapter-redis.md +47 -0
- package/docs/guides/backup-export.md +39 -0
- package/docs/guides/cardinality.md +50 -0
- package/docs/guides/cli.md +45 -0
- package/docs/guides/client-events.md +49 -0
- package/docs/guides/counter-maps.md +116 -0
- package/docs/guides/idempotency.md +39 -0
- package/docs/guides/ingestion-and-flush.md +67 -0
- package/docs/guides/insights-advisors-and-optimization.md +39 -0
- package/docs/guides/insights-anomalies-and-rules.md +48 -0
- package/docs/guides/insights-comparison-and-trends.md +47 -0
- package/docs/guides/insights-forecasting-and-budget.md +61 -0
- package/docs/guides/insights-overview.md +76 -0
- package/docs/guides/insights-ranking.md +81 -0
- package/docs/guides/measures.md +67 -0
- package/docs/guides/querying.md +79 -0
- package/docs/guides/timeframes-and-bucketing.md +55 -0
- package/docs/internals/README.md +20 -0
- package/docs/internals/internal-architecture-overview.md +65 -0
- package/docs/internals/internal-backup-stream.md +23 -0
- package/docs/internals/internal-buffer-merge-and-flush.md +51 -0
- package/docs/internals/internal-cardinality.md +30 -0
- package/docs/internals/internal-idempotency.md +36 -0
- package/docs/internals/internal-ingest-pipeline.md +52 -0
- package/docs/internals/internal-insights-layer.md +36 -0
- package/docs/internals/internal-mapping-validation-and-extraction.md +59 -0
- package/docs/internals/internal-measures-and-scales.md +35 -0
- package/docs/internals/internal-query-path.md +46 -0
- package/docs/internals/internal-storage-memory.md +13 -0
- package/docs/internals/internal-storage-mongo.md +24 -0
- package/docs/internals/internal-storage-redis.md +31 -0
- package/docs/internals/internal-timeframe-bucketing.md +33 -0
- package/package.json +45 -2
|
@@ -0,0 +1,45 @@
|
|
|
1
|
+
# Guide: CLI (`countex`)
|
|
2
|
+
|
|
3
|
+
The package exposes a minimal **`countex`** binary for running selected insights against a **config module** you provide.
|
|
4
|
+
|
|
5
|
+
## Step 1: Build or install
|
|
6
|
+
|
|
7
|
+
After install, the binary resolves to `dist/cli.js`. For local development:
|
|
8
|
+
|
|
9
|
+
```bash
|
|
10
|
+
npm run build
|
|
11
|
+
npx countex insights:top ./my-context.mjs --scope org_1 --counter my_counter
|
|
12
|
+
```
|
|
13
|
+
|
|
14
|
+
## Step 2: Author a config module
|
|
15
|
+
|
|
16
|
+
Export one of:
|
|
17
|
+
|
|
18
|
+
- `export async function createContext()` returning `{ insights: CountexInsights }`
|
|
19
|
+
- `export default { insights }`
|
|
20
|
+
- `export const insights`
|
|
21
|
+
|
|
22
|
+
## Step 3: Run a command
|
|
23
|
+
|
|
24
|
+
```bash
|
|
25
|
+
countex insights:top ./ctx.mjs --scope org_1 --counter usage
|
|
26
|
+
countex insights:pareto ./ctx.mjs --format markdown
|
|
27
|
+
countex insights:anomalies ./ctx.mjs
|
|
28
|
+
countex insights:cost ./ctx.mjs
|
|
29
|
+
countex insights:tokens ./ctx.mjs
|
|
30
|
+
countex insights:map-health ./ctx.mjs
|
|
31
|
+
countex insights:resources ./ctx.mjs
|
|
32
|
+
```
|
|
33
|
+
|
|
34
|
+
Use `--format json|markdown` for output shaping.
|
|
35
|
+
|
|
36
|
+
## Step 4: TypeScript configs
|
|
37
|
+
|
|
38
|
+
```bash
|
|
39
|
+
node --import=tsx node_modules/@x12i/countex/dist/cli.js insights:top ./ctx.ts --scope org_1
|
|
40
|
+
```
|
|
41
|
+
|
|
42
|
+
## See also
|
|
43
|
+
|
|
44
|
+
- [Insights overview](./insights-overview.md)
|
|
45
|
+
- `src/cli.ts` for the authoritative command list
|
|
@@ -0,0 +1,49 @@
|
|
|
1
|
+
# Guide: Client events (`Countex`)
|
|
2
|
+
|
|
3
|
+
`Countex` extends `EventEmitter`. Subscribe for operational visibility.
|
|
4
|
+
|
|
5
|
+
## Step 1: Subscribe
|
|
6
|
+
|
|
7
|
+
```ts
|
|
8
|
+
countex.on("flush", ({ cells, durationMs }) => {
|
|
9
|
+
console.log("flushed", cells, durationMs);
|
|
10
|
+
});
|
|
11
|
+
|
|
12
|
+
countex.on("flush_error", ({ error }) => {
|
|
13
|
+
console.error(error);
|
|
14
|
+
});
|
|
15
|
+
|
|
16
|
+
countex.on("cardinality_warning", (w) => {
|
|
17
|
+
console.warn("cardinality_warning", w);
|
|
18
|
+
});
|
|
19
|
+
|
|
20
|
+
countex.on("overflow", (o) => {
|
|
21
|
+
console.warn("overflow", o);
|
|
22
|
+
});
|
|
23
|
+
|
|
24
|
+
countex.on("dropped", (d) => {
|
|
25
|
+
console.warn("dropped", d);
|
|
26
|
+
});
|
|
27
|
+
|
|
28
|
+
countex.on("duplicate", ({ scopeId, eventId }) => {
|
|
29
|
+
console.info("duplicate", scopeId, eventId);
|
|
30
|
+
});
|
|
31
|
+
|
|
32
|
+
countex.on("measure_invalid", (m) => {
|
|
33
|
+
console.warn("measure_invalid", m);
|
|
34
|
+
});
|
|
35
|
+
```
|
|
36
|
+
|
|
37
|
+
## Step 2: Type payloads
|
|
38
|
+
|
|
39
|
+
Import `CountexEvents` from types if you want compile-time checks when wiring handlers.
|
|
40
|
+
|
|
41
|
+
## Step 3: Unsubscribe
|
|
42
|
+
|
|
43
|
+
Use `off` with the same listener reference when tearing down tests.
|
|
44
|
+
|
|
45
|
+
## See also
|
|
46
|
+
|
|
47
|
+
- [Ingestion and flush](./ingestion-and-flush.md)
|
|
48
|
+
- [Cardinality](./cardinality.md)
|
|
49
|
+
- [Measures](./measures.md)
|
|
@@ -0,0 +1,116 @@
|
|
|
1
|
+
# Guide: Counter maps
|
|
2
|
+
|
|
3
|
+
A **counter map** (`CounterMap`) tells Countex how to read one JSON event and turn it into sparse counter updates. This guide walks through defining a map from scratch.
|
|
4
|
+
|
|
5
|
+
## What you will configure
|
|
6
|
+
|
|
7
|
+
- **scope** — tenant or isolation boundary (string id).
|
|
8
|
+
- **eventTime** — when the event happened (drives timeframe buckets).
|
|
9
|
+
- **subjects** — one or more “things” the count attaches to (fan-out supported).
|
|
10
|
+
- **metrics** — labels or categories being counted (fan-out supported).
|
|
11
|
+
- **dimensions** — optional breakdown fields stored on each cell.
|
|
12
|
+
- **delta** — how much to add (default `1`).
|
|
13
|
+
- **timeframes** — which bucket granularities to write (`minute` … `all`).
|
|
14
|
+
- Optional: **measures**, **idempotency**, **cardinality**, **options**.
|
|
15
|
+
|
|
16
|
+
## Step 1: Choose a stable `counterId`
|
|
17
|
+
|
|
18
|
+
Use a string that identifies this projection family across deployments, for example `access_by_actor_label`.
|
|
19
|
+
|
|
20
|
+
## Step 2: Point at scope and time
|
|
21
|
+
|
|
22
|
+
```ts
|
|
23
|
+
const map = {
|
|
24
|
+
counterId: "access_by_actor_label",
|
|
25
|
+
scope: { path: "$.tenant.id" },
|
|
26
|
+
eventTime: { path: "$.event.createdAt" },
|
|
27
|
+
// ...
|
|
28
|
+
} as const;
|
|
29
|
+
```
|
|
30
|
+
|
|
31
|
+
Rules:
|
|
32
|
+
|
|
33
|
+
- Both paths must resolve to usable values or the event is skipped for this map.
|
|
34
|
+
- `eventTime` accepts `Date`, ISO strings, or epoch numbers.
|
|
35
|
+
|
|
36
|
+
## Step 3: Declare subjects
|
|
37
|
+
|
|
38
|
+
Each subject has a `type` (your label) and a `path`. Multi-value paths fan out.
|
|
39
|
+
|
|
40
|
+
```ts
|
|
41
|
+
subjects: [
|
|
42
|
+
{ type: "actor", path: "$.actor.id", required: true },
|
|
43
|
+
{ type: "resource", path: "$.resource.id", required: false },
|
|
44
|
+
],
|
|
45
|
+
```
|
|
46
|
+
|
|
47
|
+
- **`required: true`** — if nothing matches, the whole event is skipped.
|
|
48
|
+
- **`required: false`** — missing values omit that subject type for this event.
|
|
49
|
+
|
|
50
|
+
## Step 4: Declare metrics
|
|
51
|
+
|
|
52
|
+
```ts
|
|
53
|
+
metrics: [
|
|
54
|
+
{ path: "$.labels[*]", required: true },
|
|
55
|
+
],
|
|
56
|
+
```
|
|
57
|
+
|
|
58
|
+
Wildcards (`[*]`) expand to one increment per array element (or object values).
|
|
59
|
+
|
|
60
|
+
## Step 5: Add dimensions (optional)
|
|
61
|
+
|
|
62
|
+
```ts
|
|
63
|
+
dimensions: [
|
|
64
|
+
{ name: "operation", path: "$.event.operation" },
|
|
65
|
+
{ name: "situation", path: "$.event.situation", required: false },
|
|
66
|
+
],
|
|
67
|
+
```
|
|
68
|
+
|
|
69
|
+
## Step 6: Delta and timeframes
|
|
70
|
+
|
|
71
|
+
```ts
|
|
72
|
+
delta: { default: 1 },
|
|
73
|
+
timeframes: ["day", "week", "month"],
|
|
74
|
+
```
|
|
75
|
+
|
|
76
|
+
Use `delta: { path: "$.weight" }` when counts are not always `1`.
|
|
77
|
+
|
|
78
|
+
## Step 7: Pass maps into `createCountex`
|
|
79
|
+
|
|
80
|
+
```ts
|
|
81
|
+
import { createCountex } from "@x12i/countex";
|
|
82
|
+
import { MemoryDurable, MemoryCache } from "@x12i/countex/adapters/memory";
|
|
83
|
+
|
|
84
|
+
const countex = createCountex({
|
|
85
|
+
maps: [map],
|
|
86
|
+
durable: new MemoryDurable(),
|
|
87
|
+
cache: new MemoryCache(),
|
|
88
|
+
});
|
|
89
|
+
```
|
|
90
|
+
|
|
91
|
+
Maps are validated at construction time; invalid paths or duplicate `counterId` values throw immediately.
|
|
92
|
+
|
|
93
|
+
## Path syntax (subset)
|
|
94
|
+
|
|
95
|
+
| Syntax | Meaning |
|
|
96
|
+
|--------|---------|
|
|
97
|
+
| `$` | Root |
|
|
98
|
+
| `.name` | Property |
|
|
99
|
+
| `['name']` | Bracket property |
|
|
100
|
+
| `[N]` | Array index |
|
|
101
|
+
| `[*]` | Fan-out wildcard |
|
|
102
|
+
|
|
103
|
+
## Fan-out math
|
|
104
|
+
|
|
105
|
+
Total raw increments per event ≈
|
|
106
|
+
|
|
107
|
+
`(subjects) × (metrics) × (number of timeframes)`.
|
|
108
|
+
|
|
109
|
+
Plan capacity accordingly.
|
|
110
|
+
|
|
111
|
+
## See also
|
|
112
|
+
|
|
113
|
+
- [Timeframes](./timeframes-and-bucketing.md)
|
|
114
|
+
- [Measures](./measures.md)
|
|
115
|
+
- [Cardinality](./cardinality.md)
|
|
116
|
+
- Internal: [Mapping validation & extraction](../internals/internal-mapping-validation-and-extraction.md)
|
|
@@ -0,0 +1,39 @@
|
|
|
1
|
+
# Guide: Idempotency
|
|
2
|
+
|
|
3
|
+
Idempotency prevents **duplicate events** from incrementing counters twice when retries or at-least-once delivery replay the same logical event.
|
|
4
|
+
|
|
5
|
+
## Step 1: Enable on the map
|
|
6
|
+
|
|
7
|
+
```ts
|
|
8
|
+
const map = {
|
|
9
|
+
counterId: "orders",
|
|
10
|
+
// ...
|
|
11
|
+
idempotency: {
|
|
12
|
+
enabled: true,
|
|
13
|
+
eventIdPath: "$.event.id",
|
|
14
|
+
ttlSeconds: 86_400,
|
|
15
|
+
},
|
|
16
|
+
} as const;
|
|
17
|
+
```
|
|
18
|
+
|
|
19
|
+
If `enabled` is true, `eventIdPath` is required (validated at startup).
|
|
20
|
+
|
|
21
|
+
## Step 2: Use a cache adapter that supports dedupe
|
|
22
|
+
|
|
23
|
+
Implement **`markEventSeen(scopeId, eventId, ttlSeconds): Promise<boolean>`** on your cache adapter. The built-in **`RedisCache`** provides this using Redis keys with TTL.
|
|
24
|
+
|
|
25
|
+
Countex namespaces ids as **`${counterId}:${eventId}`** per map so different counters do not collide.
|
|
26
|
+
|
|
27
|
+
## Step 3: Ingest normally
|
|
28
|
+
|
|
29
|
+
When `markEventSeen` returns **false** (already seen), increments for that map/event are dropped and a **`duplicate`** event is emitted.
|
|
30
|
+
|
|
31
|
+
## Step 4: Handle missing event ids
|
|
32
|
+
|
|
33
|
+
If the path resolves empty while idempotency is enabled, Countex records a warning and still processes unless your extraction logic skips the event — verify your producer always sets ids.
|
|
34
|
+
|
|
35
|
+
## See also
|
|
36
|
+
|
|
37
|
+
- [Redis adapter](./adapter-redis.md)
|
|
38
|
+
- [Client events](./client-events.md)
|
|
39
|
+
- Internal: [Idempotency](../internals/internal-idempotency.md)
|
|
@@ -0,0 +1,67 @@
|
|
|
1
|
+
# Guide: Ingestion and flush
|
|
2
|
+
|
|
3
|
+
Countex keeps **deltas in memory**, then **flushes** them to durable storage and optionally a cache. This guide covers the write path from your application’s perspective.
|
|
4
|
+
|
|
5
|
+
## Step 1: Ingest events
|
|
6
|
+
|
|
7
|
+
```ts
|
|
8
|
+
await countex.ingest({
|
|
9
|
+
tenant: { id: "org_1" },
|
|
10
|
+
event: { createdAt: "2026-05-08T12:00:00.000Z", operation: "read" },
|
|
11
|
+
actor: { id: "user_a" },
|
|
12
|
+
labels: ["docs"],
|
|
13
|
+
});
|
|
14
|
+
```
|
|
15
|
+
|
|
16
|
+
`ingest` accepts `unknown`. Each configured map runs extraction independently.
|
|
17
|
+
|
|
18
|
+
Use **`ingestBatch(events)`** when you already have an array; dictionary lookups are batched across the batch.
|
|
19
|
+
|
|
20
|
+
## Step 2: Understand buffering
|
|
21
|
+
|
|
22
|
+
After ingestion:
|
|
23
|
+
|
|
24
|
+
- Raw increments are merged into an in-memory **`DeltaBuffer`** keyed by cell identity.
|
|
25
|
+
- Nothing hits Mongo/Redis until flush (except dictionary resolution during ingest, which uses durable `resolveIds`).
|
|
26
|
+
|
|
27
|
+
## Step 3: Flush explicitly or on schedule
|
|
28
|
+
|
|
29
|
+
```ts
|
|
30
|
+
await countex.flush();
|
|
31
|
+
```
|
|
32
|
+
|
|
33
|
+
Flush behavior is controlled by `flush` in config:
|
|
34
|
+
|
|
35
|
+
| Option | Role |
|
|
36
|
+
|--------|------|
|
|
37
|
+
| `everyMs` | Periodic background flush (0 disables timer) |
|
|
38
|
+
| `maxBufferedCells` | Threshold on distinct buffered cells |
|
|
39
|
+
| `maxBufferedEvents` | Threshold on ingested events since last drain |
|
|
40
|
+
| `flushOnShutdown` | Drain on `shutdown()` |
|
|
41
|
+
| `onOverflow` | `"block"` awaits flush at threshold; `"drop"` fires flush without blocking |
|
|
42
|
+
|
|
43
|
+
## Step 4: Shutdown cleanly
|
|
44
|
+
|
|
45
|
+
```ts
|
|
46
|
+
await countex.shutdown();
|
|
47
|
+
```
|
|
48
|
+
|
|
49
|
+
Typically clears the timer, optionally flushes, then closes adapters.
|
|
50
|
+
|
|
51
|
+
## Step 5: Initialize adapters in production
|
|
52
|
+
|
|
53
|
+
```ts
|
|
54
|
+
await countex.init(); // calls durable.init?.() and cache.init?.()
|
|
55
|
+
```
|
|
56
|
+
|
|
57
|
+
Call once after constructing clients.
|
|
58
|
+
|
|
59
|
+
## Observability
|
|
60
|
+
|
|
61
|
+
Subscribe to `flush`, `flush_error`, `dropped`, and related events — see [Client events](./client-events.md).
|
|
62
|
+
|
|
63
|
+
## See also
|
|
64
|
+
|
|
65
|
+
- [Counter maps](./counter-maps.md)
|
|
66
|
+
- [Adapter guides](./adapter-mongo.md)
|
|
67
|
+
- Internal: [Ingest pipeline](../internals/internal-ingest-pipeline.md), [Buffer & flush](../internals/internal-buffer-merge-and-flush.md)
|
|
@@ -0,0 +1,39 @@
|
|
|
1
|
+
# Guide: Insights — advisors and resource estimation
|
|
2
|
+
|
|
3
|
+
Advisors inspect **map shape**, **fan-out health**, and optionally **stream durable cells** to estimate capacity-style metrics.
|
|
4
|
+
|
|
5
|
+
## Step 1: Map health
|
|
6
|
+
|
|
7
|
+
Requires `mapsByCounterId` passed to `createCountexInsights`.
|
|
8
|
+
|
|
9
|
+
```ts
|
|
10
|
+
const health = await insights.analyzeMapHealth({
|
|
11
|
+
scope: "org_1",
|
|
12
|
+
counterId: "usage",
|
|
13
|
+
timeframe: { type: "day", from: "2026-05-08", to: "2026-05-08" },
|
|
14
|
+
});
|
|
15
|
+
```
|
|
16
|
+
|
|
17
|
+
## Step 2: Resource estimation from actuals
|
|
18
|
+
|
|
19
|
+
Requires the **`durable`** reference in `createCountexInsights`.
|
|
20
|
+
|
|
21
|
+
```ts
|
|
22
|
+
const resources = await insights.estimateResourcesFromActuals({
|
|
23
|
+
scope: "org_1",
|
|
24
|
+
counterId: "usage",
|
|
25
|
+
timeframe: { type: "day", from: "2026-05-08", to: "2026-05-08" },
|
|
26
|
+
});
|
|
27
|
+
```
|
|
28
|
+
|
|
29
|
+
This path uses `durable.streamCells` — ensure your adapter implements streaming efficiently.
|
|
30
|
+
|
|
31
|
+
## Events
|
|
32
|
+
|
|
33
|
+
Recommendations attach to `recommendation` emissions with severity for downstream routing (pager, ticket, etc.).
|
|
34
|
+
|
|
35
|
+
## See also
|
|
36
|
+
|
|
37
|
+
- `docs/INSIGHTS_RESOURCE_ADVISOR.md`
|
|
38
|
+
- [Insights overview](./insights-overview.md)
|
|
39
|
+
- Internal: [Insights layer](../internals/internal-insights-layer.md)
|
|
@@ -0,0 +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)
|
|
@@ -0,0 +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)
|
|
@@ -0,0 +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)
|
|
@@ -0,0 +1,76 @@
|
|
|
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
|
+
## Feature map
|
|
63
|
+
|
|
64
|
+
| Area | Methods |
|
|
65
|
+
|------|---------|
|
|
66
|
+
| Ranking | `topN`, `bottomN`, `topPercent`, `bottomPercent`, `pareto`, `contribution` |
|
|
67
|
+
| Comparison | `comparePeriods`, `trend` |
|
|
68
|
+
| Anomalies & rules | `detectAnomalies`, `evaluateRules` |
|
|
69
|
+
| Forecast & budget | `forecast`, `budgetProjection`, `costDrivers`, `recommendMaxTokens` |
|
|
70
|
+
| Advisors | `analyzeMapHealth`, `estimateResourcesFromActuals` |
|
|
71
|
+
|
|
72
|
+
## See also
|
|
73
|
+
|
|
74
|
+
- Domain-focused narratives: `docs/INSIGHTS.md`, `docs/INSIGHTS_ANOMALY_DETECTION.md`, etc.
|
|
75
|
+
- [Ranking](./insights-ranking.md)
|
|
76
|
+
- Internal: [Insights layer](../internals/internal-insights-layer.md)
|
|
@@ -0,0 +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)
|