CollaborationMetricsService

Kind: Service

Source: atloria-monorepo/apps/api/src/collaboration/collaboration-metrics.service.ts

Service for tracking and reporting collaboration metrics

CollaborationMetricsService is a NestJS service that collects and reports operational metrics for real-time collaboration, including active session counts and synchronization latency. It manages periodic metric recording during the module lifecycle and exposes query methods for current, aggregate, and P95 latency values.

Methods

totalActiveDocuments: number;
totalActiveSessions: number;
averageSyncLatencyMs: number;
documentsAboveLatencyThreshold: number;

}>` | Get a summary of collaboration metrics for monitoring |

Dependencies

• RedisService

Where it refuses work

• CollaborationMetricsService stops the work with an early return when cached && cached.expiresAt > Date.now(), in 4 places.
• CollaborationMetricsService stops the work with an early return when samples.length === 0.
• CollaborationMetricsService stops the work with an early return when numbers.length === 0.

When something fails

• CollaborationMetricsService handles failure in 6 places: it logs it and continues in 3, and turns it into a return value in 3.

Diagram

mermaid
sequenceDiagram
  participant Nest as NestJS Lifecycle
  participant Service as CollaborationMetricsService
  participant Sessions as Collaboration Sessions
  participant Metrics as Metrics Store

  Nest->>Service: onModuleInit()
  Service->>Service: Start periodic metric recording

  loop Recording interval
    Service->>Sessions: Read active sessions
    Sessions-->>Service: Session count
    Service->>Sessions: Read sync latency samples
    Sessions-->>Service: Latency values
    Service->>Metrics: Store collaboration metrics
  end

  Client->>Service: getMetrics()
  Service->>Metrics: Retrieve latest metrics
  Metrics-->>Service: CollaborationMetrics | null
  Service-->>Client: Metrics response

  Nest->>Service: onModuleDestroy()
  Service->>Service: Stop periodic recording

Usage

ts
import { Injectable } from '@nestjs/common';
import { CollaborationMetricsService } from './collaboration-metrics.service';

@Injectable()
export class CollaborationHealthService {
  constructor(
    private readonly collaborationMetrics: CollaborationMetricsService,
  ) {}

  async getHealthSummary() {
    const [metrics, activeSessions, p95SyncLatency] = await Promise.all([
      this.collaborationMetrics.getMetrics(),
      this.collaborationMetrics.getTotalActiveSessions(),
      this.collaborationMetrics.getP95SyncLatency(),
    ]);

    return {
      activeSessions,
      p95SyncLatencyMs: p95SyncLatency,
      latestMetrics: metrics,
      healthy: p95SyncLatency < 500,
    };
  }
}

AI Coding Instructions

• Let NestJS manage lifecycle hooks; keep initialization logic in onModuleInit() and always release timers, subscriptions, or resources in onModuleDestroy().
• Use recordMetrics() as the orchestration point for collection work, delegating session and latency collection to recordActiveSessions() and recordSyncLatency().
• Treat getMetrics() as nullable and handle the case where no metric snapshot has been recorded yet.
• Preserve the distinction between current latency (getSyncLatency()) and tail latency (getP95SyncLatency()); use P95 for health checks and alerting.
• Avoid performing expensive aggregation work in request paths; record and cache metric values on the service’s scheduled collection cycle.

Relationships

• DEPENDS_ON → RedisService

Referenced By

• CollaborationModule (MODULE_PROVIDES)
• CollaborationModule (MODULE_EXPORTS)