managing-apps/src/Managing.Web3Proxy/SENTRY.md

Sentry Integration for Web3Proxy

This project includes Sentry for error monitoring and logging. Sentry helps track application errors in real-time and provides detailed information about exceptions that occur during runtime.

Configuration

Sentry is configured via environment variables in your .env file:

# Sentry configuration
SENTRY_DSN=your-sentry-dsn
SENTRY_ENVIRONMENT=development # or production, staging, etc.

How It Works

1. Sentry is initialized during application startup in plugins/external/sentry.ts
2. All unhandled exceptions and errors are automatically captured and sent to Sentry
3. The Fastify instance is decorated with a sentry property, which gives you access to the Sentry SDK

Testing Endpoints

The application provides several endpoints to test Sentry functionality:

• /api/sentry-diagnostics - Shows the Sentry configuration status and sends test events
• /test-sentry - Triggers and captures a handled exception
• /test-sentry-uncaught - Triggers an unhandled exception (useful for testing error handlers)

Using Sentry in Your Routes

You can manually capture events and exceptions in your routes:

// Capture a message
fastify.get('/example', async (request, reply) => {
  // Log a message to Sentry
  fastify.sentry.captureMessage('User visited example page');
  
  // Continue with your route logic
  return { message: 'Example page' };
});

// Capture an exception
fastify.get('/example-error', async (request, reply) => {
  try {
    // Some code that might fail
    throw new Error('Something went wrong');
  } catch (error) {
    // Capture the exception
    fastify.sentry.captureException(error);
    
    // Respond to the client
    return { message: 'An error occurred, but we've logged it' };
  }
});

Troubleshooting

If events aren't appearing in your Sentry dashboard:

1. Verify your DSN is correct in your .env file
2. Ensure your network allows outbound HTTPS connections to sentry.io
3. Check that the environment is correctly set
4. Visit /api/sentry-diagnostics to run a diagnostic test

NPM Installation

The Sentry SDK is installed as a dependency via:

npm install @sentry/node