twinmind-observability

name	twinmind-observability
description	Set up comprehensive observability for TwinMind integrations with metrics, traces, and alerts. Use when implementing monitoring for TwinMind operations, setting up dashboards, or configuring alerting for meeting AI integration health. Trigger with phrases like "twinmind monitoring", "twinmind metrics", "twinmind observability", "monitor twinmind", "twinmind alerts", "twinmind tracing".
allowed-tools	Read, Write, Edit
version	1.0.0
license	MIT
author	Jeremy Longshore <[e-mail]>

TwinMind Observability

Overview

Set up comprehensive observability for TwinMind integrations including metrics, distributed tracing, logging, and alerting.

Prerequisites

• Prometheus or compatible metrics backend
• OpenTelemetry SDK installed
• Grafana or similar dashboarding tool
• AlertManager configured

Metrics Collection

Key Metrics

Metric	Type	Description
twinmind_transcriptions_total	Counter	Total transcription requests
twinmind_transcription_duration_seconds	Histogram	Transcription processing time
twinmind_transcription_audio_hours	Counter	Total audio hours processed
twinmind_errors_total	Counter	Error count by type
twinmind_rate_limit_remaining	Gauge	Rate limit headroom
twinmind_summary_requests_total	Counter	Summary generation requests
twinmind_action_items_extracted	Counter	Action items extracted
twinmind_ai_tokens_used	Counter	AI tokens consumed

Prometheus Metrics Implementation

// src/observability/metrics.ts
import { Registry, Counter, Histogram, Gauge, Summary } from 'prom-client';

const registry = new Registry();

// Transcription metrics
export const transcriptionCounter = new Counter({
  name: 'twinmind_transcriptions_total',
  help: 'Total TwinMind transcription requests',
  labelNames: ['status', 'model', 'language'],
  registers: [registry],
});

export const transcriptionDuration = new Histogram({
  name: 'twinmind_transcription_duration_seconds',
  help: 'TwinMind transcription processing duration',
  labelNames: ['model'],
  buckets: [1, 5, 10, 30, 60, 120, 300, 600],  // Up to 10 minutes
  registers: [registry],
});

export const audioHoursProcessed = new Counter({
  : ,
  : ,
  : [],
  : [registry],
});


  apiRequestCounter =  ({
  : ,
  : ,
  : [, , ],
  : [registry],
});

  apiLatency =  ({
  : ,
  : ,
  : [, ],
  : [, , , , , , , ],
  : [registry],
});


  errorCounter =  ({
  : ,
  : ,
  : [, ],
  : [registry],
});


  rateLimitRemaining =  ({
  : ,
  : ,
  : [],
  : [registry],
});


  aiTokensUsed =  ({
  : ,
  : ,
  : [],
  : [registry],
});


  summaryCounter =  ({
  : ,
  : ,
  : [, ],
  : [registry],
});

  actionItemsExtracted =  ({
  : ,
  : ,
  : [registry],
});

 { registry };

Instrumented Client

// src/twinmind/instrumented-client.ts
import {
  transcriptionCounter,
  transcriptionDuration,
  audioHoursProcessed,
  apiRequestCounter,
  apiLatency,
  errorCounter,
  rateLimitRemaining,
} from '../observability/metrics';

export class InstrumentedTwinMindClient {
  private client: TwinMindClient;

  constructor(config: TwinMindConfig) {
    this.client = new TwinMindClient(config);
  }

  async transcribe(audioUrl: string, options?: TranscriptionOptions): Promise<Transcript> {
    const timer = transcriptionDuration.startTimer({ model: options?.model || 'ear-3' });

    try {
      const result = await this.client.transcribe(audioUrl, options);

      // Record success metrics
      transcriptionCounter.inc({
        status: 'success',
        model: options?.model || 'ear-3',
        language: result.language,
      });

      // Record audio hours
      audioHoursProcessed.(
        { : options?. ||  },
        result. / 
      );

       result;
    }  (: ) {
      transcriptionCounter.({
        : ,
        : options?. || ,
        : ,
      });

      errorCounter.({
        : error. || ,
        : ,
      });

       error;
    }  {
      ();
    }
  }

   request<T>(: , : , ?: ): <T> {
     timer = apiLatency.({ method, endpoint });

     {
       response =  ..(method, endpoint, data);

      apiRequestCounter.({ method, endpoint, :  });

      
       (response.?.[]) {
        rateLimitRemaining.(
          { endpoint },
          (response.[])
        );
      }

       response.;
    }  (: ) {
      apiRequestCounter.({
        method,
        endpoint,
        : error.?. || ,
      });

       error;
    }  {
      ();
    }
  }
}

Distributed Tracing

OpenTelemetry Setup

// src/observability/tracing.ts
import { NodeSDK } from '@opentelemetry/sdk-node';
import { getNodeAutoInstrumentations } from '@opentelemetry/auto-instrumentations-node';
import { OTLPTraceExporter } from '@opentelemetry/exporter-trace-otlp-http';
import { Resource } from '@opentelemetry/resources';
import { SemanticResourceAttributes } from '@opentelemetry/semantic-conventions';
import { trace, SpanStatusCode, SpanKind } from '@opentelemetry/api';

// Initialize SDK
const sdk = new NodeSDK({
  resource: new Resource({
    [SemanticResourceAttributes.SERVICE_NAME]: 'twinmind-integration',
    [SemanticResourceAttributes.SERVICE_VERSION]: process.env.npm_package_version,
    [SemanticResourceAttributes.DEPLOYMENT_ENVIRONMENT]: process.env.NODE_ENV,
  }),
  traceExporter: new OTLPTraceExporter({
    url: process.env. || ,
  }),
  : [()],
});

sdk.();


  tracer = trace.();


   tracedOperation<T>(
  : ,
  :  <T>,
  ?: <,  | >
): <T> {
   tracer.(
    ,
    { : ., attributes },
     (span) => {
       {
         result =  ();
        span.({ : . });
         result;
      }  (: ) {
        span.({
          : .,
          : error.,
        });
        span.(error);
         error;
      }  {
        span.();
      }
    }
  );
}


   {
   : ;

   (: , ?: ): <> {
     (
      ,
       ..(audioUrl, options),
      {
        : audioUrl,
        : options?. || ,
        : options?. ?  : ,
      }
    );
  }

   (: ): <> {
     (
      ,
       ..(transcriptId),
      { : transcriptId }
    );
  }
}

Structured Logging

// src/observability/logging.ts
import pino from 'pino';

export const logger = pino({
  name: 'twinmind',
  level: process.env.LOG_LEVEL || 'info',
  formatters: {
    level: (label) => ({ level: label }),
  },
  redact: ['apiKey', 'authorization', 'password'],
});

// Operation-specific logging
export function logTwinMindOperation(
  operation: string,
  data: Record<string, any>,
  duration?: number
): void {
  logger.info({
    service: 'twinmind',
    operation,
    duration_ms: duration,
    ...data,
  });
}

// Error logging
export function logTwinMindError(
  operation: string,
  error: Error,
  context?: Record<string, any>
):  {
  logger.({
    : ,
    operation,
    : {
      : error.,
      : error.,
      : error.,
    },
    ...context,
  });
}

Alert Configuration

Prometheus AlertManager Rules

# alerts/twinmind_alerts.yaml
groups:
  - name: twinmind_alerts
    rules:
      - alert: TwinMindHighErrorRate
        expr: |
          rate(twinmind_errors_total[5m]) /
          rate(twinmind_api_requests_total[5m]) > 0.05
        for: 5m
        labels:
          severity: warning
          service: twinmind
        annotations:
          summary: "TwinMind error rate > 5%"
          description: "Error rate is {{ $value | humanizePercentage }}"

      - alert: TwinMindHighLatency
        expr: |
          histogram_quantile(0.95,
            rate(twinmind_api_latency_seconds_bucket[5m])
          ) > 5
        for: 5m
        labels:
          severity: warning
          service: twinmind
        annotations:
          summary: "TwinMind P95 latency > 5s"
          description: "P95 latency is {{ $value | humanizeDuration }}"

      - alert: TwinMindTranscriptionFailures
        expr: |
          increase(twinmind_transcriptions_total{status="error"}[15m]) > 5
         
        
           
           
        
           
           

        
                  
        
           
           
        
           
           

        
                  
        
           
           
        
           
           

        
                  
        
           
           
        
           
           

        
                  
        
           
           
        
           
           

Grafana Dashboard

{
  "dashboard": {
    "title": "TwinMind Integration",
    "panels": [
      {
        "title": "Transcription Rate",
        "type": "graph",
        "targets": [{
          "expr": "rate(twinmind_transcriptions_total[5m])",
          "legendFormat": "{{status}}"
        }]
      },
      {
        "title": "API Latency (P50/P95/P99)",
        "type": "graph",
        "targets": [
          {
            "expr": "histogram_quantile(0.5, rate(twinmind_api_latency_seconds_bucket[5m]))",
            "legendFormat": 
          
          
             
             
          
          
             
             
          
        
      
      
         
         
         
           
           
        
      
      
         
         
         
           
        
      
      
         
         
         
           
        
      
      
         
         
         
           
        
      
    
  

Metrics Endpoint

// src/api/metrics.ts
import express from 'express';
import { registry } from '../observability/metrics';

const router = express.Router();

router.get('/metrics', async (req, res) => {
  res.set('Content-Type', registry.contentType);
  res.send(await registry.metrics());
});

export default router;

Output

• Prometheus metrics implementation
• Distributed tracing with OpenTelemetry
• Structured logging with Pino
• AlertManager rules
• Grafana dashboard configuration
• Metrics endpoint

Error Handling

Issue	Cause	Solution
Missing metrics	No instrumentation	Wrap client calls
Trace gaps	Missing propagation	Check context headers
Alert storms	Wrong thresholds	Tune alert rules
High cardinality	Too many labels	Reduce label values

Resources

• Prometheus Best Practices
• OpenTelemetry Documentation
• Grafana Dashboard Examples

Next Steps

For incident response, see twinmind-incident-runbook.