|
| 1 | +# Sentry Integration Guide |
| 2 | + |
| 3 | +## Backend Services (Node.js) |
| 4 | + |
| 5 | +### 1. Initialize Sentry at service startup |
| 6 | + |
| 7 | +```typescript |
| 8 | +import { initSentry } from '@syntera/shared/logger/sentry.js' |
| 9 | +import { createLogger } from '@syntera/shared/logger/index.js' |
| 10 | + |
| 11 | +// Initialize Sentry BEFORE creating loggers |
| 12 | +initSentry({ |
| 13 | + dsn: process.env.SENTRY_DSN, |
| 14 | + environment: process.env.NODE_ENV || 'development', |
| 15 | + release: process.env.APP_VERSION, |
| 16 | + tracesSampleRate: process.env.NODE_ENV === 'production' ? 0.1 : 1.0, |
| 17 | +}) |
| 18 | + |
| 19 | +// Now create logger (it will automatically include Sentry transport) |
| 20 | +const logger = createLogger('agent-service') |
| 21 | +``` |
| 22 | + |
| 23 | +### 2. Set user context (when user is authenticated) |
| 24 | + |
| 25 | +```typescript |
| 26 | +import { setSentryUser } from '@syntera/shared/logger/sentry.js' |
| 27 | + |
| 28 | +// In your auth middleware or route handler |
| 29 | +setSentryUser(userId, userEmail, userName) |
| 30 | +``` |
| 31 | + |
| 32 | +### 3. Add context to errors |
| 33 | + |
| 34 | +```typescript |
| 35 | +import { setSentryContext } from '@syntera/shared/logger/sentry.js' |
| 36 | + |
| 37 | +// Before logging an error |
| 38 | +setSentryContext({ |
| 39 | + tags: { |
| 40 | + agentId: 'xxx', |
| 41 | + conversationId: 'yyy', |
| 42 | + }, |
| 43 | + extra: { |
| 44 | + requestId: 'zzz', |
| 45 | + customData: 'value', |
| 46 | + }, |
| 47 | +}) |
| 48 | + |
| 49 | +logger.error('Something went wrong', { error }) |
| 50 | +``` |
| 51 | + |
| 52 | +### 4. Express error middleware |
| 53 | + |
| 54 | +```typescript |
| 55 | +import * as Sentry from '@sentry/node' |
| 56 | +import { handleError } from '@syntera/shared/utils/errors.js' |
| 57 | + |
| 58 | +app.use((err: Error, req: Request, res: Response, next: NextFunction) => { |
| 59 | + // Capture to Sentry |
| 60 | + Sentry.captureException(err, { |
| 61 | + tags: { |
| 62 | + route: req.path, |
| 63 | + method: req.method, |
| 64 | + }, |
| 65 | + extra: { |
| 66 | + body: req.body, |
| 67 | + query: req.query, |
| 68 | + }, |
| 69 | + }) |
| 70 | + |
| 71 | + // Then handle normally |
| 72 | + handleError(err, res) |
| 73 | +}) |
| 74 | +``` |
| 75 | + |
| 76 | +## Environment Variables |
| 77 | + |
| 78 | +Add to your `.env` files: |
| 79 | + |
| 80 | +```bash |
| 81 | +# Sentry Configuration |
| 82 | +SENTRY_DSN=https://xxx@xxx.ingest.sentry.io/xxx |
| 83 | +NODE_ENV=production |
| 84 | +APP_VERSION=1.0.0 |
| 85 | +``` |
| 86 | + |
| 87 | +## Example: Agent Service |
| 88 | + |
| 89 | +```typescript |
| 90 | +// services/agent/src/index.ts |
| 91 | +import { initSentry } from '@syntera/shared/logger/sentry.js' |
| 92 | +import { createLogger } from '@syntera/shared/logger/index.js' |
| 93 | + |
| 94 | +// Initialize Sentry first |
| 95 | +if (process.env.SENTRY_DSN) { |
| 96 | + initSentry({ |
| 97 | + dsn: process.env.SENTRY_DSN, |
| 98 | + environment: process.env.NODE_ENV || 'development', |
| 99 | + }) |
| 100 | +} |
| 101 | + |
| 102 | +// Create logger (will include Sentry if initialized) |
| 103 | +const logger = createLogger('agent-service') |
| 104 | + |
| 105 | +// Rest of your service code... |
| 106 | +``` |
| 107 | + |
0 commit comments