Introduction

Pingui Alert is a lightweight notification service that allows you to send alerts to your Telegram account directly from your code. It's designed to be dead simple to use, with zero configuration required on your server.

System Architecture

Pingui Alert uses a queue-based architecture to ensure reliable alert delivery:

Core Components

• REST API: Receives alerts and enqueues them
• Redis Queue: Stores pending alerts (max 500 alerts)
• Queue Worker: Processes alerts at 1 msg/second (Telegram safe limit)
• Scheduled Jobs: Automatic maintenance tasks
• Telegram Bot: Interface for managing integrations

Automatic Jobs

The system runs scheduled maintenance tasks:

• Rate Limit Reset (00:00 daily): Resets daily alert counter to 10 for all users
• Database Backup (03:00 daily): Creates automatic SQLite database backups

Setup & Authentication

To start sending alerts, you need to obtain an API Key from our Telegram bot.

1. Open Telegram and search for @PinguiAlertBot (or your hosted bot instance).
2. Start a chat and send the command /start to register.
3. Send the command /temporal_token to get a temporary access token. (Once you create your first integration, you will get a new permanent token)
4. Use the API to create your first integration and start sending alerts.

The Commandments

To keep Pingui Alert useful and stable for everyone, we adhere to a strict set of rules. Follow these commandments to ensure the best experience.

1. I. Critical Use Only
   You shall use it only for critical alerts that must be corrected immediately. Design your system to trigger these alerts sparingly—only once per incident type (avoid alert storms).
2. II. Production Standards
   If you send errors from your API using our bot, you must follow production best practices. Ensure your error handling is robust before piping it to an alert.
3. III. Self-Host for Customization
   If you require any customization (no matter how simple), you shall use the self-hosted option. You can host Pingui Alert anywhere; we suggest a VPS or a local server due to its minimal resource footprint, but cloud options are also valid.
4. IV. Actionable Alerts
   You shall ensure every alert is actionable. Every alert should prompt a specific, immediate response.
5. V. No Data Leakage
   You shall not send sensitive user data (PII), identifiers, or secrets in your alerts. Keep messages safe and compliant.
6. VI. Fail Safely
   You shall implement error handling so that a failed alert notification never crashes your main application. The alert service failure should be silent to your end users.

Self-Hosting

Pingui Alert is fully open source and can be self-hosted for complete control over your alerting infrastructure.

Prerequisites

• Node.js: v20 or higher
• pnpm: v9 or higher
• Redis: For queue system (local or hosted)
• Telegram Bot Token: Create via @BotFather

Quick Setup

git clone https://github.com/juanvidev1/pingui-alert
cd pingui-alert
pnpm install

# Configure environment
cp .env.example .env
# Edit .env with your values

# Run in development
pnpm run dev

# Or build for production
pnpm run build
pnpm run start

Environment Variables

# Required
BOT_TOKEN=your_telegram_bot_token
JWT_SECRET=your_jwt_secret
REDIS_URL=redis://localhost:6379

# Optional
MAX_ALERTS=100  # Customize daily limit
MAX_QUEUE_SIZE=500
SEND_DELAY_MS=1000

Monitoring & Logs

Pingui Alert provides comprehensive logging and monitoring capabilities:

Log Files

• logs/info.log: General events and processed alerts
• logs/error.log: Application errors and send failures
• logs/jobs.log: Scheduled job execution

Monitoring Commands

# View alerts in real time
tail -f logs/info.log | grep "Sending alert"

# Monitor errors
tail -f logs/error.log

# Check job status
tail -f logs/jobs.log

# Redis queue size
redis-cli LLEN pingui:queue:alerts

System Metrics

Track system usage and performance with built-in metrics:

Available Metrics

• Total Integrations: Number of registered integrations
• Total Sent Alerts: Cumulative alerts delivered
• Total Errors: Failed alert attempts
• Last Updated: Metrics freshness timestamp

Example Response

{
  "totalIntegrations": 1234,
  "totalSentAlerts": 45678,
  "totalErrors": 23,
  "metrics": [
    {
      "totalIntegrations": 1234,
      "totalSentAlerts": 45678,
      "totalErrors": 23,
      "updatedAt": "2025-01-01T12:00:00Z"
    }
  ]
}

Production Usage

When using Pingui Alert in production environments, follow these best practices to ensure optimal service quality for everyone.

Recommended Production Setup

For production workloads with frequent notifications, we recommend one of these approaches:

• Self-Host Your Instance: Deploy your own Pingui Alert server and bot. This gives you full control over rate limits and ensures dedicated resources.
• Use for Critical Alerts Only: If using @PinguiAlertBot, implement filtering logic to send only high-priority notifications (failures, errors, security events).
• Implement Batching: Group multiple non-critical alerts into periodic summary messages instead of sending individual notifications.

Telegram Bot Commands

All interactions with Pingui Alert start from the Telegram bot. Below is the full reference for available commands.

General Commands

/help

/get_me

/temporal_token

Member Commands

/join ABC123

Owner-Only Commands

These commands require an active integration and are restricted to the integration owner.

/join_owner

/create_invite

/get_members

NPM Package

If you are using Node.js or TypeScript, we recommend using our official package in case you just want to send alerts using Pingui Alert server. Rate limit and quota are handled by the server and you need to still use the endpoint createIntegration to get your permanent API KEY.

Installation

npm install pingui-alert

Usage

1. Follow the steps in the Create Integration section to get your permanent API KEY.
2. On the public bot use the command /get_me to get your chatId.
3. Use the API KEY and chatId in the code below:

import { PinguiAlert } from 'pingui-alert-sdk';

const pinguiAlert = new PinguiAlert({
  chatId: process.env.PINGUI_ALERT_CHAT_ID,
  token: process.env.PINGUI_ALERT_API_KEY,
});

// Optional: Validate integration status before sending an alert. This checks if the integration is active and has quota.
const pinguiStatus = await pinguiAlert.validateStatus();
console.log('Pingui Alert status:', pinguiStatus); // Example response: { active: true, remainingAlerts: 9 }

// This method allows you to send an alert. The first parameter is the message to be sent. The second parameter is optional and can be used to set a title for the alert
await pinguiAlert.send('Database backup completed successfully! ✅', 'Job Completed');

Use Cases

Here are some clear examples of how to apply Pingui Alert in real-world scenarios, strictly adhering to the Commandments.

try {
  await processPayment(orderId, amount);
} catch (error) {
  // ❌ BAD: Sending the full error stack or user PII
  // await client.send(`Payment failed for user ${user.email}: ${error.stack}`);

  // ✅ GOOD: Actionable, specific, safe
  logger.error(error); // Log details locally
  await client.send(
    `🚨 Critical: Payment Gateway Failure\n` +
    `Gateway: Stripe\n` +
    `OrderId: ${orderId}\n` +
    `Action: Check Stripe Status & Logs immediately.`
  );
}

#!/bin/bash
USAGE=$(df / | grep / | awk '{ print $5 }' | sed 's/%//g')

# Only alert if usage is > 90% (Critical)
if [ "$USAGE" -gt 90 ]; then
  curl -X POST https://pingui-alert.dev/api/alert \
    -H "Authorization: Bearer $TOKEN" \
    -H "Content-Type: application/json" \
    -d '{
      "alert": "💾 Server Disk Critical\nUsage is at '"$USAGE"'%.\nClean up logs or expand volume NOW."
    }'
fi

if (failedAttempts > 10) {
  // Block IP logic...

  // Alert Security Team
  await client.send(
    `🛡️ Security Alert: Brute Force Detected\n` +
    `IP: ${req.ip}\n` +
    `Attempts: ${failedAttempts}\n` +
    `Action: IP has been temporarily banned. Verify traffic source.`
  );
}

job.on('failed', async (err) => {
  try {
    await client.send(
      `💥 Backup Job Failed\n` +
      `Job: nightly_db_backup\n` +
      `Error: Connection timeout\n` +
      `Action: Manually retry backup via admin panel.`
    );
  } catch (alertError) {
    // Fail safely - do not crash the worker if alert fails
    console.error('Failed to send alert:', alertError);
  }
});