0
# Notifications and Alerts
1

2
Configuration for budget notifications and threshold-based alerts. Supports Pub/Sub integration and Cloud Monitoring channels with different capabilities between v1 and v1beta1 APIs.
3

4
## Capabilities
5

6
### Notification Rules (v1 API)
7

8
The v1 API uses NotificationsRule for configuring budget notifications with Pub/Sub topics and monitoring channels.
9

10
```python { .api }
11
class NotificationsRule:
12
    """
13
    NotificationsRule defines recipients for budget alerts.
14

15
    Attributes:
16
        pubsub_topic (str): Optional. Pub/Sub topic where budget related
17
            messages will be published. Must be in the format
18
            projects/{project_id}/topics/{topic_id}
19
        schema_version (str): Optional. Schema version of the notification.
20
            Only "1.0" is supported
21
        monitoring_notification_channels (List[str]): Optional. Targets
22
            to send notifications to when a threshold is exceeded. Must be
23
            in the format projects/{project_id}/notificationChannels/{channel_id}
24
        disable_default_iam_recipients (bool): Optional. When true, disables
25
            default notifications sent when budget thresholds are exceeded
26
        enable_project_level_recipients (bool): Optional. When true, enables
27
            notifications to be sent to users with IAM roles on the project
28
    """
29
    pubsub_topic: str
30
    schema_version: str
31
    monitoring_notification_channels: List[str]
32
    disable_default_iam_recipients: bool
33
    enable_project_level_recipients: bool
34
```
35

36
### Enhanced Notification Rules (v1beta1 API)
37

38
The v1beta1 API uses AllUpdatesRule which provides enhanced notification capabilities.
39

40
```python { .api }
41
class AllUpdatesRule:
42
    """
43
    AllUpdatesRule defines recipients for all budget notifications.
44

45
    Attributes:
46
        pubsub_topic (str): Optional. Pub/Sub topic where budget notifications
47
            will be published. Must be in the format
48
            projects/{project_id}/topics/{topic_id}
49
        schema_version (str): Optional. Schema version of the notification.
50
            Only "1.0" is supported
51
        monitoring_notification_channels (List[str]): Optional. Cloud Monitoring
52
            notification channels to send budget alerts. Must be in the format
53
            projects/{project_id}/notificationChannels/{channel_id}
54
        disable_default_iam_recipients (bool): Optional. When true, disables
55
            default notifications sent when budget thresholds are exceeded
56
        enable_project_level_recipients (bool): Optional. When true, enables
57
            notifications to be sent to users with IAM roles on the project
58
    """
59
    pubsub_topic: str
60
    schema_version: str  # Only "1.0" supported
61
    monitoring_notification_channels: List[str]
62
    disable_default_iam_recipients: bool
63
    enable_project_level_recipients: bool
64
```
65

66
### Threshold Configuration
67

68
Threshold rules define when alerts should be triggered based on spending patterns.
69

70
```python { .api }
71
class ThresholdRule:
72
    """
73
    ThresholdRule contains a definition of a threshold for a budget.
74

75
    Attributes:
76
        threshold_percent (float): Required. Send a notification when this
77
            threshold is exceeded. Must be between 0.0 and 1.0
78
        spend_basis (Basis): Optional. The type of basis used to calculate
79
            threshold (current or forecasted spend)
80
    """
81
    threshold_percent: float  # Non-negative number (0.5 = 50%)
82
    spend_basis: Basis
83

84
    class Basis(Enum):
85
        \"\"\"The type of basis used to determine if spend has passed the threshold.\"\"\"
86
        BASIS_UNSPECIFIED = 0
87
        CURRENT_SPEND = 1  # Use current spend as basis for comparison
88
        FORECASTED_SPEND = 2  # Use forecasted spend (only with calendar periods)
89
```
90

91
## Usage Examples
92

93
### Setting Up Pub/Sub Notifications (v1)
94

95
```python
96
from google.cloud.billing import budgets
97

98
# Create a budget with Pub/Sub notifications
99
budget = budgets.Budget(
100
    display_name="Production Budget with Notifications",
101
    amount=budgets.BudgetAmount(
102
        specified_amount={"currency_code": "USD", "units": 2000}
103
    ),
104
    budget_filter=budgets.Filter(
105
        projects=["projects/my-production-project"],
106
        calendar_period=budgets.CalendarPeriod.MONTH
107
    ),
108
    threshold_rules=[
109
        budgets.ThresholdRule(
110
            threshold_percent=0.8,  # Alert at 80%
111
            spend_basis=budgets.ThresholdRule.Basis.CURRENT_SPEND
112
        ),
113
        budgets.ThresholdRule(
114
            threshold_percent=1.0,  # Alert at 100%
115
            spend_basis=budgets.ThresholdRule.Basis.CURRENT_SPEND
116
        )
117
    ],
118
    notifications_rule=budgets.NotificationsRule(
119
        pubsub_topic="projects/my-project/topics/budget-alerts",
120
        schema_version="1.0",
121
        monitoring_notification_channels=[
122
            "projects/my-project/notificationChannels/channel-123",
123
            "projects/my-project/notificationChannels/channel-456"
124
        ],
125
        disable_default_iam_recipients=False,
126
        enable_project_level_recipients=True
127
    )
128
)
129
```
130

131
### Setting Up Enhanced Notifications (v1beta1)
132

133
```python
134
from google.cloud.billing import budgets_v1beta1
135

136
# Create a budget with enhanced v1beta1 notifications
137
budget = budgets_v1beta1.Budget(
138
    display_name="Enhanced Notification Budget",
139
    amount=budgets_v1beta1.BudgetAmount(
140
        specified_amount={"currency_code": "USD", "units": 5000}
141
    ),
142
    budget_filter=budgets_v1beta1.Filter(
143
        resource_ancestors=["organizations/123456789"],
144
        calendar_period=budgets_v1beta1.CalendarPeriod.QUARTER
145
    ),
146
    threshold_rules=[
147
        budgets_v1beta1.ThresholdRule(
148
            threshold_percent=0.5,  # Alert at 50%
149
            spend_basis=budgets_v1beta1.ThresholdRule.Basis.FORECASTED_SPEND
150
        ),
151
        budgets_v1beta1.ThresholdRule(
152
            threshold_percent=0.9,  # Alert at 90%
153
            spend_basis=budgets_v1beta1.ThresholdRule.Basis.CURRENT_SPEND
154
        )
155
    ],
156
    all_updates_rule=budgets_v1beta1.AllUpdatesRule(
157
        pubsub_topic="projects/my-project/topics/enhanced-budget-alerts",
158
        schema_version="1.0",
159
        monitoring_notification_channels=[
160
            "projects/my-project/notificationChannels/ops-team",
161
            "projects/my-project/notificationChannels/finance-team"
162
        ]
163
    )
164
)
165
```
166

167
### Forecast-Based Alerting
168

169
```python
170
from google.cloud.billing import budgets
171

172
# Create a budget with forecast-based threshold alerting
173
budget = budgets.Budget(
174
    display_name="Forecast Alert Budget",
175
    amount=budgets.BudgetAmount(
176
        specified_amount={"currency_code": "USD", "units": 10000}
177
    ),
178
    budget_filter=budgets.Filter(
179
        projects=["projects/ml-training-project"],
180
        services=["services/compute.googleapis.com"],
181
        calendar_period=budgets.CalendarPeriod.MONTH
182
    ),
183
    threshold_rules=[
184
        # Alert when forecasted spend hits 80%
185
        budgets.ThresholdRule(
186
            threshold_percent=0.8,
187
            spend_basis=budgets.ThresholdRule.Basis.FORECASTED_SPEND
188
        ),
189
        # Alert when current spend hits 100%
190
        budgets.ThresholdRule(
191
            threshold_percent=1.0,
192
            spend_basis=budgets.ThresholdRule.Basis.CURRENT_SPEND
193
        )
194
    ],
195
    notifications_rule=budgets.NotificationsRule(
196
        pubsub_topic="projects/my-project/topics/ml-budget-alerts",
197
        schema_version="1.0",
198
        disable_default_iam_recipients=False
199
    )
200
)
201
```
202

203
### Multiple Threshold Configuration
204

205
```python
206
from google.cloud.billing import budgets
207

208
# Create a budget with multiple threshold levels
209
budget = budgets.Budget(
210
    display_name="Multi-Threshold Budget",
211
    amount=budgets.BudgetAmount(
212
        specified_amount={"currency_code": "USD", "units": 3000}
213
    ),
214
    budget_filter=budgets.Filter(
215
        projects=["projects/web-app-project"],
216
        calendar_period=budgets.CalendarPeriod.MONTH
217
    ),
218
    threshold_rules=[
219
        # Early warning at 25%
220
        budgets.ThresholdRule(
221
            threshold_percent=0.25,
222
            spend_basis=budgets.ThresholdRule.Basis.CURRENT_SPEND
223
        ),
224
        # Mid-month check at 50%
225
        budgets.ThresholdRule(
226
            threshold_percent=0.5,
227
            spend_basis=budgets.ThresholdRule.Basis.CURRENT_SPEND
228
        ),
229
        # Alert at 75%
230
        budgets.ThresholdRule(
231
            threshold_percent=0.75,
232
            spend_basis=budgets.ThresholdRule.Basis.CURRENT_SPEND
233
        ),
234
        # Critical alert at 90%
235
        budgets.ThresholdRule(
236
            threshold_percent=0.9,
237
            spend_basis=budgets.ThresholdRule.Basis.CURRENT_SPEND
238
        ),
239
        # Overspend alert at 100%
240
        budgets.ThresholdRule(
241
            threshold_percent=1.0,
242
            spend_basis=budgets.ThresholdRule.Basis.CURRENT_SPEND
243
        )
244
    ],
245
    notifications_rule=budgets.NotificationsRule(
246
        pubsub_topic="projects/my-project/topics/web-app-budget",
247
        schema_version="1.0",
248
        monitoring_notification_channels=[
249
            "projects/my-project/notificationChannels/dev-team",
250
            "projects/my-project/notificationChannels/finance-alerts"
251
        ]
252
    )
253
)
254
```
255

256
### Monitoring Channel Integration
257

258
```python
259
from google.cloud.billing import budgets
260

261
# Budget with Cloud Monitoring integration
262
budget = budgets.Budget(
263
    display_name="Monitoring Integration Budget",
264
    amount=budgets.BudgetAmount(
265
        specified_amount={"currency_code": "USD", "units": 1500}
266
    ),
267
    budget_filter=budgets.Filter(
268
        projects=["projects/microservices-project"],
269
        calendar_period=budgets.CalendarPeriod.MONTH,
270
        services=[
271
            "services/compute.googleapis.com",
272
            "services/storage.googleapis.com",
273
            "services/bigquery.googleapis.com"
274
        ]
275
    ),
276
    threshold_rules=[
277
        budgets.ThresholdRule(
278
            threshold_percent=0.8,
279
            spend_basis=budgets.ThresholdRule.Basis.CURRENT_SPEND
280
        )
281
    ],
282
    notifications_rule=budgets.NotificationsRule(
283
        pubsub_topic="projects/my-project/topics/microservices-budget",
284
        schema_version="1.0",
285
        monitoring_notification_channels=[
286
            # Email notification channel
287
            "projects/my-project/notificationChannels/email-devops",
288
            # Slack notification channel  
289
            "projects/my-project/notificationChannels/slack-alerts",
290
            # PagerDuty notification channel
291
            "projects/my-project/notificationChannels/pagerduty-critical"
292
        ],
293
        disable_default_iam_recipients=True,  # Only use specified channels
294
        enable_project_level_recipients=False
295
    )
296
)
297
```
298

299
## Notification Message Format
300

301
When budget thresholds are exceeded, notifications are sent with a structured format containing budget and spending information.
302

303
### Pub/Sub Message Schema
304

305
Budget notifications published to Pub/Sub topics follow this structure:
306

307
```python
308
{
309
    "budgetDisplayName": "My Budget Name",
310
    "alertThresholdExceeded": 0.8,  # Threshold that was exceeded (0.0-1.0)
311
    "costAmount": 850.00,  # Current spend amount
312
    "costIntervalStart": "2024-01-01T00:00:00Z",
313
    "costIntervalEnd": "2024-01-15T23:59:59Z", 
314
    "budgetAmount": 1000.00,  # Total budget amount
315
    "budgetAmountType": "SPECIFIED_AMOUNT",  # or "LAST_PERIOD_AMOUNT"
316
    "currencyCode": "USD",
317
    "schemaVersion": "1.0"
318
}
319
```
320

321
### Message Attributes
322

323
Pub/Sub messages include these attributes:
324

325
- `billingAccountId`: The billing account ID
326
- `budgetId`: The budget ID that triggered the alert
327
- `schemaVersion`: Always "1.0"
328

329
## API Version Differences
330

331
### v1 API Features
332
- Uses `NotificationsRule` class
333
- Supports `disable_default_iam_recipients` flag
334
- Supports `enable_project_level_recipients` flag
335
- REST transport available
336

337
### v1beta1 API Features  
338
- Uses `AllUpdatesRule` class (enhanced notifications)
339
- Simplified notification configuration
340
- Enhanced Pub/Sub integration
341
- Only gRPC transports (no REST)
342
- More flexible notification channel management