Gamma Observability

Overview

Implement comprehensive monitoring, logging, and tracing for Gamma integrations.

Prerequisites

• Observability stack (Prometheus, Grafana, or cloud equivalent)
• Log aggregation (ELK, CloudWatch, or similar)
• APM tool (Datadog, New Relic, or OpenTelemetry)

Three Pillars of Observability

1. Metrics

// lib/gamma-metrics.ts
import { Counter, Histogram, Gauge, Registry } from 'prom-client';

const registry = new Registry();

// Request metrics
const requestCounter = new Counter({
  name: 'gamma_requests_total',
  help: 'Total Gamma API requests',
  labelNames: ['method', 'endpoint', 'status'],
  registers: [registry],
});

const requestDuration = new Histogram({
  name: 'gamma_request_duration_seconds',
  help: 'Gamma API request duration',
  labelNames: ['method', 'endpoint'],
  buckets: [0.1, 0.5, 1, 2, 5, 10, 30],
  registers: [registry],
});

// Business metrics
const presentationsCreated = new Counter({
  name: 'gamma_presentations_created_total',
  help: 'Total presentations created',
  labelNames: ['style', 'user_tier'],
  registers: [registry],
});

const rateLimitRemaining = new Gauge({
  name: 'gamma_rate_limit_remaining',
  help: 'Remaining API calls in rate limit window',
  registers: [registry],
});

// Instrumented client
export function createInstrumentedClient() {
  return new GammaClient({
    apiKey: process.env.GAMMA_API_KEY,
    interceptors: {
      request: (config) => {
        config._startTime = Date.now();
        return config;
      },
      response: (response, config) => {
        const duration = (Date.now() - config._startTime) / 1000;
        const endpoint = config.path.split('/')[1];

        requestCounter.inc({
          method: config.method,
          endpoint,
          status: response.status,
        });

        requestDuration.observe(
          { method: config.method, endpoint },
          duration
        );

        // Update rate limit gauge
        const remaining = response.headers['x-ratelimit-remaining'];
        if (remaining) {
          rateLimitRemaining.set(parseInt(remaining, 10));
        }

        return response;
      },
    },
  });
}

2. Logging

// lib/gamma-logger.ts
import winston from 'winston';

const logger = winston.createLogger({
  level: process.env.LOG_LEVEL || 'info',
  format: winston.format.combine(
    winston.format.timestamp(),
    winston.format.errors({ stack: true }),
    winston.format.json()
  ),
  defaultMeta: { service: 'gamma-integration' },
  transports: [
    new winston.transports.Console(),
    new winston.transports.File({ filename: 'gamma-error.log', level: 'error' }),
    new winston.transports.File({ filename: 'gamma-combined.log' }),
  ],
});

// Structured logging for Gamma operations
export function logGammaRequest(operation: string, params: object) {
  logger.info('Gamma API request', {
    operation,
    params: sanitizeParams(params),
    timestamp: new Date().toISOString(),
  });
}

export function logGammaResponse(operation: string, response: object, duration: number) {
  logger.info('Gamma API response', {
    operation,
    duration,
    success: true,
    responseId: response.id,
  });
}

export function logGammaError(operation: string, error: Error, context: object) {
  logger.error('Gamma API error', {
    operation,
    error: error.message,
    stack: error.stack,
    context,
  });
}

function sanitizeParams(params: object): object {
  const sanitized = { ...params };
  // Remove sensitive fields
  delete sanitized.apiKey;
  delete sanitized.secret;
  return sanitized;
}

3. Distributed Tracing

// lib/gamma-tracing.ts
import { trace, SpanKind, SpanStatusCode } from '@opentelemetry/api';

const tracer = trace.getTracer('gamma-integration');

export async function traceGammaCall<T>(
  operationName: string,
  fn: () => Promise<T>
): Promise<T> {
  return tracer.startActiveSpan(
    `gamma.${operationName}`,
    { kind: SpanKind.CLIENT },
    async (span) => {
      try {
        const result = await fn();

        span.setAttributes({
          'gamma.operation': operationName,
          'gamma.success': true,
        });

        span.setStatus({ code: SpanStatusCode.OK });
        return result;
      } catch (error) {
        span.setAttributes({
          'gamma.operation': operationName,
          'gamma.success': false,
          'gamma.error': error.message,
        });

        span.setStatus({
          code: SpanStatusCode.ERROR,
          message: error.message,
        });

        span.recordException(error);
        throw error;
      } finally {
        span.end();
      }
    }
  );
}

// Usage
const presentation = await traceGammaCall('presentations.create', () =>
  gamma.presentations.create({ title: 'My Deck', prompt: 'AI content' })
);

Dashboard Configuration

Grafana Dashboard

{
  "title": "Gamma Integration",
  "panels": [
    {
      "title": "Request Rate",
      "type": "graph",
      "targets": [
        { "expr": "rate(gamma_requests_total[5m])" }
      ]
    },
    {
      "title": "Latency P95",
      "type": "graph",
      "targets": [
        { "expr": "histogram_quantile(0.95, rate(gamma_request_duration_seconds_bucket[5m]))" }
      ]
    },
    {
      "title": "Error Rate",
      "type": "stat",
      "targets": [
        { "expr": "rate(gamma_requests_total{status=~'5..'}[5m]) / rate(gamma_requests_total[5m])" }
      ]
    },
    {
      "title": "Rate Limit Remaining",
      "type": "gauge",
      "targets": [
        { "expr": "gamma_rate_limit_remaining" }
      ]
    }
  ]
}

Alert Rules

# prometheus/alerts.yml
groups:
  - name: gamma
    rules:
      - alert: GammaHighErrorRate
        expr: rate(gamma_requests_total{status=~"5.."}[5m]) / rate(gamma_requests_total[5m]) > 0.05
        for: 5m
        labels:
          severity: warning
        annotations:
          summary: High Gamma API error rate

      - alert: GammaRateLimitLow
        expr: gamma_rate_limit_remaining < 10
        for: 1m
        labels:
          severity: critical
        annotations:
          summary: Gamma rate limit nearly exhausted

      - alert: GammaHighLatency
        expr: histogram_quantile(0.95, rate(gamma_request_duration_seconds_bucket[5m])) > 5
        for: 5m
        labels:
          severity: warning
        annotations:
          summary: Gamma API latency is high

Health Check Endpoint

// routes/health.ts
app.get('/health/gamma', async (req, res) => {
  const health = {
    status: 'unknown',
    latency: 0,
    rateLimit: { remaining: 0, limit: 0 },
    timestamp: new Date().toISOString(),
  };

  try {
    const start = Date.now();
    const response = await gamma.ping();
    health.latency = Date.now() - start;
    health.status = response.ok ? 'healthy' : 'degraded';
    health.rateLimit = {
      remaining: response.rateLimit.remaining,
      limit: response.rateLimit.limit,
    };
  } catch (error) {
    health.status = 'unhealthy';
  }

  const statusCode = health.status === 'healthy' ? 200 : 503;
  res.status(statusCode).json(health);
});

Resources

• OpenTelemetry Documentation
• Prometheus Best Practices
• Grafana Dashboards

Next Steps

Proceed to gamma-incident-runbook for incident response.