add-stats-dimension
Skill4.2k starsChanged 37 days agoMITView on GitHub
Checklist for adding or changing a statistics table/dimension in the collector. Use whenever touching SQLite schema, traffic write paths, retention, ClickHouse parity, or stats query APIs — several places must change together or data silently drifts.
1 other project uses a version of this.
Trending
Quiet since August.thin dataabout the whole repository
Most recently taken up by
- foru17/clash-masterword for word, first seen Oct 8, 2026
Who's talking about foru17/neko-master
- @camilleroux.com“Neko Master : un dashboard self-hosted pour visualiser et auditer le trafic réseau en temps réel, avec …”Bluesky · Aug 3, 2026 · 4 likes
- @github-trending-js.bsky.social“🚀 Skyrocketing! 🚀 (200+ new stars) 📦 foru17 / neko-master ⭐ 3,679 (+231) 🗒 TypeScript A modern and …”Bluesky · Aug 21, 2026 · 1 likes
- @chrisshort.net“foru17/neko-master: A modern and elegant dashboard for network traffic visualization and analysis. …”Bluesky · Jul 24, 2026 · 1 likes
- @github-trending-js.bsky.social“🔥 Hot Repo! 🔥 (100+ new stars) 📦 foru17 / neko-master ⭐ 2,741 (+186) 🗒 TypeScript A modern and elegant …”Bluesky · Jul 17, 2026 · 1 likes
- ruanyf/weekly“【开源自荐】Neko Master:现代化网络流量分析面板”GitHub · Feb 11, 2026
The biggest 5 of 5 mentions linking to the repository that our crawl found. Each line is their own headline.
Other versions1 project uses a version of this.
Word for word · 1
- foru17/clash-master★ 4.2k100% same
Edited · 0
None found.
Wrote their own version · 0
None found.
How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.
In this repository8 other files it gives its agents.
- AGENTS.mdAGENTS.md
- CLAUDE.mdCLAUDE.md
- .github/copilot-instructions.mdCopilot instructions
- agent-probe-devSkill
- db-conventionsSkill
- releaseSkill
- ui-conventionsSkill
- verify-changesSkill
The file
We split this skill into the rules it gives an agent
6 rules. About 0 are common, 1 is distinctive, and 5 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈1
Distinctive · estimate
This author's own choices. Worth a look.
5
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 12
Add the CREATE TABLE / CREATE INDEX statements to apps/collector/src/database/schema.ts (SCHEMA + INDEXES).
- Very specific: line 14
Do NOT add expression indexes on (total_download + total_upload) — hot queries filter by backend_id first, so the planner never uses them …
- Very specific: line 18
All traffic writes go through batchUpdateTrafficStats in apps/collector/src/database/repositories/traffic-writer.repository.ts.
- Distinctive: line 19
Add your aggregation map in the batch loop and the upsert in the appropriate transaction group.
- Very specific: line 39
Add the table to the explicit delete list in deleteBackendData (apps/collector/src/database/repositories/backend.repository.ts).
- Very specific: line 53
Add a Vitest case in apps/collector exercising the batch write + read-back (see traffic-writer.test.ts for patterns, …
≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Add / Change a Stats Dimension
The stats pipeline has one write implementation but several coupled registries. Missing any step below produces silent data loss or drift — none of it fails loudly. Work through the checklist in order.
1. Schema (single source of truth)
- Add the
CREATE TABLE/CREATE INDEXstatements toapps/collector/src/database/schema.ts(SCHEMA+INDEXES). Nothing else creates tables. - Existing databases only get
IF NOT EXISTSDDL from schema.ts. Column additions and index drops need an explicit migration inapps/collector/src/modules/db/db.tsinit()(see theALTER TABLE ... ADD COLUMNandDROP INDEX IF EXISTSprecedents there). - Do NOT add expression indexes on
(total_download + total_upload)— hot queries filter bybackend_idfirst, so the planner never uses them (verified with EXPLAIN QUERY PLAN); they only amplify writes.
2. Write path (exactly one)
- All traffic writes go through
batchUpdateTrafficStatsinapps/collector/src/database/repositories/traffic-writer.repository.ts.updateTrafficStatsis a thin wrapper over it — never add a second write implementation. - Add your aggregation map in the batch loop and the upsert in the appropriate transaction group. The whole flush is one outer transaction; keep it that way (a partial commit + buffer retry double-counts).
- CSV-style association columns (
ips,rules,chains,domains) must dedupe with the delimiter-aware pattern — bareINSTR(list, value)treatsa.comas present whenaa.comis:
INSTR(',' || col || ',', ',' || @value || ',') > 0- Respect
reduceWritessemantics: detail tables are skipped when ClickHouse is the read source (shouldReduceSqliteWritesinmodules/stats/stats-write-mode.ts). Decide whether your table is "core" (always written) or "detail" (skippable) and place it in the matching branch.
3. Rule naming contract (if the dimension involves rules)
- Rule stats key on the top-level policy group (last chain hop) for multi-hop chains —
buildRuleNameinsrc/shared/utils/rule-name.tsis the only place this logic lives. The frontend matches these names against gateway rule targets (rule.proxy), so changing the key breaks the flow graph and rule matching (this regressed once in v1.3.9; seedocs/dev/deep-review-2026-07.md).
4. Retention
- Register cleanup in
apps/collector/src/modules/cleanup/cleanup.service.ts+config.repository.ts. Minute-level tables followconnectionLogsDays(default 7d); hourly tables followhourlyStatsDays(default 30d).hourly_dim_statsbacks all >6h range queries — never tie it to the minute cutoff. - Cumulative
*_statstables currently have no retention; if your table is a cross-product (rule×ip style), consider alast_seen-based cap from day one.
5. Backend deletion
- Add the table to the explicit delete list in
deleteBackendData(apps/collector/src/database/repositories/backend.repository.ts).PRAGMA foreign_keysis OFF, so the declaredON DELETE CASCADEnever fires — forgetting this leaves orphan rows forever.
6. ClickHouse parity (if the data is queryable over ranges)
- Writer:
apps/collector/src/modules/clickhouse/clickhouse.writer.ts - Reader:
apps/collector/src/modules/clickhouse/clickhouse.reader.ts— the SQLite and CH implementations of the same query must return the same shape and semantics (time format, windows). Routing lives inmodules/stats/stats.service.ts(*WithRoutingmethods).
7. Types and API
- Shared response types go in
packages/shared(both apps consume them; never fork the type locally). - Time keys are UTC ISO slices: minute
YYYY-MM-DDTHH:MM:00, hourYYYY-MM-DDTHH:00:00(toMinuteKey/toHourKeyinbase.repository.ts). Don't introduce local-time keys.
8. Tests
- Add a Vitest case in
apps/collectorexercising the batch write + read-back (seetraffic-writer.test.tsfor patterns,src/__tests__/helpers.tsfor DB setup), then run theverify-changesskill.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

