Alert

The Alert resource allows you to create and manage alerts that notify you when metrics exceed or fall below specified thresholds in PostHog.

Example Usage

Basic Alert

import * as posthog from "pulumi-posthog";

const errorAlert = new posthog.Alert("high-errors", {
    name: "High Error Rate",
    // Use the numeric insight ID from PostHog (find in insight URL or API)
    insight: 12345,
    enabled: true,
    thresholdType: "absolute",
    thresholdUpper: 100,
    // Array of PostHog user IDs to notify (find in user settings)
    subscribedUsers: [67890],
});

const signupAlert = new posthog.Alert("low-signups", {
    name: "Low Signup Alert",
    // Get insight ID from PostHog insight URL or API
    insight: 12345,
    enabled: true,
    thresholdType: "absolute",
    thresholdLower: 10, // Alert when below 10 signups
    // Get user IDs from PostHog user settings or API
    subscribedUsers: [67890, 67891],
});

Percentage Change Alert

const growthAlert = new posthog.Alert("growth-alert", {
    name: "Revenue Growth Alert",
    insight: 23456,
    enabled: true,
    thresholdType: "percentage",
    thresholdLower: -10, // Alert on 10% decrease
    thresholdUpper: 50, // Alert on 50% increase
    subscribedUsers: [67890],
});

Daily Check Alert

const dailyAlert = new posthog.Alert("daily-check", {
    name: "Daily Active Users Check",
    insight: 34567,
    enabled: true,
    thresholdType: "absolute",
    thresholdLower: 1000,
    calculationInterval: "daily",
    subscribedUsers: [67890],
});

Weekend-Skipping Alert

const weekdayAlert = new posthog.Alert("weekday-only", {
    name: "Weekday Metrics Alert",
    insight: 45678,
    enabled: true,
    thresholdType: "absolute",
    thresholdUpper: 500,
    skipWeekend: true, // Don't check on weekends
    subscribedUsers: [67890],
});

Series-Specific Alert

const seriesAlert = new posthog.Alert("series-alert", {
    name: "Specific Metric Alert",
    insight: 56789,
    enabled: true,
    thresholdType: "absolute",
    thresholdUpper: 200,
    seriesIndex: 0, // Monitor first series in multi-series insight
    subscribedUsers: [67890],
});

Resource Properties

Required Arguments

insight (number): Numeric ID of the insight this alert monitors
thresholdType (string): Type of threshold - "absolute" for fixed values or "percentage" for relative changes
subscribedUsers (number[]): List of user IDs to notify when the alert fires

Optional Arguments

name (string): Alert name
enabled (boolean): Whether alert is enabled (default: true)
thresholdLower (number): Lower bound of the threshold - alert fires when value goes below this
thresholdUpper (number): Upper bound of the threshold - alert fires when value goes above this
calculationInterval (string): How often to check - "hourly", "daily", "weekly", or "monthly"
conditionType (string): Condition type - "absoluteValue", "relativeIncrease", or "relativeDecrease"
seriesIndex (number): Index of the trend series to monitor (0-based)
checkOngoingInterval (boolean): Whether to check the ongoing (incomplete) interval
skipWeekend (boolean): Whether to skip checking the alert on weekends

Attributes

All configured properties

Threshold Types

Absolute Value

Fixed numeric thresholds:

const alert = new posthog.Alert("absolute-alert", {
    name: "Absolute Threshold",
    insight: 12345,
    thresholdType: "absolute",
    thresholdLower: 50,  // Alert when below 50
    thresholdUpper: 200, // Alert when above 200
    subscribedUsers: [67890],
});

Percentage Change

Relative change thresholds:

const alert = new posthog.Alert("percentage-alert", {
    name: "Percentage Change",
    insight: 12345,
    thresholdType: "percentage",
    thresholdLower: -20, // Alert on 20% decrease
    thresholdUpper: 50,  // Alert on 50% increase
    subscribedUsers: [67890],
});

Calculation Intervals

Hourly

Check metrics every hour:

calculationInterval: "hourly"

Daily

Check once per day:

calculationInterval: "daily"

Weekly

Check once per week:

calculationInterval: "weekly"

Monthly

Check once per month:

calculationInterval: "monthly"

Best Practices

1. Use Descriptive Names

// ✅ Good
const alert = new posthog.Alert("critical-error-spike", {
    name: "Critical: Error Rate Spike (>100/hour)",
});

// ❌ Avoid
const alert = new posthog.Alert("alert1", {
    name: "Alert 1",
});

2. Set Appropriate Thresholds

// Start with conservative thresholds
const alert = new posthog.Alert("signup-alert", {
    name: "Low Signup Rate",
    insight: 12345,
    thresholdType: "absolute",
    thresholdLower: 50, // Alert if below normal baseline
    subscribedUsers: [67890],
});

3. Notify the Right People

// Production alerts - notify on-call team
const prodAlert = new posthog.Alert("prod-critical", {
    name: "Production Critical Alert",
    insight: 12345,
    thresholdType: "absolute",
    thresholdUpper: 1000,
    subscribedUsers: [111, 222, 333], // On-call team
});

// Business alerts - notify stakeholders
const bizAlert = new posthog.Alert("revenue-drop", {
    name: "Revenue Drop Alert",
    insight: 23456,
    thresholdType: "percentage",
    thresholdLower: -10,
    subscribedUsers: [444, 555], // Business team
});

Common Use Cases

Error Rate Monitoring

const errorMonitor = new posthog.Alert("error-monitor", {
    name: "High Error Rate Detection",
    insight: 12345,
    enabled: true,
    thresholdType: "absolute",
    thresholdUpper: 50, // Alert when errors exceed 50
    calculationInterval: "hourly",
    subscribedUsers: [67890],
});

Conversion Drop Detection

const conversionAlert = new posthog.Alert("conversion-drop", {
    name: "Conversion Rate Drop",
    insight: 23456,
    enabled: true,
    thresholdType: "percentage",
    thresholdLower: -15, // Alert on 15% drop
    calculationInterval: "daily",
    subscribedUsers: [67890, 67891],
});

Traffic Spike Alert

const trafficSpike = new posthog.Alert("traffic-spike", {
    name: "Unusual Traffic Spike",
    insight: 34567,
    enabled: true,
    thresholdType: "percentage",
    thresholdUpper: 100, // Alert on 100% increase
    calculationInterval: "hourly",
    subscribedUsers: [67890],
});

Troubleshooting

Alert Not Firing

Issue: Alert doesn't trigger when threshold is exceeded

Solution:

Verify the alert is enabled
Check calculation interval matches expectation
Confirm insight ID is correct
Ensure threshold values are set appropriately

Wrong Users Notified

Issue: Incorrect users receiving alerts