| 1 |
// Package pagerduty provides a notification service for PagerDuty incident management. |
| 2 |
// |
| 3 |
// The PagerDuty service enables sending alerts, acknowledgments, and resolutions to PagerDuty |
| 4 |
// using the Events API v2. It supports creating incidents, acknowledging existing incidents, |
| 5 |
// and resolving incidents with configurable severity levels and custom parameters. |
| 6 |
// |
| 7 |
// # URL Format |
| 8 |
// |
| 9 |
// The service URL follows the format: |
| 10 |
// |
| 11 |
// pagerduty://[host[:port]]/integration-key[?query] |
| 12 |
// |
| 13 |
// Where: |
| 14 |
// - host: optional PagerDuty API host (default: events.pagerduty.com) |
| 15 |
// - port: optional port number (default: 443) |
| 16 |
// - integration-key: the PagerDuty Events API v2 integration key |
| 17 |
// - query: configuration parameters |
| 18 |
// |
| 19 |
// # Configuration Options |
| 20 |
// |
| 21 |
// The following query parameters can be used to configure the service: |
| 22 |
// |
| 23 |
// - severity: alert severity (critical, error, warning, info; default: error) |
| 24 |
// - source: unique location of affected system (default: default) |
| 25 |
// - action: event type (trigger, acknowledge, resolve; default: trigger) |
| 26 |
// |
| 27 |
// # Event Actions |
| 28 |
// |
| 29 |
// ## Trigger (Default) |
| 30 |
// |
| 31 |
// Creates a new incident in PagerDuty: |
| 32 |
// |
| 33 |
// url := "pagerduty:///eb243592-faa2-4ba2-a551q-1afdf565c889" |
| 34 |
// err := shoutrrr.Send(url, "Server is down") |
| 35 |
// |
| 36 |
// ## Acknowledge |
| 37 |
// |
| 38 |
// Acknowledges an existing incident: |
| 39 |
// |
| 40 |
// url := "pagerduty:///eb243592-faa2-4ba2-a551q-1afdf565c889?action=acknowledge" |
| 41 |
// err := shoutrrr.Send(url, "Investigating server issue") |
| 42 |
// |
| 43 |
// ## Resolve |
| 44 |
// |
| 45 |
// Resolves an existing incident: |
| 46 |
// |
| 47 |
// url := "pagerduty:///eb243592-faa2-4ba2-a551q-1afdf565c889?action=resolve" |
| 48 |
// err := shoutrrr.Send(url, "Server issue resolved") |
| 49 |
// |
| 50 |
// # Examples |
| 51 |
// |
| 52 |
// ## Basic incident creation |
| 53 |
// |
| 54 |
// url := "pagerduty:///eb243592-faa2-4ba2-a551q-1afdf565c889" |
| 55 |
// err := shoutrrr.Send(url, "Database connection failed") |
| 56 |
// |
| 57 |
// ## Critical severity alert |
| 58 |
// |
| 59 |
// url := "pagerduty:///eb243592-faa2-4ba2-a551q-1afdf565c889?severity=critical" |
| 60 |
// err := shoutrrr.Send(url, "Production system unavailable") |
| 61 |
// |
| 62 |
// ## Custom source identifier |
| 63 |
// |
| 64 |
// url := "pagerduty:///eb243592-faa2-4ba2-a551q-1afdf565c889?source=web-server-01" |
| 65 |
// err := shoutrrr.Send(url, "High CPU usage detected") |
| 66 |
// |
| 67 |
// ## Using parameters in code |
| 68 |
// |
| 69 |
// service.Send("Alert message", &types.Params{ |
| 70 |
// "severity": "critical", |
| 71 |
// "source": "monitoring-system", |
| 72 |
// "action": "trigger", |
| 73 |
// }) |
| 74 |
// |
| 75 |
// ## Command line usage |
| 76 |
// |
| 77 |
// shoutrrr send -u 'pagerduty:///eb243592-faa2-4ba2-a551q-1afdf565c889?severity=critical&source=app' -m 'Application crashed' |
| 78 |
// |
| 79 |
// # Common Use Cases |
| 80 |
// |
| 81 |
// ## Monitoring System Integration |
| 82 |
// |
| 83 |
// Send alerts from monitoring tools like Prometheus, Nagios, or Zabbix: |
| 84 |
// |
| 85 |
// url := "pagerduty:///eb243592-faa2-4ba2-a551q-1afdf565c889?source=prometheus" |
| 86 |
// err := shoutrrr.Send(url, "CPU usage above 90%", map[string]string{"severity": "warning"}) |
| 87 |
// |
| 88 |
// ## Application Error Notifications |
| 89 |
// |
| 90 |
// Notify PagerDuty of application errors or exceptions: |
| 91 |
// |
| 92 |
// url := "pagerduty:///eb243592-faa2-4ba2-a551q-1afdf565c889?severity=error&source=my-app" |
| 93 |
// err := shoutrrr.Send(url, fmt.Sprintf("Exception in %s: %v", functionName, err)) |
| 94 |
// |
| 95 |
// ## Infrastructure Alerts |
| 96 |
// |
| 97 |
// Alert on infrastructure issues like disk space, memory, or network problems: |
| 98 |
// |
| 99 |
// url := "pagerduty:///eb243592-faa2-4ba2-a551q-1afdf565c889?severity=critical&source=server-01" |
| 100 |
// err := shoutrrr.Send(url, "Disk space critically low: 95% used") |
| 101 |
// |
| 102 |
// ## Automated Incident Response |
| 103 |
// |
| 104 |
// Use acknowledge and resolve actions in automated workflows: |
| 105 |
// |
| 106 |
// // Acknowledge incident |
| 107 |
// ackURL := "pagerduty:///eb243592-faa2-4ba2-a551q-1afdf565c889?action=acknowledge" |
| 108 |
// shoutrrr.Send(ackURL, "Auto-acknowledging for investigation") |
| 109 |
// |
| 110 |
// // Resolve incident |
| 111 |
// resolveURL := "pagerduty:///eb243592-faa2-4ba2-a551q-1afdf565c889?action=resolve" |
| 112 |
// shoutrrr.Send(resolveURL, "Issue automatically resolved") |
| 113 |
// |
| 114 |
// # Error Handling |
| 115 |
// |
| 116 |
// The service returns errors for network failures, invalid integration keys, |
| 117 |
// and PagerDuty API errors. Always check the returned error: |
| 118 |
// |
| 119 |
// err := shoutrrr.Send(url, message) |
| 120 |
// if err != nil { |
| 121 |
// log.Printf("Failed to send PagerDuty alert: %v", err) |
| 122 |
// } |
| 123 |
// |
| 124 |
// Common error scenarios: |
| 125 |
// - Invalid integration key: HTTP 400 Bad Request |
| 126 |
// - Network connectivity issues: connection timeouts |
| 127 |
// - API rate limiting: HTTP 429 Too Many Requests |
| 128 |
// - Server errors: HTTP 5xx status codes |
| 129 |
// |
| 130 |
// # Security Considerations |
| 131 |
// |
| 132 |
// - Store integration keys securely, never in version control |
| 133 |
// - Use HTTPS for all PagerDuty API communications |
| 134 |
// - Validate integration keys before deployment |
| 135 |
// - Monitor API usage to avoid rate limiting |
| 136 |
// - Consider IP allowlisting for production environments |
| 137 |
// - Use appropriate severity levels to avoid alert fatigue |
| 138 |
// |
| 139 |
// # API Reference |
| 140 |
// |
| 141 |
// This service uses the PagerDuty Events API v2. For detailed API documentation, |
| 142 |
// see: https://developer.pagerduty.com/docs/events-api-v2-overview |
| 143 |
// |
| 144 |
// The payload structure includes: |
| 145 |
// - routing_key: integration key for event routing |
| 146 |
// - event_action: trigger, acknowledge, or resolve |
| 147 |
// - payload: contains summary, severity, and source information |
| 148 |
package pagerduty |