0
# Google Cloud Service Health
1

2
Google Cloud Service Health API client library for monitoring service health events and organization impacts. This library enables developers to gain visibility into disruptive events impacting Google Cloud products through comprehensive service health monitoring capabilities.
3

4
## Package Information
5

6
- **Package Name**: google-cloud-servicehealth
7
- **Language**: Python
8
- **Installation**: `pip install google-cloud-servicehealth`
9

10
## Core Imports
11

12
```python
13
from google.cloud import servicehealth_v1
14
```
15

16
Common patterns for client usage:
17

18
```python
19
from google.cloud.servicehealth import ServiceHealthClient, ServiceHealthAsyncClient
20
```
21

22
Import specific types when needed:
23

24
```python
25
from google.cloud.servicehealth import Event, OrganizationEvent, EventView
26
```
27

28
## Basic Usage
29

30
```python
31
from google.cloud.servicehealth import ServiceHealthClient
32

33
# Initialize the client
34
client = ServiceHealthClient()
35

36
# List events for a project
37
project_id = "your-project-id"
38
location = "global"  # or specific location like "us-central1"
39
parent = f"projects/{project_id}/locations/{location}"
40

41
events = client.list_events(parent=parent)
42
for event in events:
43
    print(f"Event: {event.title}")
44
    print(f"State: {event.state}")
45
    print(f"Category: {event.category}")
46
    print("---")
47

48
# Get a specific event
49
event_name = f"projects/{project_id}/locations/global/events/{event_id}"
50
event = client.get_event(name=event_name)
51
print(f"Event details: {event.description}")
52
```
53

54
## Architecture
55

56
The Service Health API follows Google Cloud's standard client library architecture:
57

58
- **Client Classes**: ServiceHealthClient (sync) and ServiceHealthAsyncClient (async) provide the main API interface
59
- **Resource Types**: Event, OrganizationEvent, OrganizationImpact represent core service health data
60
- **Request/Response Types**: Structured message types for all API operations with proper validation
61
- **Transport Layer**: Support for both gRPC and REST protocols with automatic retry and error handling
62
- **Authentication**: Standard Google Cloud authentication patterns with service accounts and application default credentials
63

64
This design enables monitoring of Google Cloud service health at both project and organization levels, with comprehensive filtering and pagination support for handling large-scale service health data.
65

66
## Capabilities
67

68
### Service Health Events
69

70
Monitor and retrieve service health events affecting your Google Cloud projects. Provides access to incidents, outages, and service disruptions with detailed impact information and real-time updates.
71

72
```python { .api }
73
def list_events(
74
    request: Union[ListEventsRequest, dict] = None,
75
    *,
76
    parent: str = None,
77
    retry: Retry = gapic_v1.method.DEFAULT,
78
    timeout: Union[float, object] = gapic_v1.method.DEFAULT,
79
    metadata: Sequence[Tuple[str, Union[str, bytes]]] = ()
80
) -> ListEventsPager: ...
81

82
def get_event(
83
    request: Union[GetEventRequest, dict] = None,
84
    *,
85
    name: str = None,
86
    retry: Retry = gapic_v1.method.DEFAULT,
87
    timeout: Union[float, object] = gapic_v1.method.DEFAULT,
88
    metadata: Sequence[Tuple[str, Union[str, bytes]]] = ()
89
) -> Event: ...
90
```
91

92
[Service Health Events](./service-health-events.md)
93

94
### Organization Events
95

96
Access organization-level service health events that may affect multiple projects within your organization. Provides visibility into broader service health issues and their organizational impact.
97

98
```python { .api }
99
def list_organization_events(
100
    request: Union[ListOrganizationEventsRequest, dict] = None,
101
    *,
102
    parent: str = None,
103
    retry: Retry = gapic_v1.method.DEFAULT,
104
    timeout: Union[float, object] = gapic_v1.method.DEFAULT,
105
    metadata: Sequence[Tuple[str, Union[str, bytes]]] = ()
106
) -> ListOrganizationEventsPager: ...
107

108
def get_organization_event(
109
    request: Union[GetOrganizationEventRequest, dict] = None,
110
    *,
111
    name: str = None,
112
    retry: Retry = gapic_v1.method.DEFAULT,
113
    timeout: Union[float, object] = gapic_v1.method.DEFAULT,
114
    metadata: Sequence[Tuple[str, Union[str, bytes]]] = ()
115
) -> OrganizationEvent: ...
116
```
117

118
[Organization Events](./organization-events.md)
119

120
### Organization Impacts
121

122
Track specific impacts of service health events on organization assets. Provides detailed information about which resources and projects are affected by service health incidents.
123

124
```python { .api }
125
def list_organization_impacts(
126
    request: Union[ListOrganizationImpactsRequest, dict] = None,
127
    *,
128
    parent: str = None,
129
    retry: Retry = gapic_v1.method.DEFAULT,
130
    timeout: Union[float, object] = gapic_v1.method.DEFAULT,
131
    metadata: Sequence[Tuple[str, Union[str, bytes]]] = ()
132
) -> ListOrganizationImpactsPager: ...
133

134
def get_organization_impact(
135
    request: Union[GetOrganizationImpactRequest, dict] = None,
136
    *,
137
    name: str = None,
138
    retry: Retry = gapic_v1.method.DEFAULT,
139
    timeout: Union[float, object] = gapic_v1.method.DEFAULT,
140
    metadata: Sequence[Tuple[str, Union[str, bytes]]] = ()
141
) -> OrganizationImpact: ...
142
```
143

144
[Organization Impacts](./organization-impacts.md)
145

146
### Asynchronous Operations
147

148
All client operations are available in asynchronous versions for non-blocking execution in async/await environments.
149

150
```python { .api }
151
# Async client with same methods as sync client
152
class ServiceHealthAsyncClient:
153
    async def list_events(...) -> ListEventsAsyncPager: ...
154
    async def get_event(...) -> Event: ...
155
    # ... all other methods as async versions
156
```
157

158
[Async Operations](./async-operations.md)
159

160
## Core Types
161

162
```python { .api }
163
class Event:
164
    """Service health event affecting Google Cloud products."""
165
    name: str  # Resource name
166
    title: str  # Human-readable title
167
    description: str  # Detailed description
168
    category: Event.EventCategory  # Event category
169
    detailed_category: Event.DetailedCategory  # Detailed category
170
    state: Event.State  # Current state
171
    detailed_state: Event.DetailedState  # Detailed state
172
    event_impacts: List[EventImpact]  # List of impacts
173
    relevance: Event.Relevance  # Relevance to project
174
    updates: List[EventUpdate]  # Event updates
175
    parent_event: str  # Parent event (for merged events)
176
    update_time: datetime  # Last update time
177
    start_time: datetime  # Event start time
178
    end_time: datetime  # Event end time (if resolved)
179
    next_update_time: datetime  # Next expected update time
180

181
class OrganizationEvent:
182
    """Organization-level service health event."""
183
    name: str  # Resource name
184
    title: str  # Human-readable title
185
    description: str  # Detailed description
186
    category: OrganizationEvent.EventCategory  # Event category
187
    state: OrganizationEvent.State  # Current state
188
    event_impacts: List[EventImpact]  # List of impacts
189
    updates: List[EventUpdate]  # Event updates
190
    start_time: datetime  # Event start time
191
    end_time: datetime  # Event end time (if resolved)
192
    update_time: datetime  # Last update time
193

194
class OrganizationImpact:
195
    """Impact of an event on organization assets."""
196
    name: str  # Resource name
197
    events: List[str]  # Associated event names
198
    asset: Asset  # Impacted asset
199
    update_time: datetime  # Last update time
200

201
class EventImpact:
202
    """Impact information for a service health event."""
203
    product: Product  # Affected Google Cloud product
204
    location: Location  # Affected location
205

206
class EventUpdate:
207
    """Update information for a service health event."""
208
    update_time: datetime  # Update timestamp
209
    title: str  # Update title
210
    description: str  # Update description
211
    symptom: str  # Symptom description
212
    workaround: str  # Workaround information
213

214
class Product:
215
    """Google Cloud product information."""
216
    product_name: str  # Product display name
217
    id: str  # Product identifier
218

219
class Location:
220
    """Geographic location information."""
221
    location_name: str  # Location identifier
222

223
class Asset:
224
    """Google Cloud asset information."""
225
    asset_name: str  # Full resource name
226
    asset_type: str  # Resource type
227

228
# Enumerations
229
class EventView(Enum):
230
    EVENT_VIEW_UNSPECIFIED = 0  # Default to basic view
231
    EVENT_VIEW_BASIC = 1        # Basic fields without updates
232
    EVENT_VIEW_FULL = 2         # All fields including updates
233

234
class OrganizationEventView(Enum):
235
    ORGANIZATION_EVENT_VIEW_UNSPECIFIED = 0  # Default to basic view
236
    ORGANIZATION_EVENT_VIEW_BASIC = 1        # Basic fields without updates
237
    ORGANIZATION_EVENT_VIEW_FULL = 2         # All fields including updates
238

239
# Event nested enumerations
240
class Event.EventCategory(Enum):
241
    EVENT_CATEGORY_UNSPECIFIED = 0  # Unspecified category
242
    INCIDENT = 2                    # Service outage or degradation
243

244
class Event.DetailedCategory(Enum):
245
    DETAILED_CATEGORY_UNSPECIFIED = 0  # Unspecified detailed category
246
    CONFIRMED_INCIDENT = 1             # Confirmed impact to Google Cloud product
247
    EMERGING_INCIDENT = 2              # Under investigation for impact
248

249
class Event.State(Enum):
250
    STATE_UNSPECIFIED = 0  # Unspecified state
251
    ACTIVE = 1             # Actively affecting Google Cloud product
252
    CLOSED = 2             # No longer affecting or merged with another event
253

254
class Event.DetailedState(Enum):
255
    DETAILED_STATE_UNSPECIFIED = 0  # Unspecified detail state
256
    EMERGING = 1                    # Under active investigation
257
    CONFIRMED = 2                   # Confirmed and impacting at least one product
258
    RESOLVED = 3                    # No longer affecting any product
259
    MERGED = 4                     # Merged into parent event (see parent_event field)
260
    AUTO_CLOSED = 9                # Automatically closed (impact unconfirmed/intermittent)
261
    FALSE_POSITIVE = 10            # Not affecting a Google Cloud product
262

263
class Event.Relevance(Enum):
264
    RELEVANCE_UNSPECIFIED = 0  # Unspecified relevance
265
    UNKNOWN = 2               # Relevance to project unknown
266
    NOT_IMPACTED = 6          # Does not impact the project
267
    PARTIALLY_RELATED = 7     # Associated with product you use, may not impact you
268
    RELATED = 8               # Direct connection with your project
269
    IMPACTED = 9              # Verified to be impacting your project
270

271
# Request/Response Message Types
272
class ListEventsRequest:
273
    """Request message for listing service health events."""
274
    parent: str           # Required. Format: projects/{project_id}/locations/{location}
275
    page_size: int        # Optional. Maximum number of events to return
276
    page_token: str       # Optional. Page token for pagination
277
    filter: str           # Optional. Filter expression
278
    view: EventView       # Optional. Level of detail to return
279

280
class ListEventsResponse:
281
    """Response message for listing service health events."""
282
    events: List[Event]       # List of events
283
    next_page_token: str      # Token for next page of results
284
    unreachable: List[str]    # Unreachable locations
285

286
class GetEventRequest:
287
    """Request message for getting a specific service health event."""
288
    name: str  # Required. Format: projects/{project_id}/locations/{location}/events/{event_id}
289

290
class ListOrganizationEventsRequest:
291
    """Request message for listing organization events."""
292
    parent: str                      # Required. Format: organizations/{organization_id}/locations/{location}
293
    page_size: int                   # Optional. Maximum number of events to return
294
    page_token: str                  # Optional. Page token for pagination
295
    filter: str                      # Optional. Filter expression
296
    view: OrganizationEventView      # Optional. Level of detail to return
297

298
class ListOrganizationEventsResponse:
299
    """Response message for listing organization events."""
300
    organization_events: List[OrganizationEvent]  # List of organization events
301
    next_page_token: str                          # Token for next page of results
302
    unreachable: List[str]                        # Unreachable locations
303

304
class GetOrganizationEventRequest:
305
    """Request message for getting a specific organization event."""
306
    name: str  # Required. Format: organizations/{organization_id}/locations/{location}/organizationEvents/{event_id}
307

308
class ListOrganizationImpactsRequest:
309
    """Request message for listing organization impacts."""
310
    parent: str       # Required. Format: organizations/{organization_id}/locations/{location}
311
    page_size: int    # Optional. Maximum number of impacts to return
312
    page_token: str   # Optional. Page token for pagination
313
    filter: str       # Optional. Filter expression
314

315
class ListOrganizationImpactsResponse:
316
    """Response message for listing organization impacts."""
317
    organization_impacts: List[OrganizationImpact]  # List of organization impacts
318
    next_page_token: str                            # Token for next page of results
319
    unreachable: List[str]                          # Unreachable locations
320

321
class GetOrganizationImpactRequest:
322
    """Request message for getting a specific organization impact."""
323
    name: str  # Required. Format: organizations/{organization_id}/locations/{location}/organizationImpacts/{organization_impact_id}
324

325
# Pager Classes
326
class ListEventsPager:
327
    """Synchronous iterator for paginating through Event objects."""
328
    def __iter__(self) -> Iterator[Event]: ...
329
    def __next__(self) -> Event: ...
330

331
class ListEventsAsyncPager:
332
    """Asynchronous iterator for paginating through Event objects."""
333
    def __aiter__(self) -> AsyncIterator[Event]: ...
334
    async def __anext__(self) -> Event: ...
335

336
class ListOrganizationEventsPager:
337
    """Synchronous iterator for paginating through OrganizationEvent objects."""
338
    def __iter__(self) -> Iterator[OrganizationEvent]: ...
339
    def __next__(self) -> OrganizationEvent: ...
340

341
class ListOrganizationEventsAsyncPager:
342
    """Asynchronous iterator for paginating through OrganizationEvent objects."""
343
    def __aiter__(self) -> AsyncIterator[OrganizationEvent]: ...
344
    async def __anext__(self) -> OrganizationEvent: ...
345

346
class ListOrganizationImpactsPager:
347
    """Synchronous iterator for paginating through OrganizationImpact objects."""
348
    def __iter__(self) -> Iterator[OrganizationImpact]: ...
349
    def __next__(self) -> OrganizationImpact: ...
350

351
class ListOrganizationImpactsAsyncPager:
352
    """Asynchronous iterator for paginating through OrganizationImpact objects."""
353
    def __aiter__(self) -> AsyncIterator[OrganizationImpact]: ...
354
    async def __anext__(self) -> OrganizationImpact: ...
355
```