@xcelsior/strapi-monitoring

Monitoring and error tracking plugin for Strapi CMS in the Xcelsior ecosystem.

Installation

pnpm add @xcelsior/strapi-monitoring

Features

Basic Setup

Add to your Strapi configuration:

// config/plugins.ts
export default {
  'xcelsior-monitoring': {
    enabled: true,
    config: {
      service: 'strapi-cms',
      environment: process.env.NODE_ENV,
      sampleRate: 1.0,
    },
  },
};

Error Tracking

Automatic error tracking in your Strapi application:

// In your controllers/services
module.exports = {
  async create(ctx) {
    try {
      const entry = await strapi.entityService.create('api::article.article', {
        data: ctx.request.body,
      });
      return entry;
    } catch (error) {
      // Error will be automatically captured
      throw error;
    }
  },
};

// Manual error capture
strapi.monitor.captureError(error, {
  tags: { component: 'article-service' },
  extra: { articleData: data },
});

Performance Monitoring

Track application performance:

// Automatic transaction tracking
module.exports = {
  async find(ctx) {
    const transaction = strapi.monitor.startTransaction('find-articles');
    
    try {
      const entries = await strapi.entityService.findMany('api::article.article');
      transaction.finish();
      return entries;
    } catch (error) {
      transaction.finish(error);
      throw error;
    }
  },
};

// Performance spans
const span = strapi.monitor.startSpan('database-query');
try {
  await query();
} finally {
  span.finish();
}

Configuration

Plugin Options

interface MonitoringOptions {
  service: string;
  environment: string;
  release?: string;
  sampleRate?: number;
  ignoreErrors?: (string | RegExp)[];
  performance?: {
    enabled: boolean;
    sampleRate?: number;
  };
  breadcrumbs?: {
    enabled: boolean;
    maxBreadcrumbs?: number;
  };
}

Environment Variables

The plugin respects these environment variables:

• STRAPI_MONITORING_DSN: Connection string for error reporting service
• STRAPI_MONITORING_ENVIRONMENT: Environment name
• STRAPI_MONITORING_RELEASE: Release version

Advanced Usage

Custom Context

Add custom context to all events:

// Add global context
strapi.monitor.setContext('deployment', {
  version: '1.0.0',
  region: 'us-east-1',
});

// Add context to specific events
strapi.monitor.captureMessage('Important event', {
  level: 'info',
  tags: { component: 'auth' },
  extra: { userId: '123' },
});

Health Checks

Monitor service health:

const health = strapi.monitor.healthCheck({
  database: async () => {
    await strapi.db.connection.raw('SELECT 1');
    return { status: 'healthy' };
  },
  redis: async () => {
    await strapi.redis.ping();
    return { status: 'healthy' };
  },
});

// Get health status
const status = await health.check();

Custom Metrics

Track application metrics:

// Track custom metrics
strapi.monitor.trackMetric('active_users', 100);
strapi.monitor.trackMetric('response_time', 150, {
  tags: { endpoint: '/api/articles' },
});

Best Practices

Error Handling

try {
  await riskyOperation();
} catch (error) {
  strapi.monitor.captureError(error, {
    tags: { operation: 'riskyOperation' },
    extra: { input: input },
    user: ctx.state.user,
  });
  throw error;
}

Performance Tracking

module.exports = (config, { strapi }) => {
  return async (ctx, next) => {
    const transaction = strapi.monitor.startTransaction(ctx.request.path);
    
    try {
      await next();
    } finally {
      transaction.finish({
        status: ctx.response.status,
        duration: Date.now() - ctx.request.startTime,
      });
    }
  };
};

Breadcrumbs

// Add breadcrumbs for debugging
strapi.monitor.addBreadcrumb({
  category: 'auth',
  message: 'User login attempt',
  level: 'info',
  data: { userId: '123' },
});

License

MIT