0
# Service Health Events
1

2
Monitor and retrieve service health events affecting your Google Cloud projects. Service health events provide visibility into incidents, outages, and service disruptions with detailed impact information and real-time updates.
3

4
## Capabilities
5

6
### List Events
7

8
Retrieve a list of service health events for a specific project and location, with support for filtering, pagination, and different view levels.
9

10
```python { .api }
11
def list_events(
12
    request: Union[ListEventsRequest, dict] = None,
13
    *,
14
    parent: str = None,
15
    retry: Retry = gapic_v1.method.DEFAULT,
16
    timeout: Union[float, object] = gapic_v1.method.DEFAULT,
17
    metadata: Sequence[Tuple[str, Union[str, bytes]]] = ()
18
) -> ListEventsPager:
19
    """
20
    Lists service health events for the specified project and location.
21

22
    Parameters:
23
    - request: The request object containing all parameters
24
    - parent: Required. Format: projects/{project_id}/locations/{location}
25
    - retry: Retry policy for the request
26
    - timeout: Request timeout in seconds
27
    - metadata: Additional metadata for the request
28

29
    Returns:
30
    ListEventsPager: Iterator over Event objects with automatic pagination
31
    """
32
```
33

34
**Usage Example:**
35

36
```python
37
from google.cloud.servicehealth import ServiceHealthClient, EventView
38

39
client = ServiceHealthClient()
40

41
# List all events for a project
42
parent = "projects/my-project/locations/global"
43
events = client.list_events(parent=parent)
44

45
for event in events:
46
    print(f"Event: {event.title} - State: {event.state}")
47

48
# List events with filtering and full view
49
events_full = client.list_events(
50
    parent=parent,
51
    filter='state="ACTIVE"',
52
    view=EventView.EVENT_VIEW_FULL
53
)
54

55
for event in events_full:
56
    print(f"Event: {event.title}")
57
    print(f"Description: {event.description}")
58
    for update in event.updates:
59
        print(f"  Update: {update.title}")
60
```
61

62
### Get Event
63

64
Retrieve detailed information about a specific service health event.
65

66
```python { .api }
67
def get_event(
68
    request: Union[GetEventRequest, dict] = None,
69
    *,
70
    name: str = None,
71
    retry: Retry = gapic_v1.method.DEFAULT,
72
    timeout: Union[float, object] = gapic_v1.method.DEFAULT,
73
    metadata: Sequence[Tuple[str, Union[str, bytes]]] = ()
74
) -> Event:
75
    """
76
    Gets details of a specific service health event.
77

78
    Parameters:
79
    - request: The request object containing all parameters
80
    - name: Required. Format: projects/{project_id}/locations/{location}/events/{event_id}
81
    - retry: Retry policy for the request
82
    - timeout: Request timeout in seconds
83
    - metadata: Additional metadata for the request
84

85
    Returns:
86
    Event: The service health event details
87
    """
88
```
89

90
**Usage Example:**
91

92
```python
93
# Get a specific event
94
event_name = "projects/my-project/locations/global/events/event-123"
95
event = client.get_event(name=event_name)
96

97
print(f"Event Title: {event.title}")
98
print(f"Description: {event.description}")
99
print(f"State: {event.state}")
100
print(f"Category: {event.category}")
101

102
# Check event impacts
103
for impact in event.event_impacts:
104
    print(f"Affected Product: {impact.product.product_name}")
105
    print(f"Affected Location: {impact.location.location_name}")
106

107
# Review event updates
108
for update in event.updates:
109
    print(f"Update ({update.update_time}): {update.title}")
110
    if update.workaround:
111
        print(f"Workaround: {update.workaround}")
112
```
113

114
## Request Types
115

116
```python { .api }
117
class ListEventsRequest:
118
    """Request message for listing service health events."""
119
    parent: str  # Required: projects/{project_id}/locations/{location}
120
    page_size: int  # Optional: 1-100, defaults to reasonable size
121
    page_token: str  # Optional: pagination token from previous response
122
    filter: str  # Optional: filter expression (e.g., 'state="ACTIVE"')
123
    view: EventView  # Optional: controls which fields are returned
124

125
class GetEventRequest:
126
    """Request message for getting a specific event."""
127
    name: str  # Required: projects/{project_id}/locations/{location}/events/{event_id}
128
```
129

130
## Response Types
131

132
```python { .api }
133
class ListEventsResponse:
134
    """Response message for listing events."""
135
    events: List[Event]  # List of service health events
136
    next_page_token: str  # Token for retrieving next page
137
    unreachable: List[str]  # Locations that could not be reached
138

139
class Event:
140
    """Represents a service health event."""
141
    name: str  # Output only: Resource name
142
    title: str  # Output only: Event title
143
    description: str  # Output only: Detailed description
144
    category: Event.EventCategory  # Output only: Event category
145
    detailed_category: Event.DetailedCategory  # Output only: Detailed category
146
    state: Event.State  # Output only: Current event state
147
    detailed_state: Event.DetailedState  # Output only: Detailed state
148
    event_impacts: List[EventImpact]  # List of product/location impacts
149
    relevance: Event.Relevance  # Output only: Relevance to requesting project
150
    updates: List[EventUpdate]  # Output only: Event updates (in FULL view)
151
    parent_event: str  # Output only: Parent event if this is a child
152
    update_time: datetime  # Output only: Last update time
153
    start_time: datetime  # Output only: Event start time
154
    end_time: datetime  # Output only: Event end time (if resolved)
155
    next_update_time: datetime  # Output only: Expected next update time
156
```
157

158
## Event Enumerations
159

160
```python { .api }
161
class Event.EventCategory(Enum):
162
    """Category of the service health event."""
163
    EVENT_CATEGORY_UNSPECIFIED = 0  # Unspecified category
164
    INCIDENT = 2  # Service outage or degradation
165

166
class Event.DetailedCategory(Enum):
167
    """Detailed category information."""
168
    DETAILED_CATEGORY_UNSPECIFIED = 0  # Unspecified detailed category
169
    CONFIRMED_INCIDENT = 1  # Confirmed impact to Google Cloud product
170
    EMERGING_INCIDENT = 2   # Under investigation for potential impact
171

172
class Event.State(Enum):
173
    """Current state of the event."""
174
    STATE_UNSPECIFIED = 0  # Unspecified state
175
    ACTIVE = 1  # Event is actively affecting Google Cloud product
176
    CLOSED = 2  # Event is no longer affecting or merged with another
177

178
class Event.DetailedState(Enum):
179
    """Detailed state information."""
180
    DETAILED_STATE_UNSPECIFIED = 0  # Unspecified detailed state
181
    EMERGING = 1         # Event is under investigation
182
    CONFIRMED = 2        # Event is confirmed and impacting service
183
    RESOLVED = 3         # Event no longer affects the Google Cloud product
184
    MERGED = 4           # Event merged into parent incident
185
    AUTO_CLOSED = 9      # Event automatically closed by the system
186
    FALSE_POSITIVE = 10  # Event was determined not to affect service
187

188
class Event.Relevance(Enum):
189
    """Relevance of the event to the requesting project."""
190
    RELEVANCE_UNSPECIFIED = 0  # Unspecified relevance
191
    UNKNOWN = 2          # Unknown relevance to project
192
    NOT_IMPACTED = 6     # Event does not impact the project
193
    PARTIALLY_RELATED = 7 # Event is associated but may not impact
194
    RELATED = 8          # Event has direct connection with project
195
    IMPACTED = 9         # Event has verified impact to the project
196
```
197

198
## Filtering
199

200
The `filter` parameter supports various filtering expressions:
201

202
**State filtering:**
203
```python
204
filter='state="ACTIVE"'  # Only active events
205
filter='state="CLOSED"'  # Only closed events
206
```
207

208
**Category filtering:**
209
```python
210
filter='category="INCIDENT"'  # Only incidents
211
```
212

213
**Time range filtering:**
214
```python
215
filter='start_time>="2023-01-01T00:00:00Z"'  # Events after date
216
filter='end_time<="2023-12-31T23:59:59Z"'    # Events before date
217
```
218

219
**Product filtering:**
220
```python
221
filter='event_impacts.product.product_name="Cloud SQL"'  # Specific product
222
```
223

224
**Location filtering:**
225
```python
226
filter='event_impacts.location.location_name="us-central1"'  # Specific location
227
```
228

229
## Pagination
230

231
Use the `ListEventsPager` to iterate through all results automatically:
232

233
```python
234
# Automatic pagination
235
for event in client.list_events(parent=parent):
236
    process_event(event)
237

238
# Manual pagination control
239
request = ListEventsRequest(parent=parent, page_size=50)
240
pager = client.list_events(request=request)
241

242
for page in pager.pages:
243
    for event in page.events:
244
        process_event(event)
245
    if len(page.events) < 50:  # Last page
246
        break
247
```