Debian Codegraph @

pkg/services/incident/pagerduty/doc.go

raw
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