Pharos SDK Use Cases

15 Ways to Use
the Pharos SDK

From health monitoring to automated alerting, discover how teams use the Pharos SDK to build more reliable applications and respond faster to incidents.

Monitoring
Alerting
Debugging
Reliability

Standardized Health Endpoints

Monitoring

Create production-ready health endpoints with built-in dependency checking, timeout handling, and Pharos-compatible response schemas. Works with Next.js, Express, Fastify, and more.

Benefits:

  • Standardized health response schema
  • Critical vs non-critical dependency checks
  • Automatic timeout handling and error boundaries
  • Framework adapters for easy integration
typescript
// Next.js App Router
import { respondNextJs } from '@skdevlabs/pharos-sdk/adapters/nextjs';

export async function GET() {
  return await respondNextJs(pharos, {
    version: '1.0.0',
    checks: {
      db: {
        fn: async () => {
          await db.ping();
          return { status: 'ok', latencyMs: 12 };
        },
        critical: true  // Service "down" if fails
      },
      redis: async () => ({ status: 'ok' }) // Non-critical
    }
  });
}

Service Health Monitoring

Monitoring

Track the health of your microservices across multiple environments. Send periodic health pings to ensure services are alive and responding.

Benefits:

  • Monitor service availability in real-time
  • Detect service outages immediately
  • Track health across production, staging, and development
  • Identify which services are stale or inactive
typescript
import { PharosClient } from '@skdevlabs/pharos-sdk';

const pharos = new PharosClient({
  apiKey: process.env.PHAROS_API_KEY,
  serviceName: 'payment-service',
  environment: 'production'
});

// Send health ping every 5 minutes
setInterval(async () => {
  await pharos.health.ping();
}, 5 * 60 * 1000);

Background Job Tracking

Monitoring

Monitor all your background jobs, cron tasks, and async operations. Track success rates, failure patterns, and execution durations.

Benefits:

  • Know when jobs fail before users complain
  • Track job execution times and performance
  • Identify jobs with low success rates
  • Monitor job frequency and patterns
typescript
// Track any background job
await pharos.jobs.start({ jobName: 'data-export' });

try {
  await exportDataToS3();
  await pharos.jobs.complete({
    jobName: 'data-export',
    duration: 1500
  });
} catch (error) {
  await pharos.jobs.fail({
    jobName: 'data-export',
    error: error.message
  });
}

Critical Error Detection

Alerting

Automatically create incidents when critical errors occur in your application. No manual incident creation needed.

Benefits:

  • Catch critical errors before they escalate
  • Automatic incident creation from code
  • Severity-based prioritization
  • Link incidents to specific services or endpoints
typescript
// Automatically create incident on critical error
try {
  await connectToDatabase();
} catch (error) {
  await pharos.incidents.create({
    title: 'Database Connection Failed',
    severity: 'critical',
    description: `Unable to connect: ${error.message}`,
    metadata: {
      serviceName: 'api-server',
      errorCode: error.code
    }
  });
  throw error;
}

Automated Team Notifications

Alerting

Get your entire team notified when incidents occur or jobs fail. Email alerts sent automatically to all users and contacts.

Benefits:

  • Instant email notifications on failures
  • No duplicate emails (smart deduplication)
  • Severity-based email formatting
  • Troubleshooting tips included in job failure emails
typescript
// All team members receive email when this fails
await pharos.jobs.fail({
  jobName: 'email-batch-send',
  error: 'SMTP timeout after 30s',
  duration: 30000
});

// Email subject: [Alert] Job Failed: email-batch-send
// All active users + contacts notified automatically

Database Health Checks

Monitoring

Monitor database connection pools, query performance, and availability. Create incidents when database issues are detected.

Benefits:

  • Detect connection pool exhaustion
  • Monitor query response times
  • Track database availability
  • Alert on replication lag or failovers
typescript
// Monitor database connection pool
const pool = await getConnectionPool();

if (pool.activeConnections > pool.maxConnections * 0.9) {
  await pharos.incidents.create({
    title: 'Database Pool Near Limit',
    severity: 'high',
    description: `Pool at ${pool.activeConnections}/${pool.maxConnections}`
  });
}

Performance Degradation Detection

Monitoring

Track job execution times and detect when performance degrades. Set up automated alerts when operations take longer than expected.

Benefits:

  • Identify slow operations before users notice
  • Track performance trends over time
  • Compare execution times across environments
  • Proactive performance optimization
typescript
const startTime = Date.now();

await pharos.jobs.start({ jobName: 'report-generation' });

const result = await generateReport();
const duration = Date.now() - startTime;

// Alert if job takes longer than 5 seconds
if (duration > 5000) {
  await pharos.incidents.create({
    title: 'Report Generation Slow',
    severity: 'medium',
    description: `Took ${duration}ms (expected <5000ms)`
  });
}

await pharos.jobs.complete({ jobName: 'report-generation', duration });

API Rate Limit Monitoring

Alerting

Track API usage and create incidents when approaching rate limits. Prevent service disruptions from hitting third-party limits.

Benefits:

  • Avoid hitting rate limits unexpectedly
  • Track API quota usage trends
  • Proactive capacity planning
  • Prevent service disruptions
typescript
// Monitor third-party API usage
const usage = await checkStripeAPIUsage();

if (usage.remaining < usage.limit * 0.1) {
  await pharos.incidents.create({
    title: 'Stripe API Rate Limit Warning',
    severity: 'medium',
    description: `Only ${usage.remaining} requests remaining`
  });
}

Deployment Health Verification

Reliability

Send health pings after deployments to verify services started correctly. Create incidents if post-deployment health checks fail.

Benefits:

  • Verify deployments succeeded
  • Detect rollout issues immediately
  • Track deployment health across environments
  • Automated rollback triggers
typescript
// After deployment
async function verifyDeployment() {
  await new Promise(resolve => setTimeout(resolve, 10000)); // Wait 10s

  try {
    await pharos.health.ping();
    console.log('✅ Deployment successful');
  } catch (error) {
    await pharos.incidents.create({
      title: 'Deployment Failed - Service Unhealthy',
      severity: 'critical',
      description: 'Service failed health check post-deployment'
    });
  }
}

Multi-Environment Monitoring

Monitoring

Track the same services across production, staging, and development. Identify environment-specific issues quickly.

Benefits:

  • Compare health across environments
  • Catch staging issues before production
  • Environment-specific incident tracking
  • Unified monitoring dashboard
typescript
// Production instance
const pharosProd = new PharosClient({
  apiKey: process.env.PHAROS_API_KEY,
  serviceName: 'api-server',
  environment: 'production'
});

// Staging instance
const pharosStaging = new PharosClient({
  apiKey: process.env.PHAROS_API_KEY,
  serviceName: 'api-server',
  environment: 'staging'
});

// Both appear separately in dashboard

Security Event Tracking

Alerting

Create high-severity incidents when security events are detected. Track failed login attempts, unauthorized access, or suspicious activity.

Benefits:

  • Immediate security incident alerts
  • Track security event patterns
  • Compliance audit trails
  • Coordinated security response
typescript
// Track security events
async function handleFailedLogin(username, ip) {
  failedAttempts.increment(ip);

  if (failedAttempts.get(ip) > 5) {
    await pharos.incidents.create({
      title: 'Possible Brute Force Attack',
      severity: 'high',
      description: `${failedAttempts.get(ip)} failed attempts from ${ip}`,
      metadata: { username, ip, timestamp: Date.now() }
    });
  }
}

Team Collaboration on Issues

Reliability

When SDK creates incidents, all team members are notified. Use the dashboard to track resolution status and collaborate.

Benefits:

  • Entire team notified instantly
  • Centralized incident tracking
  • Status updates visible to all
  • Track who resolved what
typescript
// SDK creates incident - all team members notified
await pharos.incidents.create({
  title: 'Payment Gateway Timeout',
  severity: 'critical',
  description: 'Stripe API timing out after 30s'
});

// Team sees incident in dashboard
// Updates status: investigating → identified → resolved
// All team members receive status change emails

SLA & Uptime Tracking

Reliability

Monitor service uptime and job success rates. Track SLA compliance and identify services that need attention.

Benefits:

  • Calculate real uptime percentages
  • Track job success rates over time
  • SLA compliance reporting
  • Identify reliability trends
typescript
// SDK Activity dashboard shows:
// - Job success rates (95%, 87%, 100%)
// - Last run times for each job
// - Service health status (healthy, stale, inactive)
// - Incident history and resolution times

// Perfect for SLA reporting and customer communication

Custom Metrics & Events

Debugging

Track any custom events or metrics using the SDK. Store metadata for later analysis and debugging.

Benefits:

  • Track custom business metrics
  • Store contextual data with events
  • Flexible metadata structure
  • Rich debugging information
typescript
// Track custom events with metadata
await pharos.jobs.complete({
  jobName: 'data-sync',
  duration: 2500,
  metadata: {
    recordsProcessed: 15000,
    dataSource: 'postgres',
    compressionRatio: 0.73,
    s3Bucket: 'backups-prod'
  }
});

// View metadata in SDK Activity dashboard

Debugging Production Issues

Debugging

Use the SDK Activity dashboard to debug production issues. See exactly when jobs failed, what errors occurred, and service health status.

Benefits:

  • Historical view of all events
  • Filter by service, job, or time range
  • See error messages and stack traces
  • Correlate incidents with job failures
typescript
// SDK Activity dashboard shows:
// 1. Health Pings - Which services are alive
// 2. Jobs - Which jobs failed and why
// 3. Incidents - What went wrong and when

// Example: "Why did data-export fail yesterday?"
// → Check Jobs tab → See failure at 3:42 AM
// → Error: "S3 bucket permission denied"
// → Duration: 5000ms (usually 1500ms)

Ready to Get Started?

Install the Pharos SDK and start monitoring your services in minutes.

Install via npm:

bash
npm install @skdevlabs/pharos-sdk
View DocumentationGet Started Free

© 2025 Pharos. All rights reserved.