Pharos is a powerful uptime and incident monitoring platform that helps you track the health of your APIs, servers, and services. This guide will walk you through setting up your first monitoring endpoint.

Quick Setup

1. Create an account and log in to your dashboard
2. Navigate to the Endpoints page and click "Add Endpoint"
3. Configure your endpoint with the desired check type
4. Set up notifications to get alerts when issues occur
5. Create a status page to communicate with your customers

Supported Check Types

• HTTP/HTTPS: Monitor web endpoints with custom headers and expected responses
• Ping (ICMP): Check server availability and network latency
• TCP Port: Verify that specific ports are open and accepting connections

Pharos uses API keys for programmatic access to the platform. You can create API keys with different permission levels from your dashboard.

Creating an API Key

1. Navigate to Settings → API Keys
2. Click "Create API Key"
3. Enter a name and select permissions (read, write, admin)
4. Copy and securely store your API key (it will only be shown once)

Permission Levels

• Read: View endpoints, health checks, and analytics
• Write: Create and update endpoints, incidents, and contacts
• Admin: Full access including team management and billing

Health checks are automated tests that run at regular intervals to verify your services are working correctly. Pharos supports multiple check types with customizable configurations.

HTTP/HTTPS Checks

Monitor web endpoints by sending HTTP requests and validating responses:

• Configure request method (GET, POST, PUT, etc.)
• Add custom headers (authentication, content-type, etc.)
• Validate response status codes (200, 201, etc.)
• Check for expected text in response body
• Monitor TLS certificate expiry dates

Ping Checks

Use ICMP ping to verify server availability and measure network latency:

• Check if servers are reachable
• Measure round-trip time
• Detect network issues

Port Checks

Verify that specific TCP ports are open and accepting connections:

• Monitor database ports (3306, 5432, etc.)
• Check custom application ports
• Verify firewall configurations

Configuring Checks from Dashboard

To configure a health check, navigate to Endpoints → Add Endpoint and fill in the required fields including check type, URL/host, check interval, timeout, and any custom headers or expected responses.

Endpoints represent the services you want to monitor. Each endpoint can have its own check configuration, notification settings, and analytics.

Creating an Endpoint

From the dashboard, navigate to Endpoints and click "Add Endpoint". Enter the endpoint name, select the check type (HTTP, Ping, or Port), configure the URL or host, set the check interval and timeout, and optionally add custom headers or expected responses. Click Save to start monitoring.

Endpoint States

• Up: All recent checks passed successfully
• Down: Recent checks are failing
• Degraded: Some checks failing, not all

Viewing Endpoint Analytics

Click on any endpoint card in the dashboard to view detailed analytics including uptime percentage, response times, check history, and incidents. You can filter by different time periods (24h, 7d, 30d, 90d).

Incidents help you track and communicate outages or issues. They're automatically created when checks fail, or you can create them manually.

Incident Lifecycle

1. Investigating: Issue identified, team is investigating
2. Identified: Root cause found, working on fix
3. Monitoring: Fix deployed, monitoring for stability
4. Resolved: Issue completely resolved

Creating an Incident

Navigate to Incidents and click "Create Incident". Enter a title, select severity level (low, medium, high, critical), set the status, optionally select affected endpoints, and add a description. The incident will appear on your status page if configured.

Severity Levels

• Low: Minor issues, no customer impact
• Medium: Degraded performance
• High: Major functionality impaired
• Critical: Complete service outage

Status pages are public-facing pages that display the current status of your services. They help keep your customers informed during outages and build trust through transparency.

Creating a Status Page

Navigate to Status Pages and click "Create Status Page". Enter a name, choose a unique slug (URL path), optionally configure a custom domain, upload your logo, and select primary and secondary brand colors. Toggle whether to show response times publicly.

Adding Endpoints to Status Page

Click "Manage Endpoints" on your status page card. Select which endpoints should appear on your public status page. This lets you control what information is publicly visible to your customers.

Customization Options

• Custom logo and branding colors
• Custom domain (CNAME to our servers)
• Toggle response time visibility
• Select which endpoints to display
• Automatic incident updates

Stay informed when issues occur by configuring email and webhook notifications. You can create different notification contacts and assign them to specific endpoints.

Creating a Contact

Navigate to Contacts and click "Add Contact". Enter a name for the contact (e.g., "On-Call Team"), then configure notification channels. Enable email notifications by providing an email address, and/or enable webhook notifications by providing a webhook URL.

Assigning Contacts to Endpoints

From the endpoint details page, click "Manage Contacts" or use the "Assign Contacts" button. Select contacts to notify and configure when they should be notified (on endpoint down, up, or degraded status).

Webhook Notifications

When configured, Pharos sends webhook notifications to your specified URL with event details including endpoint information, status, timestamp, and error messages. This allows integration with Slack, PagerDuty, or custom systems.

Collaborate with your team by inviting members with different roles and permissions. Manage access to ensure the right people have the right level of control.

User Roles

• Admin: Full access to all features including billing and team management
• Developer: Can manage endpoints, incidents, and view analytics

Inviting Team Members

1. Navigate to Settings → Team
2. Click "Invite Member"
3. Enter email address and select role
4. Send invitation
5. Team member receives email with acceptance link

Track the performance and reliability of your endpoints with detailed analytics and visualizations. Monitor uptime percentages, response times, and incident history.

Available Metrics

• Uptime Percentage: Track availability over time (last 24h, 7d, 30d, 90d)
• Response Time: Monitor latency trends and identify performance degradation
• Status Distribution: View breakdown of successful vs failed checks
• Incident History: See all past incidents with duration and resolution times

Viewing Analytics

Access analytics from the Analytics page in your dashboard. Filter by time period (24h, 7d, 30d, 90d) to see uptime trends, response time charts, status distribution, and incident history for all your endpoints.

The Pharos SDK allows you to send monitoring events directly from your application. Track background jobs, send health pings, and create incidents programmatically.

Install via npm

npm install pharos-sdk

Install via yarn

yarn add pharos-sdk

Install via pnpm

pnpm add pharos-sdk

Requirements

• Node.js 18 or higher
• TypeScript 5.0+ (recommended)

Initialize the Pharos client with your API key and optional configuration. The client handles authentication, retries, and error handling automatically.

Basic Setup

import { PharosClient } from 'pharos-sdk';

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

export { pharos };

Configuration Options

type PharosConfig = {
  // Required: Your Pharos API key
  apiKey: string;

  // Optional: Base URL (default: https://api.usepharos.online)
  baseUrl?: string;

  // Optional: Service name for tracking
  serviceName?: string;

  // Optional: Environment (production, staging, etc.)
  environment?: string;

  // Optional: Request timeout in ms (default: 5000)
  timeout?: number;

  // Optional: Max retry attempts (default: 3)
  maxRetries?: number;

  // Optional: Initial retry delay in ms (default: 1000)
  retryDelay?: number;
};

Send periodic health pings to confirm your service is running. These are simple heartbeat signals that don't require any specific check configuration.

Basic Health Ping

import { pharos } from './pharos';

// Simple health ping
await pharos.health.ping();

// Health ping with metadata
await pharos.health.ping({
  metadata: {
    version: '1.2.3',
    region: 'us-east-1',
    instanceId: 'i-1234567890',
  },
});

Scheduled Health Pings

// Send health ping every 5 minutes
setInterval(async () => {
  try {
    await pharos.health.ping({
      metadata: {
        uptime: process.uptime(),
        memoryUsage: process.memoryUsage(),
      },
    });
  } catch (error) {
    console.error('Failed to send health ping:', error);
  }
}, 5 * 60 * 1000);

Track the execution of background jobs, scheduled tasks, and long-running processes. Monitor job duration, success rates, and failures.

Basic Job Tracking

import { pharos } from './pharos';

async function dailyBackup() {
  // Mark job start
  await pharos.jobs.start({
    jobName: 'daily-backup',
    metadata: {
      startedBy: 'scheduler',
      databaseCount: 5,
    },
  });

  const startTime = Date.now();

  try {
    // Perform backup
    await performBackup();

    // Mark job success
    await pharos.jobs.complete({
      jobName: 'daily-backup',
      duration: Date.now() - startTime,
      metadata: {
        filesBackedUp: 1247,
        totalSize: '2.3GB',
      },
    });
  } catch (error) {
    // Mark job failure
    await pharos.jobs.fail({
      jobName: 'daily-backup',
      error: error.message,
      duration: Date.now() - startTime,
      metadata: {
        failureReason: error.code,
      },
    });

    throw error;
  }
}

Job Tracking with Decorator

// Helper function to track any async function
async function trackJob<T>(
  jobName: string,
  fn: () => Promise<T>
): Promise<T> {
  await pharos.jobs.start({ jobName });
  const startTime = Date.now();

  try {
    const result = await fn();
    await pharos.jobs.complete({
      jobName,
      duration: Date.now() - startTime,
    });
    return result;
  } catch (error) {
    await pharos.jobs.fail({
      jobName,
      error: error.message,
      duration: Date.now() - startTime,
    });
    throw error;
  }
}

// Usage
await trackJob('email-digest', async () => {
  await sendEmailDigest();
});

Create incidents programmatically when your application detects errors or anomalies. This allows you to track application-level issues alongside infrastructure monitoring.

Creating Incidents

import { pharos } from './pharos';

// Create a critical incident
await pharos.incidents.create({
  title: 'Database Connection Pool Exhausted',
  severity: 'critical',
  description: 'All database connections are in use. New requests are failing.',
  metadata: {
    activeConnections: 100,
    maxConnections: 100,
    queuedRequests: 47,
  },
});

// Create incident with endpoint association
await pharos.incidents.create({
  title: 'Payment Gateway Timeout',
  severity: 'high',
  description: 'Payment processing taking longer than 30 seconds',
  endpointId: 'endpoint-123',
  metadata: {
    averageResponseTime: '35s',
    affectedTransactions: 12,
  },
});

Incident Severity Levels

type IncidentSeverity = 'low' | 'medium' | 'high' | 'critical';

// Examples
await pharos.incidents.create({
  title: 'Cache hit rate below threshold',
  severity: 'low',  // Minor issue, no immediate action needed
});

await pharos.incidents.create({
  title: 'API response time degraded',
  severity: 'medium',  // Performance issue, investigate
});

await pharos.incidents.create({
  title: 'Service outage in EU region',
  severity: 'high',  // Major functionality impaired
});

await pharos.incidents.create({
  title: 'Complete system failure',
  severity: 'critical',  // Total outage, immediate attention
});

Error Monitoring Integration

// Automatically create incidents for uncaught errors
process.on('uncaughtException', async (error) => {
  await pharos.incidents.create({
    title: `Uncaught Exception: ${error.name}`,
    severity: 'critical',
    description: error.message,
    metadata: {
      stack: error.stack,
      timestamp: new Date().toISOString(),
    },
  });

  process.exit(1);
});

// Track errors in Express middleware
app.use(async (err, req, res, next) => {
  if (err.statusCode >= 500) {
    await pharos.incidents.create({
      title: `Server Error: ${err.message}`,
      severity: 'high',
      description: `${req.method} ${req.path} failed`,
      metadata: {
        statusCode: err.statusCode,
        path: req.path,
        method: req.method,
      },
    });
  }

  next(err);
});