SDK Reference

Complete reference for the @a11ops/sdk package, including alerts, log monitoring, and all available methods.

Installation

npm install @a11ops/sdk
# or
yarn add @a11ops/sdk
# or
pnpm add @a11ops/sdk

Basic Setup

import A11ops from '@a11ops/sdk';

const client = new A11ops('your-api-key', {
  baseUrl: 'https://api.a11ops.com',  // Optional
  environment: 'production',           // Optional
  release: '1.0.0',                    // Optional
  logMonitoring: true,                 // Enable log monitoring
  autoCaptureErrors: true,             // Auto-capture unhandled errors
  autoBreadcrumbs: true                // Auto-capture breadcrumbs
});

Alert Methods

1. alert

Send individual alerts with full context

await client.alert({
  title: 'Database Connection Lost',     // Required
  message: 'Primary database is unreachable', // Optional details
  severity: 'critical',                  // critical, high, medium, low, info
  metadata: {                            // Optional custom data
    server: 'db-primary-01',
    region: 'us-east-1',
    attemptedRetries: 3
  }
});

Use when:

  • Immediate notification needed for single event
  • System failures or critical errors
  • Threshold breaches (CPU, memory, disk)
  • Security events

2. batchAlert

Send multiple alerts efficiently in one request

await client.batchAlert([
  {
    title: 'High CPU Usage',
    severity: 'warning',
    metadata: { cpu: '85%', server: 'web-01' }
  },
  {
    title: 'Memory Threshold Exceeded',
    severity: 'medium',
    metadata: { memory: '92%', server: 'web-01' }
  },
  {
    title: 'Disk Space Low',
    severity: 'high',
    metadata: { disk: '95%', partition: '/data' }
  }
]);

Use when:

  • Multiple related alerts from system health checks
  • Periodic monitoring reports
  • Bulk processing results
  • Reducing API calls for better performance

Severity Levels

CRITICALSystem down, data loss risk, immediate action required
HIGHService degraded, action needed soon
MEDIUMPotential issues, monitor closely
LOWMinor issues, informational
INFOStatus updates, metrics, logs

Log Monitoring Methods

1. captureError

For errors and exceptions

client.logs.captureError(error, {
  level: 'error',        // error, fatal, critical
  user: { id: 123 },     // User context
  tags: { version: '1.0' }, // Custom tags
  extra: { cart: [] }    // Additional data
});

Use when:

  • Catching exceptions in try/catch blocks
  • Handling API errors
  • Database connection failures
  • Any Error object

2. captureMessage

For messages and events

client.logs.captureMessage('Payment processed', 'info', {
  user: { id: 123 },
  extra: { amount: 99.99 }
});

Use when:

  • Logging important events (user signup, payment)
  • Warning conditions (low inventory, high CPU)
  • Debug information
  • Non-error notifications

3. captureLog

General purpose - handles anything

// Handles different input types automatically
client.logs.captureLog('Simple string');           // → captureMessage
client.logs.captureLog(new Error('Oops'));         // → captureError  
client.logs.captureLog({ message: 'Custom', data: {} }); // → captureMessage with extra

Use when:

  • You want flexibility
  • Input type varies
  • Building generic error handlers
  • Migrating from other logging systems

Automatic Features

Auto-capture

Automatically captures unhandled errors, promise rejections, and network failures without additional code.

Breadcrumbs

Records user actions, console logs, navigation, and API calls to provide context for debugging.

User Context

Attach user information to all logs to understand who is affected by issues.

Environment Info

Automatically collects browser, OS, device info (frontend) or Node.js runtime details (backend).

Real-World Example

Complete example showing error handling in a payment flow:

// In your app
try {
  await processPayment(order);
  
  // Log success event
  client.logs.captureMessage('Payment successful', 'info', {
    extra: { 
      orderId: order.id, 
      amount: order.total,
      paymentMethod: order.paymentMethod
    }
  });
  
} catch (error) {
  // Log the error with full context
  client.logs.captureError(error, {
    level: 'critical',
    user: { 
      id: user.id, 
      email: user.email 
    },
    tags: {
      feature: 'payment',
      environment: 'production'
    },
    extra: { 
      orderId: order.id,
      attemptNumber: retryCount
    }
  });
  
  // Also send an alert for immediate attention
  await client.alert({
    title: 'Payment Failed',
    message: `Payment processing failed for order ${order.id}`,
    severity: 'critical'
  });
}

Context Management

Set persistent context that will be included with all subsequent logs:

// Set user context
client.logs.setUser({
  id: user.id,
  email: user.email,
  username: user.username
});

// Add custom context
client.logs.setContext('subscription', {
  plan: 'premium',
  expires: '2024-12-31'
});

// Add tags for filtering
client.logs.setTag('version', '2.0.0');
client.logs.setTag('feature', 'checkout');

// Manually add breadcrumb
client.logs.addBreadcrumb({
  type: 'navigation',
  category: 'page',
  message: 'User viewed checkout page',
  level: 'info'
});

Related Documentation

Getting Started →Log Monitoring Guide →API Reference →Best Practices →