[FEATURE] Analytics: Custom metrics and KPI definition engine (#74)

[KevinMB0220]

Description

Roadmap Phase 4 → Analytics & Monitoring → #74 Create custom metrics and KPIs has no tracking issue. It is the remaining gap in a section whose other three items have shipped: #339 (analytics dashboard, roadmap #71), #340 (real-time performance monitoring, #72) and #341 (configurable alerting, #73).

Those three cover fixed, developer-defined metrics. #74 is about letting an operator define a metric without a code change — pick a source, an aggregation, a window and a dimension, name it, and have it appear in the dashboard and be alertable.

Background

What exists today:

• packages/api/rest/src/services/monitoring/ — transaction-monitoring.service.ts, monitoring-alert.service.ts, alert-evaluator.ts, transaction-rule-engine.ts, and a channel dispatcher with webhook and notification channels
• packages/api/rest/src/routes/monitoring/ — transactions.ts and alerts.ts

alert-evaluator.ts and transaction-rule-engine.ts already evaluate conditions over transaction data, which is the closest existing analogue and the natural thing to generalize rather than duplicate.

What is missing is the definition layer: every metric is currently hardcoded, so adding one means editing a service, opening a PR and redeploying.

Requirements

Metric definition model

• A metric_definitions table and a typed model: id, userId/orgId, name, description, source, aggregation, window, dimensions, filters, unit, enabled
• Sources drawn from what the DevKit already records: transactions, wallet events, DeFi positions, oracle prices, automation executions, API request logs
• Aggregations: count, sum, avg, min, max, p50/p95/p99, rate, distinct_count
• Rolling windows (5m, 1h, 24h, 7d, 30d) and calendar windows (day/week/month to date)
• Dimensions/group-by: asset, protocol, network, wallet, user, team, endpoint
• Derived metrics — a definition may reference other definitions in an arithmetic expression (e.g. failed_tx / total_tx). Detect and reject cycles

Evaluation

• A MetricsService that compiles a definition into a parameterized Supabase query — never string-concatenated SQL
• Reuse the caching layer from [FEATURE] Core: Advanced caching strategies with TTL and invalidation (#77) #343 with a TTL derived from the window; a 30d metric must not be recomputed per request
• Scheduled materialization for expensive definitions, with on-demand evaluation for cheap ones
• Backfill: computing a newly created definition over existing history

KPI targets

• Attach a target/threshold and direction (higher-is-better / lower-is-better) to a definition
• Expose current value, target, delta vs. previous period, and trend

API

• POST/GET/PATCH/DELETE /api/v1/metrics/definitions — full CRUD, scoped to the owner
• GET /api/v1/metrics/:id/value — current value, optional dimension filters
• GET /api/v1/metrics/:id/series — time series for charting, with explicit bucket size
• POST /api/v1/metrics/preview — evaluate an unsaved definition, so the UI can validate before saving

Integration

• Custom metrics selectable as an alert source in monitoring-alert.service.ts, reusing the existing channel dispatcher rather than adding a parallel one
• Custom metrics renderable in the [FEATURE] Frontend: Comprehensive analytics dashboard with portfolio tracking (#71) #339 dashboard
• Definitions exportable/importable as JSON so an environment's KPI set is reproducible

Guardrails

• Per-user caps on definition count and on evaluation cost; reject a definition whose estimated scan exceeds a limit
• Query timeouts, so one expensive metric cannot stall the monitoring API
• Audit-log create/update/delete via the [FEATURE] API: Enhanced structured audit logging system (#66) #334 audit logging

Acceptance Criteria

• An operator can define "average swap size in USD, per protocol, 24h rolling" through the API with no code change, and read its value
• A derived metric referencing two other definitions evaluates correctly; a cyclic definition is rejected at save time
• An alert rule can target a custom metric and fires through the existing channels
• Repeated reads inside the TTL are served from cache
• A definition with an unsupported source or aggregation is rejected with a clear validation error
• A user cannot read or modify another user's definitions
• preview evaluates without persisting
• Tests cover each aggregation, each window type, dimension grouping and cycle detection

References

• Roadmap: Phase 4 → Analytics & Monitoring → [FEATURE] Implement Hardware Wallet Integration (Ledger) #74
• Builds on: [FEATURE] Frontend: Comprehensive analytics dashboard with portfolio tracking (#71) #339 (dashboard, [FEATURE] Create IOracleSource Interface and Aggregator #71), [FEATURE] API: Real-time performance monitoring and health check endpoints (#72) #340 (performance monitoring, [FEATURE] Setup Integration Tests Infrastructure #72), [FEATURE] API: Configurable alerting system with multi-channel notifications (#73) #341 (alerting, [FEATURE] Add Multi-Signature Wallet Support #73)
• Existing code to generalize: packages/api/rest/src/services/monitoring/alert-evaluator.ts, transaction-rule-engine.ts
• Depends on: [FEATURE] Core: Advanced caching strategies with TTL and invalidation (#77) #343 (caching), [FEATURE] Core: Optimize Supabase queries and add database indexing strategy (#76) #342 (DB indexing), [FEATURE] API: Enhanced structured audit logging system (#66) #334 (audit logging)

[Buluz244]

@Buluz244 has applied to work on this issue as part of the Stellar Wave Program's 8th wave.

I love to be assigned this issue also I've experienced across many framework and I'm confidently able to resolve it looking forward to it thanks

ℹ️ Repo Maintainers: To accept this application, review their application or assign @Buluz244 to this issue.

[Horlars105]

@Horlars105 has applied to work on this issue as part of the Stellar Wave Program's 8th wave.

Let me work on this issue, you'll know the reason why I want to work on it when I'm done working on it.

ℹ️ Repo Maintainers: To accept this application, review their application or assign @Horlars105 to this issue.

[mayborn005]

@mayborn005 has applied to work on this issue as part of the Stellar Wave Program's 8th wave.

Hello @maintainer, I'd love to work on this issue. I'll keep the implementation simple, clean, and well-tested.

ℹ️ Repo Maintainers: To accept this application, review their application or assign @mayborn005 to this issue.

[Lspnjr1]

@Lspnjr1 has applied to work on this issue as part of the Stellar Wave Program's 8th wave.

I’ll like to applied on this issue

ℹ️ Repo Maintainers: To accept this application, review their application or assign @Lspnjr1 to this issue.

[babatundealao407-alt]

@babatundealao407-alt has applied to work on this issue as part of the Stellar Wave Program's 8th wave.

I’ve taken the time to understand the issue and its intendefunctionalit. I’d be happy to work on this and provide an implementation that is cleanly integrated, properly tested, and considerate of existing functionality.

ℹ️ Repo Maintainers: To accept this application, review their application or assign @babatundealao407-alt to this issue.

[Inspector222]

@Inspector222 has applied to work on this issue as part of the Stellar Wave Program's 8th wave.

Please assign the issue to me. I’m ready to work on it.

ℹ️ Repo Maintainers: To accept this application, review their application or assign @Inspector222 to this issue.

[Gezziy]

@Gezziy has applied to work on this issue as part of the Stellar Wave Program's 8th wave.

Hi I would like to contribute to this issue. I’m a blockchain and backend developer with experience in Solidity, TypeScript, and Node.js, specializing in secure smart contract development and scalable backend systems. I focus on writing reliable, well-structured code and building efficient integrations for blockchain-based applications.

ℹ️ Repo Maintainers: To accept this application, review their application or assign @Gezziy to this issue.

[iyanukid2008-pixel]

@iyanukid2008-pixel has applied to work on this issue as part of the Stellar Wave Program's 8th wave.

I’ve reviewed the issue and understand what the implementation needs to achieve. I’d be happy to take this on and work toward a clean, reliable solution that fits naturally within the existing codebase.

ℹ️ Repo Maintainers: To accept this application, review their application or assign @iyanukid2008-pixel to this issue.