Logs & Metrics

Send structured logs and custom metrics to Sentry

Sentry supports sending structured logs and custom metrics alongside your error and performance data, providing a complete observability solution.

Logs

Sentry logs provide structured, searchable logging with automatic correlation to traces and errors.

Setup

Enable logs in your SDK initialization:

import * as Sentry from '@sentry/node';

Sentry.init({
  dsn: 'your-dsn',
  
  // Enable logs
  enableLogs: true,
  
  // Configure log levels
  logLevel: 'info', // minimum level to capture
});

Capturing Logs

Use the logger API to send structured logs:

import * as Sentry from '@sentry/node';

// Different log levels
Sentry.logger.trace('Detailed trace information');
Sentry.logger.debug('Debug information', { component: 'UserService' });
Sentry.logger.info('User logged in', { userId: '123' });
Sentry.logger.warn('Deprecated API used', { endpoint: '/old-api' });
Sentry.logger.error('Operation failed', { error: 'Connection timeout' });
Sentry.logger.fatal('Critical system failure', { service: 'database' });

Logs require the enableLogs option to be set to true during initialization.

Log Attributes

Add structured data to logs:

Sentry.logger.info('User action', {
  user_id: '123',
  action: 'purchase',
  product_id: 'prod-456',
  amount: 99.99,
  currency: 'USD',
  payment_method: 'credit_card'
});

Template Strings

Use template strings for structured logging:

import * as Sentry from '@sentry/node';

const userId = '123';
const page = '/dashboard';

// Parameterized log message
Sentry.logger.info(
  Sentry.logger.fmt`User ${userId} navigated to ${page}`,
  {
    userId: '123',
    sessionId: 'abc-xyz'
  }
);

Template strings allow Sentry to group similar log messages together while preserving the actual values.

Log with Scope

Capture logs with specific scope:

import { getCurrentScope } from '@sentry/node';

const scope = getCurrentScope();
scope.setTag('service', 'payment');

Sentry.logger.info('Payment processed', {
  order_id: '123',
  amount: 99.99
}, {
  scope // Use this specific scope
});

Log Levels

• trace: Very detailed diagnostic information
• debug: Detailed information for debugging
• info: General informational messages
• warn: Warning messages for potentially harmful situations
• error: Error events
• fatal: Very severe error events that might lead to application abort

Metrics

Custom metrics help you track business and technical KPIs.

Counters

Increment counters for counting events:

import * as Sentry from '@sentry/node';

// Increment by 1
Sentry.metrics.count('api.requests', 1, {
  attributes: {
    endpoint: '/api/users',
    method: 'GET',
    status: 200
  }
});

// Increment by custom value
Sentry.metrics.count('items.processed', 5, {
  attributes: {
    processor: 'batch-1',
    queue: 'high-priority'
  }
});

Gauges

Record current values:

// Memory usage
Sentry.metrics.gauge('memory.usage', 1024, {
  unit: 'megabyte',
  attributes: {
    process: 'web-server',
    region: 'us-east-1'
  }
});

// Active connections
Sentry.metrics.gauge('connections.active', 42, {
  attributes: {
    server: 'api-1',
    protocol: 'websocket'
  }
});

// Queue depth
Sentry.metrics.gauge('queue.depth', 150, {
  unit: 'item',
  attributes: {
    queue: 'email-notifications'
  }
});

Distributions

Record value distributions for statistical analysis:

// Request duration
Sentry.metrics.distribution('request.duration', 245, {
  unit: 'millisecond',
  attributes: {
    endpoint: '/api/users',
    method: 'GET'
  }
});

// Response size
Sentry.metrics.distribution('response.size', 1024, {
  unit: 'byte',
  attributes: {
    endpoint: '/api/data',
    compression: 'gzip'
  }
});

// Batch size
Sentry.metrics.distribution('batch.size', 100, {
  attributes: {
    processor: 'data-pipeline',
    type: 'async'
  }
});

Metric Units

Use standard units for better visualization:

// Time units
Sentry.metrics.distribution('duration', 500, { unit: 'millisecond' });
Sentry.metrics.distribution('latency', 1.5, { unit: 'second' });

// Size units
Sentry.metrics.gauge('memory', 512, { unit: 'megabyte' });
Sentry.metrics.distribution('payload', 1024, { unit: 'byte' });

// Custom units
Sentry.metrics.gauge('temperature', 72, { unit: 'fahrenheit' });
Sentry.metrics.count('requests', 100, { unit: 'request' });

Correlation with Traces

Logs and metrics are automatically correlated with active spans:

import * as Sentry from '@sentry/node';

Sentry.startSpan({ name: 'process_order', op: 'function' }, () => {
  // Log is automatically linked to span
  Sentry.logger.info('Processing order', { orderId: '123' });
  
  // Metric is linked to trace
  Sentry.metrics.count('orders.processed', 1, {
    attributes: { status: 'success' }
  });
  
  processOrder();
});

Logs and metrics captured within a span are automatically tagged with the trace ID and span ID.

Practical Examples

API Monitoring

import * as Sentry from '@sentry/node';
import express from 'express';

const app = express();

app.use((req, res, next) => {
  const start = Date.now();
  
  res.on('finish', () => {
    const duration = Date.now() - start;
    
    // Log request
    Sentry.logger.info(
      Sentry.logger.fmt`${req.method} ${req.path}`,
      {
        method: req.method,
        path: req.path,
        status: res.statusCode,
        duration
      }
    );
    
    // Count requests
    Sentry.metrics.count('api.requests', 1, {
      attributes: {
        method: req.method,
        endpoint: req.route?.path || req.path,
        status: res.statusCode
      }
    });
    
    // Track duration
    Sentry.metrics.distribution('api.duration', duration, {
      unit: 'millisecond',
      attributes: {
        endpoint: req.route?.path || req.path
      }
    });
  });
  
  next();
});

Database Operations

import * as Sentry from '@sentry/node';

async function queryDatabase(sql, params) {
  const start = Date.now();
  
  try {
    const result = await db.query(sql, params);
    const duration = Date.now() - start;
    
    // Log successful query
    Sentry.logger.debug('Database query executed', {
      query: sql,
      rows: result.rowCount,
      duration
    });
    
    // Track query count
    Sentry.metrics.count('db.queries', 1, {
      attributes: {
        operation: getOperationType(sql),
        status: 'success'
      }
    });
    
    // Track query duration
    Sentry.metrics.distribution('db.query.duration', duration, {
      unit: 'millisecond',
      attributes: {
        operation: getOperationType(sql)
      }
    });
    
    return result;
  } catch (error) {
    // Log error
    Sentry.logger.error('Database query failed', {
      query: sql,
      error: error.message
    });
    
    // Count errors
    Sentry.metrics.count('db.errors', 1, {
      attributes: {
        error_type: error.code
      }
    });
    
    throw error;
  }
}

Business Metrics

import * as Sentry from '@sentry/node';

async function processOrder(order) {
  Sentry.logger.info('Processing order', {
    order_id: order.id,
    user_id: order.userId,
    amount: order.total
  });
  
  // Count orders
  Sentry.metrics.count('orders.processed', 1, {
    attributes: {
      payment_method: order.paymentMethod,
      country: order.shippingAddress.country
    }
  });
  
  // Track order value
  Sentry.metrics.distribution('order.value', order.total, {
    unit: 'dollar',
    attributes: {
      currency: order.currency,
      payment_method: order.paymentMethod
    }
  });
  
  // Track order items
  Sentry.metrics.distribution('order.items', order.items.length, {
    unit: 'item'
  });
  
  await saveOrder(order);
}

Resource Monitoring

import * as Sentry from '@sentry/node';
import os from 'os';

// Monitor system resources
setInterval(() => {
  const memUsage = process.memoryUsage();
  const cpuUsage = process.cpuUsage();
  
  // Memory metrics
  Sentry.metrics.gauge('memory.heap_used', memUsage.heapUsed, {
    unit: 'byte'
  });
  
  Sentry.metrics.gauge('memory.heap_total', memUsage.heapTotal, {
    unit: 'byte'
  });
  
  // CPU metrics
  Sentry.metrics.gauge('cpu.user', cpuUsage.user, {
    unit: 'microsecond'
  });
  
  Sentry.metrics.gauge('cpu.system', cpuUsage.system, {
    unit: 'microsecond'
  });
  
  // Log if memory is high
  if (memUsage.heapUsed / memUsage.heapTotal > 0.9) {
    Sentry.logger.warn('High memory usage', {
      heap_used: memUsage.heapUsed,
      heap_total: memUsage.heapTotal,
      percentage: Math.round((memUsage.heapUsed / memUsage.heapTotal) * 100)
    });
  }
}, 60000); // Every minute

Error Rate Tracking

import * as Sentry from '@sentry/node';

function trackOperationResult(operation, success) {
  // Log the operation
  Sentry.logger.info('Operation completed', {
    operation,
    success
  });
  
  // Count successes and failures
  Sentry.metrics.count('operations', 1, {
    attributes: {
      operation,
      status: success ? 'success' : 'failure'
    }
  });
}

try {
  await criticalOperation();
  trackOperationResult('critical_operation', true);
} catch (error) {
  trackOperationResult('critical_operation', false);
  Sentry.captureException(error);
}

Scope Integration

Logs and metrics respect scope attributes:

import { getCurrentScope } from '@sentry/node';

const scope = getCurrentScope();
scope.setAttributes({
  service: 'api',
  environment: 'production',
  region: 'us-east-1'
});

// These attributes are automatically added to logs and metrics
Sentry.logger.info('Service started');
Sentry.metrics.gauge('service.uptime', 3600, { unit: 'second' });

Best Practices

Logs

1. Use appropriate levels: Match severity to importance
2. Add context: Include relevant attributes
3. Use structured data: Avoid string concatenation
4. Avoid sensitive data: Don’t log PII or secrets
5. Use templates: For better grouping

// Good: Structured with attributes
Sentry.logger.info('User action', {
  user_id: '123',
  action: 'purchase'
});

// Bad: String concatenation
Sentry.logger.info(`User 123 made a purchase`);

Metrics

1. Choose the right type: Counter, gauge, or distribution
2. Use consistent names: Follow naming conventions
3. Add relevant attributes: For filtering and grouping
4. Use standard units: For better visualization
5. Don’t over-instrument: Focus on meaningful metrics

// Good: Clear name, appropriate type, useful attributes
Sentry.metrics.distribution('api.response_time', duration, {
  unit: 'millisecond',
  attributes: {
    endpoint: '/api/users',
    method: 'GET'
  }
});

// Bad: Vague name, no attributes
Sentry.metrics.gauge('time', duration);

Viewing Logs and Metrics

In Sentry:

1. Logs Explorer: Search and filter logs
2. Metrics Dashboard: Visualize custom metrics
3. Trace View: See logs/metrics within traces
4. Correlation: Link logs/metrics to errors

Next Steps

Performance

Monitor application performance

Tracing

Correlate logs with traces

Error Monitoring

Link errors with logs

Scopes

Manage scope attributes