OmniRoute/docs/architecture/MONITORING_SECTIONS.md at 223e67a4fbb20ce153dc367b6cd6fcba02c32d71

mirror of https://github.com/diegosouzapw/OmniRoute.git synced 2026-08-03 05:45:04 +03:00

Files

Diego Rodrigues de Sa e Souza 5ac4637816 docs: reorganize docs/ + accuracy audit + drop Node 20 (rebased onto current release tip) (#5262 )

* docs: move superpowers/research artifacts to isolated _tasks repo + docs tree cleanup

- Move docs/superpowers/{plans,specs} and docs/research/* into the gitignored,
  separately-versioned _tasks/ repo; untrack the two tracked research design docs.
- Add CLAUDE.md "Planning & Research Artifacts" section overriding the superpowers
  default save paths (docs/... -> _tasks/...); align REPOSITORY_MAP and
  DOCUMENTATION_OVERHAUL_PLAN with the new convention.
- Drop 4 now-obsolete /api/discovery/* entries from check-docs-symbols allowlist
  (stale-enforcement) and refresh code/spec path comments to _tasks/...
- Sweeps in concurrent docs-tree restructuring (root-level provider/guide docs,
  compression spec cleanup, .mcp.json.example removal).

* docs: reorganize docs/ tree + fix stale facts across ~26 docs

Phase A — reorganization:
- Move 7 orphan root docs into subfolders (providers/ created; TIERS+USAGE_QUOTA→guides/;
  plugins+PLUGIN_SDK→frameworks/); delete 8 obsolete/redundant docs (SUBMIT_PR superseded
  by CONTRIBUTING; DOCUMENTATION_OVERHAUL_PLAN; INCIDENT_RESPONSE/PERF_BUDGETS/THREAT_MODEL;
  3 ops snapshots). Rebuild README index (was missing ~40 files) + per-folder meta.json nav.
- Clean 14 dangling doc-path references in bin/ ops scripts, scripts/, workflow, tests;
  fix the dockerignore-docs-coverage required-docs path (PROVIDERS→providers/CLAUDE_WEB).

Phase B — content accuracy (verified against code, not the audit summary):
- Functional: ENVIRONMENT flag defaults (INPUT_SANITIZER/MCP_ENFORCE_SCOPES=true,
  COMPRESS_DESCRIPTIONS=false, dynamic heap); MCP-SERVER notion tool names (omniroute_*→
  notion_*) + counts 87→94; coverage gate 75/70→60/60/60/60 (RELEASE_CHECKLIST, COVERAGE_PLAN,
  ERROR_SANITIZATION, CONTRIBUTING); pre-push hook description; regenerate PROVIDER_REFERENCE (237).
- Count drift: providers 237, executors 70, migrations 106, db modules 94, oauth 19,
  strategies 17, MCP 94, flags 38, TS 6.0, open-sse ~900/services 294 across architecture/
  frameworks/ops docs; AUTO-COMBO 9→12 factors w/ correct DEFAULT_WEIGHTS; REASONING +2
  patterns; STEALTH UA defaults; AGENT_PROTOCOLS +cursor-cloud/list-capabilities;
  LANGUAGE_PACKS +id pack.
- Kept Node 20 (runtime guard accepts 20.20.2+; only engines is stricter) and MCP scopes=13
  (mcpScopes.ts) — both were correct in the docs; corrected only the attribution.

* docs: finish content refresh — compression engines, CLI_TOKEN merge, metadata sweep

- Compression: document the additional built-in engines (CCR, headroom, ionizer,
  session-dedup) in COMPRESSION_ENGINES; clarify LLMLingua-2 is the ultra-mode SLM
  backend + cross-ref the extra engines in EXTENDING_COMPRESSION; add the id
  (Indonesian) language pack to LANGUAGE_PACKS.
- AUTO-COMBO: replace the orphan 'How tiers fit' weight table (stale weights) with a
  pointer to the canonical 12-factor DEFAULT_WEIGHTS table.
- Security: merge CLI_TOKEN_AUTH.md (legacy 32-char SHA-256 format) into CLI_TOKEN.md
  as a 'Legacy format — still accepted' section (server accepts both HMAC + legacy),
  delete CLI_TOKEN_AUTH.md, drop it from the index + security nav.
- Metadata: bump stale frontmatter (version/lastUpdated) to 3.8.40/2026-06-28 across the
  doc set audited this pass, and normalize the in-body 'Last updated' header lines to match.

* fix(runtime): drop Node 20 from supported range + align all docs/diagrams/counts

- Node minimum is now 22 (aligned with package.json engines). SUPPORTED_NODE_RANGE in
  src/shared/utils/nodeRuntimeSupport.ts (and the bin/ mirror) drops the 20.x line →
  '>=22.22.2 <23 || >=24.0.0 <27'; getNodeRuntimeSupport now rejects Node 20 as
  unsupported-major. Test updated (TDD): node-runtime-support.test.ts asserts Node 20
  rejected. Docs aligned (TROUBLESHOOTING ×2, TERMUX, RELEASE_CHECKLIST, CODEBASE,
  CLI-TOOLS, README, llm.txt + 42 i18n llm.txt mirrors, skills/cli-serve).
- Diagrams regenerated: mcp-tools-87 -> mcp-tools-94 (34 base + pool 6 = 94) and
  auto-combo-9factor -> auto-combo-12factor (correct DEFAULT_WEIGHTS); SVGs re-rendered
  via mermaid-cli; doc refs + diagrams/README updated; fixed a pre-existing broken
  resilience-3layers image path.
- CLAUDE.md + AGENTS.md aligned to real counts (237 providers, 94 MCP tools / 34 base,
  106 migrations, 94 db modules, 12-factor auto-combo, 17 strategies); README provider
  count 231 -> 237; executor count corrected to 68 (provider executors, excl base/index)
  and OAuth to 18 across architecture docs. check:docs-all now passes (0 strict drift,
  0 broken links); removed dead .mcp.json.example doc link.

* fix(services): update installer Node hint to >=22.22.2 (aligned with dropped Node 20)

* docs: realign counts to current release tip after rebase

The release tip advanced while this work was in flight (Gemini CLI provider/executor
removed by #5246, plus other PRs). Re-counted against the current code and updated:
providers 237->236, executors 68->67, OAuth modules 18->17, open-sse services 294->298;
regenerated PROVIDER_REFERENCE.md (236). check:docs-all passes (0 strict drift).

* docs(changelog) + i18n: record Node 20 drop + fix nodeIncompatibleHint

- CHANGELOG: add [3.8.40] entries for the Node 20.x removal (runtime) and the docs
  reorganization/accuracy audit.
- i18n: nodeIncompatibleHint across all 42 locales no longer lists Node 20.x as
  supported (ASCII + CJK full-width variants), aligned with the dropped Node 20.

* fix(docs): repair CI breakages from the doc moves

- test: cli-plugin-system asserted docs/dev/plugins.md exists; the file moved to
  docs/frameworks/PLUGINS.md — point the test at the new path (Unit fast-path 2/2 fix).
- frontmatter: PLUGINS.md and PLUGIN_SDK.md moved into the fumadocs-indexed
  docs/frameworks/ which requires a 'title' frontmatter; the missing frontmatter
  failed the Next.js MDX build (dast-smoke 'invalid frontmatter'). Added frontmatter
  to both, plus the providers/ docs (consistency; that folder is not indexed).

2026-06-28 22:07:18 -03:00

6.0 KiB

Raw Blame History

title, version, lastUpdated

title	version	lastUpdated
Monitoring & Costs — Navigation Structure	3.8.40	2026-06-28

Implemented in Group B (plan 16). See src/shared/constants/sidebarVisibility.ts.

The dashboard sidebar (after Group B) has these top-level sections in order:

Home
Providers
Combos
API Keys
Settings
Analytics
Costs          ← NEW (Group B, plan 16)
Monitoring     ← REORGANIZED (Group B, plan 16)
...

Costs section (new, level 1)

Path prefix: /dashboard/costs/

Item	URL	Description
Overview	`/dashboard/costs`	Aggregated cost dashboard (moved from Analytics)
Pricing	`/dashboard/costs/pricing`	Per-model pricing table
Budget	`/dashboard/costs/budget`	Budget thresholds + alerts
Quota Sharing	`/dashboard/costs/quota-share`	Quota Share pools + usage
Plan Config	`/dashboard/costs/quota-share/plans`	Per-provider plan overrides

Rationale: Pricing, Budget, and Quota Sharing were previously under Monitoring > Costs Parameters. Moving them to a dedicated top-level section makes them discoverable without navigating through observability tooling.

Monitoring section (reorganized)

The Monitoring section now has Activity at the top followed by 3 subgroups:

Monitoring
├── Activity             ← Timeline feed (top-level item)
├── Logs group
│   ├── Logs (all)
│   ├── Proxy Logs
│   └── Console Logs
├── Audit group
│   ├── Audit Log
│   ├── MCP Audit
│   └── A2A Audit
└── System group
    ├── Health
    └── Runtime

What changed from the old structure

Before	After
Activity = tab inside Logs that rendered the Audit Log	Activity = dedicated feed (`/dashboard/activity`)
Costs Parameters group in Monitoring	Moved to Costs section
Flat list: Logs, Activity (logs), Audit, Health, Runtime, Pricing, Budget, Quota	Structured 3-group + dedicated Costs section

Activity vs Audit Log

These two are now distinct:

Dimension	Activity (`/dashboard/activity`)	Audit Log (`/dashboard/audit`)
Purpose	User-facing event feed ("what happened recently")	Compliance / security log
Data source	`GET /api/compliance/audit-log?level=high`	`GET /api/compliance/audit-log?level=all`
Format	Timeline, grouped by day, human-readable verbs + icons	Dense paginaged table, 50/page
Filters	Event type category	Action, severity, actor, date range
Export	Not available	JSON export
Actor filter	Not applicable	Filterable by actor
Events shown	High-level actions only (allowlist)	All audit events

High-Level Actions allowlist

Defined in src/lib/audit/highLevelActions.ts. Controls which events appear in the Activity feed. The allowlist includes:

Provider add/remove/test events
Combo create/update/delete
API key lifecycle (create, revoke, rotate)
Budget threshold reached
Auth login/logout
Cloud agent session creation
MCP tool registration
Webhook create/delete
Quota pool/plan changes (quota.* actions, Group B)
Platform events (update, deploy)
Skill install/remove

Events not in this list appear only in the Audit Log.

Adding a new high-level action

Edit src/lib/audit/highLevelActions.ts and add the action string to HIGH_LEVEL_ACTIONS. This requires a PR (the list is code, not DB-configurable). The corresponding icon can be added to src/lib/audit/activityIcons.ts.

Redirect: `/dashboard/logs/activity`

The old path /dashboard/logs/activity is permanently redirected (HTTP 308) to /dashboard/activity via permanentRedirect() in src/app/(dashboard)/dashboard/logs/activity/page.tsx.

The legacy sidebar ID logs-activity is preserved in HIDEABLE_SIDEBAR_ITEM_IDS (but removed from SIDEBAR_DEFINITIONS) to avoid breaking user presets that reference the old ID.

i18n

Namespaces added by Group B:

Namespace key	Covers
`sidebar.costsSection`	Costs section label
`sidebar.activity`	Activity sidebar item
`sidebar.logsGroup`	Logs subgroup label
`sidebar.systemGroup`	System subgroup label
`sidebar.costsOverview`	Costs overview item
`activity.*`	All Activity page strings (title, verbs, filters, empty state)

Source-of-truth locales: pt-BR and en. All other 39 locales fall back to English via the next-intl fallback mechanism (configured in src/i18n/config.ts).

6.0 KiB Raw Blame History

Monitoring & Costs — Navigation Structure

High-Level Navigation