@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,63 +1,63 @@
|
|
|
1
|
-
# Internal: Redis cache adapter
|
|
2
|
-
|
|
3
|
-
`RedisCache` (`src/storage/redis.ts`) maps each `(scope, counterId, timeframeType, timeframeKey)` bucket to a **HASH** of cell entries plus a sibling **`:cov` HASH** of coverage metadata:
|
|
4
|
-
|
|
5
|
-
```
|
|
6
|
-
countex:{scope}:{counterId}:{tf}:{bucket} → HASH (cells)
|
|
7
|
-
field = "{subjectType}|{subjectId}|{metricId}|{dimensionsHash}"
|
|
8
|
-
value = count (integer)
|
|
9
|
-
field = "{base}:m:{measureName}:sum" → measure sum
|
|
10
|
-
field = "{base}:m:{measureName}:count" → measure event count
|
|
11
|
-
|
|
12
|
-
countex:{scope}:{counterId}:{tf}:{bucket}:cov → HASH (coverage meta)
|
|
13
|
-
status = "complete" | "partial" | "rebuilding"
|
|
14
|
-
lastWarmAt = epoch ms
|
|
15
|
-
cellCount = number of cells last warmed (set on warm)
|
|
16
|
-
schemaVersion = REDIS_CACHE_SCHEMA_VERSION
|
|
17
|
-
mapVersion = optional opaque integer
|
|
18
|
-
|
|
19
|
-
countex:{scope}:{counterId}:{tf}:{bucket}:meta:{baseField} → JSON of dimensions
|
|
20
|
-
```
|
|
21
|
-
|
|
22
|
-
Per-bucket coverage gives the planner authoritative information about which buckets the cache can answer with confidence, instead of guessing from "did `HGETALL` return anything?".
|
|
23
|
-
|
|
24
|
-
## Coverage state machine
|
|
25
|
-
|
|
26
|
-
| Triggered by | Effect on `:cov.status` |
|
|
27
|
-
|---|---|
|
|
28
|
-
| First `applyDeltas` to a previously-empty bucket | `partial` (via `HSETNX`) — never downgrades a `complete` or `rebuilding` bucket |
|
|
29
|
-
| Subsequent `applyDeltas` | unchanged status; `lastWarmAt` updated |
|
|
30
|
-
| `warm()` | `complete`, with `cellCount`, `schemaVersion`, `mapVersion`, `lastWarmAt` written atomically |
|
|
31
|
-
| `markBucketRebuilding()` | `rebuilding` (called by `rebuildCache` before refilling) |
|
|
32
|
-
| TTL expiry | key disappears → `missing` on next read |
|
|
33
|
-
|
|
34
|
-
## Read coverage
|
|
35
|
-
|
|
36
|
-
`readCells` pipelines both `HGETALL bucket` and `HGETALL :cov`, then derives per-bucket coverage from the meta:
|
|
37
|
-
|
|
38
|
-
- All buckets `complete` → aggregate `full`.
|
|
39
|
-
- Any `complete | partial | rebuilding` mixed with the rest → aggregate `partial`.
|
|
40
|
-
- All `missing` → aggregate `miss`.
|
|
41
|
-
|
|
42
|
-
When the planner supplies `expectedMapVersion` or `expectedSchemaVersion` and the bucket's stored version differs, `complete` is demoted to `partial` (cache is treated as stale for that bucket). The planner then falls back to durable.
|
|
43
|
-
|
|
44
|
-
## Probe-only path
|
|
45
|
-
|
|
46
|
-
`probeBucketCoverage(scope, counterId, tf, [keys])` returns just the `:cov` hashes without touching cell data. The `Countex.explainQuery(spec)` API uses this to predict the cache hit rate without materializing rows.
|
|
47
|
-
|
|
48
|
-
## Dedupe keys
|
|
49
|
-
|
|
50
|
-
`markEventSeen` writes ephemeral keys `countex:{scope}:dedupe:{eventId}` with TTL.
|
|
51
|
-
|
|
52
|
-
## Warm path
|
|
53
|
-
|
|
54
|
-
`warm` hydrates hashes from `CounterCell[]` after durable reads, then sets `:cov.status=complete`. Used by `rebuildCache` and by the query planner's best-effort warm-after-fallback.
|
|
55
|
-
|
|
56
|
-
## Error stance
|
|
57
|
-
|
|
58
|
-
Apply failures during flush are swallowed at Countex level after durable success — subsequent reads rebuild cache. Coverage meta is best-effort: a stale `:cov.status=complete` only causes a temporary divergence (caller sees stale-but-consistent reads until TTL expires).
|
|
59
|
-
|
|
60
|
-
## See also
|
|
61
|
-
|
|
62
|
-
- [Query path](./internal-query-path.md)
|
|
63
|
-
- [Storage memory](./internal-storage-memory.md) — mirrors the same coverage contract for tests.
|
|
1
|
+
# Internal: Redis cache adapter
|
|
2
|
+
|
|
3
|
+
`RedisCache` (`src/storage/redis.ts`) maps each `(scope, counterId, timeframeType, timeframeKey)` bucket to a **HASH** of cell entries plus a sibling **`:cov` HASH** of coverage metadata:
|
|
4
|
+
|
|
5
|
+
```
|
|
6
|
+
countex:{scope}:{counterId}:{tf}:{bucket} → HASH (cells)
|
|
7
|
+
field = "{subjectType}|{subjectId}|{metricId}|{dimensionsHash}"
|
|
8
|
+
value = count (integer)
|
|
9
|
+
field = "{base}:m:{measureName}:sum" → measure sum
|
|
10
|
+
field = "{base}:m:{measureName}:count" → measure event count
|
|
11
|
+
|
|
12
|
+
countex:{scope}:{counterId}:{tf}:{bucket}:cov → HASH (coverage meta)
|
|
13
|
+
status = "complete" | "partial" | "rebuilding"
|
|
14
|
+
lastWarmAt = epoch ms
|
|
15
|
+
cellCount = number of cells last warmed (set on warm)
|
|
16
|
+
schemaVersion = REDIS_CACHE_SCHEMA_VERSION
|
|
17
|
+
mapVersion = optional opaque integer
|
|
18
|
+
|
|
19
|
+
countex:{scope}:{counterId}:{tf}:{bucket}:meta:{baseField} → JSON of dimensions
|
|
20
|
+
```
|
|
21
|
+
|
|
22
|
+
Per-bucket coverage gives the planner authoritative information about which buckets the cache can answer with confidence, instead of guessing from "did `HGETALL` return anything?".
|
|
23
|
+
|
|
24
|
+
## Coverage state machine
|
|
25
|
+
|
|
26
|
+
| Triggered by | Effect on `:cov.status` |
|
|
27
|
+
|---|---|
|
|
28
|
+
| First `applyDeltas` to a previously-empty bucket | `partial` (via `HSETNX`) — never downgrades a `complete` or `rebuilding` bucket |
|
|
29
|
+
| Subsequent `applyDeltas` | unchanged status; `lastWarmAt` updated |
|
|
30
|
+
| `warm()` | `complete`, with `cellCount`, `schemaVersion`, `mapVersion`, `lastWarmAt` written atomically |
|
|
31
|
+
| `markBucketRebuilding()` | `rebuilding` (called by `rebuildCache` before refilling) |
|
|
32
|
+
| TTL expiry | key disappears → `missing` on next read |
|
|
33
|
+
|
|
34
|
+
## Read coverage
|
|
35
|
+
|
|
36
|
+
`readCells` pipelines both `HGETALL bucket` and `HGETALL :cov`, then derives per-bucket coverage from the meta:
|
|
37
|
+
|
|
38
|
+
- All buckets `complete` → aggregate `full`.
|
|
39
|
+
- Any `complete | partial | rebuilding` mixed with the rest → aggregate `partial`.
|
|
40
|
+
- All `missing` → aggregate `miss`.
|
|
41
|
+
|
|
42
|
+
When the planner supplies `expectedMapVersion` or `expectedSchemaVersion` and the bucket's stored version differs, `complete` is demoted to `partial` (cache is treated as stale for that bucket). The planner then falls back to durable.
|
|
43
|
+
|
|
44
|
+
## Probe-only path
|
|
45
|
+
|
|
46
|
+
`probeBucketCoverage(scope, counterId, tf, [keys])` returns just the `:cov` hashes without touching cell data. The `Countex.explainQuery(spec)` API uses this to predict the cache hit rate without materializing rows.
|
|
47
|
+
|
|
48
|
+
## Dedupe keys
|
|
49
|
+
|
|
50
|
+
`markEventSeen` writes ephemeral keys `countex:{scope}:dedupe:{eventId}` with TTL.
|
|
51
|
+
|
|
52
|
+
## Warm path
|
|
53
|
+
|
|
54
|
+
`warm` hydrates hashes from `CounterCell[]` after durable reads, then sets `:cov.status=complete`. Used by `rebuildCache` and by the query planner's best-effort warm-after-fallback.
|
|
55
|
+
|
|
56
|
+
## Error stance
|
|
57
|
+
|
|
58
|
+
Apply failures during flush are swallowed at Countex level after durable success — subsequent reads rebuild cache. Coverage meta is best-effort: a stale `:cov.status=complete` only causes a temporary divergence (caller sees stale-but-consistent reads until TTL expires).
|
|
59
|
+
|
|
60
|
+
## See also
|
|
61
|
+
|
|
62
|
+
- [Query path](./internal-query-path.md)
|
|
63
|
+
- [Storage memory](./internal-storage-memory.md) — mirrors the same coverage contract for tests.
|
|
@@ -1,33 +1,33 @@
|
|
|
1
|
-
# Internal: Timeframe bucketing
|
|
2
|
-
|
|
3
|
-
## Bucket derivation
|
|
4
|
-
|
|
5
|
-
`bucketKey(type, date)` (`src/core/timeframe.ts`) formats UTC bucket strings:
|
|
6
|
-
|
|
7
|
-
- Minute/hour include `T` separators.
|
|
8
|
-
- Week uses **ISO week** numbering (`formatIsoWeek`).
|
|
9
|
-
- Quarter uses `YYYY-Qn`.
|
|
10
|
-
- `all` collapses to `"all"`.
|
|
11
|
-
|
|
12
|
-
Ingest **never** uses processing clock — only parsed **`eventTime`** from the map.
|
|
13
|
-
|
|
14
|
-
## Range iteration
|
|
15
|
-
|
|
16
|
-
`bucketRange(from, to)` walks forward with `advance`, stopping at:
|
|
17
|
-
|
|
18
|
-
- End boundary
|
|
19
|
-
- **MAX = 10_000** produced keys
|
|
20
|
-
|
|
21
|
-
Downstream query code relies on this bound for safety.
|
|
22
|
-
|
|
23
|
-
## Rates
|
|
24
|
-
|
|
25
|
-
`bucketDurationSeconds` supplies nominal seconds per bucket for rate calculations. **`all` throws** by design — mirrored in public API constraints.
|
|
26
|
-
|
|
27
|
-
## Parsing
|
|
28
|
-
|
|
29
|
-
`parseBucket` reconstructs `Date` objects for comparisons when reshaping query outputs.
|
|
30
|
-
|
|
31
|
-
## See also
|
|
32
|
-
|
|
33
|
-
- [Query path](./internal-query-path.md)
|
|
1
|
+
# Internal: Timeframe bucketing
|
|
2
|
+
|
|
3
|
+
## Bucket derivation
|
|
4
|
+
|
|
5
|
+
`bucketKey(type, date)` (`src/core/timeframe.ts`) formats UTC bucket strings:
|
|
6
|
+
|
|
7
|
+
- Minute/hour include `T` separators.
|
|
8
|
+
- Week uses **ISO week** numbering (`formatIsoWeek`).
|
|
9
|
+
- Quarter uses `YYYY-Qn`.
|
|
10
|
+
- `all` collapses to `"all"`.
|
|
11
|
+
|
|
12
|
+
Ingest **never** uses processing clock — only parsed **`eventTime`** from the map.
|
|
13
|
+
|
|
14
|
+
## Range iteration
|
|
15
|
+
|
|
16
|
+
`bucketRange(from, to)` walks forward with `advance`, stopping at:
|
|
17
|
+
|
|
18
|
+
- End boundary
|
|
19
|
+
- **MAX = 10_000** produced keys
|
|
20
|
+
|
|
21
|
+
Downstream query code relies on this bound for safety.
|
|
22
|
+
|
|
23
|
+
## Rates
|
|
24
|
+
|
|
25
|
+
`bucketDurationSeconds` supplies nominal seconds per bucket for rate calculations. **`all` throws** by design — mirrored in public API constraints.
|
|
26
|
+
|
|
27
|
+
## Parsing
|
|
28
|
+
|
|
29
|
+
`parseBucket` reconstructs `Date` objects for comparisons when reshaping query outputs.
|
|
30
|
+
|
|
31
|
+
## See also
|
|
32
|
+
|
|
33
|
+
- [Query path](./internal-query-path.md)
|
package/docs/use-cases/README.md
CHANGED
|
@@ -1,56 +1,56 @@
|
|
|
1
|
-
# Countex use cases — technical playbooks
|
|
2
|
-
|
|
3
|
-
These documents are **end-to-end operational specifications**: they start from a concrete delivery problem, define **exact** input contracts and Countex primitives, then walk through **numbered steps** you can implement without improvising.
|
|
4
|
-
|
|
5
|
-
They are published with `@x12i/countex` under `docs/use-cases/` and exposed as stable `package.json` exports (see root `README.md`).
|
|
6
|
-
|
|
7
|
-
## How each playbook is structured
|
|
8
|
-
|
|
9
|
-
Every use-case file follows the same skeleton:
|
|
10
|
-
|
|
11
|
-
1. **Problem & constraints** — what you are counting, latency/durability expectations, and what Countex does *not* solve.
|
|
12
|
-
2. **Primitives mapping** — explicit table: JSON field → `scope` / `subject` / `metric` / `dimension` / `eventTime` / `delta`.
|
|
13
|
-
3. **Canonical payload** — JSON example plus a **required-field matrix** (what must be present or ingest skips).
|
|
14
|
-
4. **`CounterMap`** — copy-paste literal with a **field-by-field rationale**.
|
|
15
|
-
5. **Fan-out arithmetic** — formula and a worked example for capacity planning.
|
|
16
|
-
6. **Implementation steps** — repository layout, dependencies, `createCountex` options, `init` / `ingest` / `flush` / `shutdown`, event subscriptions.
|
|
17
|
-
7. **Query specifications** — literal `QuerySpec` objects; how to read **`QueryRow.keys`** (dictionary ids vs literal dimension strings).
|
|
18
|
-
8. **Production hardening** — Mongo / Redis wiring patterns, cardinality, idempotency TTL math, observability.
|
|
19
|
-
9. **Verification** — checks you can run after deploy.
|
|
20
|
-
10. **Failure modes** — symptom → cause → exact mitigation.
|
|
21
|
-
|
|
22
|
-
## Stable import paths (npm)
|
|
23
|
-
|
|
24
|
-
| Document | Subpath |
|
|
25
|
-
|----------|---------|
|
|
26
|
-
| Index (this list) | `@x12i/countex/docs/use-cases` |
|
|
27
|
-
| [Audit & security logs](./audit-security-log-counts.md) (includes **volume, situations, distinct entities, logical event counts**) | `@x12i/countex/docs/use-cases/audit-security-log-counts` |
|
|
28
|
-
| [Product & feature activity](./product-feature-usage.md) | `@x12i/countex/docs/use-cases/product-feature-usage` |
|
|
29
|
-
| [LLM metering](./llm-cost-and-token-metering.md) | `@x12i/countex/docs/use-cases/llm-cost-and-token-metering` |
|
|
30
|
-
| [Multi-tenant isolation](./multi-tenant-isolation.md) | `@x12i/countex/docs/use-cases/multi-tenant-isolation` |
|
|
31
|
-
| [Webhooks & queues](./webhook-idempotent-ingestion.md) | `@x12i/countex/docs/use-cases/webhook-idempotent-ingestion` |
|
|
32
|
-
| [Ops dashboards](./ops-dashboard-daily-rollups.md) | `@x12i/countex/docs/use-cases/ops-dashboard-daily-rollups` |
|
|
33
|
-
| [Processing & workflow activity](./processing-workflow-activity.md) | `@x12i/countex/docs/use-cases/processing-workflow-activity` |
|
|
34
|
-
|
|
35
|
-
## Prerequisites (global)
|
|
36
|
-
|
|
37
|
-
- **Node.js** ≥ 18 (see `package.json` `engines`).
|
|
38
|
-
- Core package: `@x12i/countex`.
|
|
39
|
-
- Optional peers for production paths: `mongodb`, `ioredis` (your process owns client lifecycle).
|
|
40
|
-
|
|
41
|
-
## Terminology (read this once)
|
|
42
|
-
|
|
43
|
-
| Term | Meaning |
|
|
44
|
-
|------|---------|
|
|
45
|
-
| **Scope** | Tenant boundary string (`scopeId` in storage). Every query **must** pin `scope`. |
|
|
46
|
-
| **Subject** | `(subjectType, subjectId)` after dictionary resolution; `subjectId` is an **integer**. |
|
|
47
|
-
| **Metric** | `(metricId)` after dictionary resolution; labels/strings become stable numeric ids per scope. |
|
|
48
|
-
| **Dimension** | Named breakdown; values stored **literally** on cells (not dictionary-encoded). |
|
|
49
|
-
| **Timeframe key** | UTC bucket string, e.g. `2026-05-08` for `day` (see `bucketKey` in `src/core/timeframe.ts`). |
|
|
50
|
-
| **Fan-out** | Cartesian product of subject extractions × metric extractions × number of `timeframes` entries. |
|
|
51
|
-
|
|
52
|
-
## Related documentation
|
|
53
|
-
|
|
54
|
-
- Feature reference: [`docs/guides/`](../guides/README.md)
|
|
55
|
-
- Narrative tutorial: [`END_TO_END_EXAMPLE.md`](../END_TO_END_EXAMPLE.md)
|
|
56
|
-
- Deployment: [`DEPLOYMENT.md`](../DEPLOYMENT.md)
|
|
1
|
+
# Countex use cases — technical playbooks
|
|
2
|
+
|
|
3
|
+
These documents are **end-to-end operational specifications**: they start from a concrete delivery problem, define **exact** input contracts and Countex primitives, then walk through **numbered steps** you can implement without improvising.
|
|
4
|
+
|
|
5
|
+
They are published with `@x12i/countex` under `docs/use-cases/` and exposed as stable `package.json` exports (see root `README.md`).
|
|
6
|
+
|
|
7
|
+
## How each playbook is structured
|
|
8
|
+
|
|
9
|
+
Every use-case file follows the same skeleton:
|
|
10
|
+
|
|
11
|
+
1. **Problem & constraints** — what you are counting, latency/durability expectations, and what Countex does *not* solve.
|
|
12
|
+
2. **Primitives mapping** — explicit table: JSON field → `scope` / `subject` / `metric` / `dimension` / `eventTime` / `delta`.
|
|
13
|
+
3. **Canonical payload** — JSON example plus a **required-field matrix** (what must be present or ingest skips).
|
|
14
|
+
4. **`CounterMap`** — copy-paste literal with a **field-by-field rationale**.
|
|
15
|
+
5. **Fan-out arithmetic** — formula and a worked example for capacity planning.
|
|
16
|
+
6. **Implementation steps** — repository layout, dependencies, `createCountex` options, `init` / `ingest` / `flush` / `shutdown`, event subscriptions.
|
|
17
|
+
7. **Query specifications** — literal `QuerySpec` objects; how to read **`QueryRow.keys`** (dictionary ids vs literal dimension strings).
|
|
18
|
+
8. **Production hardening** — Mongo / Redis wiring patterns, cardinality, idempotency TTL math, observability.
|
|
19
|
+
9. **Verification** — checks you can run after deploy.
|
|
20
|
+
10. **Failure modes** — symptom → cause → exact mitigation.
|
|
21
|
+
|
|
22
|
+
## Stable import paths (npm)
|
|
23
|
+
|
|
24
|
+
| Document | Subpath |
|
|
25
|
+
|----------|---------|
|
|
26
|
+
| Index (this list) | `@x12i/countex/docs/use-cases` |
|
|
27
|
+
| [Audit & security logs](./audit-security-log-counts.md) (includes **volume, situations, distinct entities, logical event counts**) | `@x12i/countex/docs/use-cases/audit-security-log-counts` |
|
|
28
|
+
| [Product & feature activity](./product-feature-usage.md) | `@x12i/countex/docs/use-cases/product-feature-usage` |
|
|
29
|
+
| [LLM metering](./llm-cost-and-token-metering.md) | `@x12i/countex/docs/use-cases/llm-cost-and-token-metering` |
|
|
30
|
+
| [Multi-tenant isolation](./multi-tenant-isolation.md) | `@x12i/countex/docs/use-cases/multi-tenant-isolation` |
|
|
31
|
+
| [Webhooks & queues](./webhook-idempotent-ingestion.md) | `@x12i/countex/docs/use-cases/webhook-idempotent-ingestion` |
|
|
32
|
+
| [Ops dashboards](./ops-dashboard-daily-rollups.md) | `@x12i/countex/docs/use-cases/ops-dashboard-daily-rollups` |
|
|
33
|
+
| [Processing & workflow activity](./processing-workflow-activity.md) | `@x12i/countex/docs/use-cases/processing-workflow-activity` |
|
|
34
|
+
|
|
35
|
+
## Prerequisites (global)
|
|
36
|
+
|
|
37
|
+
- **Node.js** ≥ 18 (see `package.json` `engines`).
|
|
38
|
+
- Core package: `@x12i/countex`.
|
|
39
|
+
- Optional peers for production paths: `mongodb`, `ioredis` (your process owns client lifecycle).
|
|
40
|
+
|
|
41
|
+
## Terminology (read this once)
|
|
42
|
+
|
|
43
|
+
| Term | Meaning |
|
|
44
|
+
|------|---------|
|
|
45
|
+
| **Scope** | Tenant boundary string (`scopeId` in storage). Every query **must** pin `scope`. |
|
|
46
|
+
| **Subject** | `(subjectType, subjectId)` after dictionary resolution; `subjectId` is an **integer**. |
|
|
47
|
+
| **Metric** | `(metricId)` after dictionary resolution; labels/strings become stable numeric ids per scope. |
|
|
48
|
+
| **Dimension** | Named breakdown; values stored **literally** on cells (not dictionary-encoded). |
|
|
49
|
+
| **Timeframe key** | UTC bucket string, e.g. `2026-05-08` for `day` (see `bucketKey` in `src/core/timeframe.ts`). |
|
|
50
|
+
| **Fan-out** | Cartesian product of subject extractions × metric extractions × number of `timeframes` entries. |
|
|
51
|
+
|
|
52
|
+
## Related documentation
|
|
53
|
+
|
|
54
|
+
- Feature reference: [`docs/guides/`](../guides/README.md)
|
|
55
|
+
- Narrative tutorial: [`END_TO_END_EXAMPLE.md`](../END_TO_END_EXAMPLE.md)
|
|
56
|
+
- Deployment: [`DEPLOYMENT.md`](../DEPLOYMENT.md)
|