0
# Uptime Check Management
1

2
Comprehensive uptime check management for monitoring the availability and response time of HTTP/HTTPS endpoints, TCP services, and other network resources in Google Cloud Monitoring. Uptime checks provide global monitoring from multiple geographic locations.
3

4
## Capabilities
5

6
### Uptime Check Configuration
7

8
Manage the complete lifecycle of uptime check configurations including creation, updates, retrieval, and deletion.
9

10
```python { .api }
11
class UptimeCheckServiceClient:
12
    def list_uptime_check_configs(
13
        self,
14
        request=None,
15
        *,
16
        parent: str = None,
17
        retry=None,
18
        timeout=None,
19
        metadata=()
20
    ) -> pagers.ListUptimeCheckConfigsPager:
21
        """
22
        Lists the existing valid Uptime check configurations.
23

24
        Args:
25
            request: The request object or dict equivalent
26
            parent: Required. Project name in format 'projects/[PROJECT_ID]'
27
            retry: Retry configuration
28
            timeout: Request timeout in seconds
29
            metadata: Additional metadata
30

31
        Returns:
32
            Pager for iterating over UptimeCheckConfig objects
33
        """
34

35
    def get_uptime_check_config(
36
        self,
37
        request=None,
38
        *,
39
        name: str = None,
40
        retry=None,
41
        timeout=None,
42
        metadata=()
43
    ) -> uptime.UptimeCheckConfig:
44
        """
45
        Gets a single Uptime check configuration.
46

47
        Args:
48
            request: The request object or dict equivalent
49
            name: Required. Uptime check config name
50
            retry: Retry configuration
51
            timeout: Request timeout in seconds
52
            metadata: Additional metadata
53

54
        Returns:
55
            UptimeCheckConfig object
56
        """
57

58
    def create_uptime_check_config(
59
        self,
60
        request=None,
61
        *,
62
        parent: str = None,
63
        uptime_check_config=None,
64
        retry=None,
65
        timeout=None,
66
        metadata=()
67
    ) -> uptime.UptimeCheckConfig:
68
        """
69
        Creates a new Uptime check configuration.
70

71
        Args:
72
            request: The request object or dict equivalent
73
            parent: Required. Project name
74
            uptime_check_config: Required. The uptime check config to create
75
            retry: Retry configuration
76
            timeout: Request timeout in seconds
77
            metadata: Additional metadata
78

79
        Returns:
80
            Created UptimeCheckConfig object
81
        """
82

83
    def update_uptime_check_config(
84
        self,
85
        request=None,
86
        *,
87
        uptime_check_config=None,
88
        retry=None,
89
        timeout=None,
90
        metadata=()
91
    ) -> uptime.UptimeCheckConfig:
92
        """
93
        Updates an Uptime check configuration.
94

95
        Args:
96
            request: The request object or dict equivalent
97
            uptime_check_config: Required. Updated uptime check config
98
            retry: Retry configuration
99
            timeout: Request timeout in seconds
100
            metadata: Additional metadata
101

102
        Returns:
103
            Updated UptimeCheckConfig object
104
        """
105

106
    def delete_uptime_check_config(
107
        self,
108
        request=None,
109
        *,
110
        name: str = None,
111
        retry=None,
112
        timeout=None,
113
        metadata=()
114
    ) -> None:
115
        """
116
        Deletes an Uptime check configuration.
117

118
        Args:
119
            request: The request object or dict equivalent
120
            name: Required. Uptime check config name to delete
121
            retry: Retry configuration
122
            timeout: Request timeout in seconds
123
            metadata: Additional metadata
124
        """
125

126
    def list_uptime_check_ips(
127
        self,
128
        request=None,
129
        *,
130
        retry=None,
131
        timeout=None,
132
        metadata=()
133
    ) -> pagers.ListUptimeCheckIpsPager:
134
        """
135
        Returns the list of IP addresses that checkers run from.
136

137
        Args:
138
            request: The request object or dict equivalent
139
            retry: Retry configuration
140
            timeout: Request timeout in seconds
141
            metadata: Additional metadata
142

143
        Returns:
144
            Pager for iterating over UptimeCheckIp objects
145
        """
146
```
147

148
## Data Types
149

150
### UptimeCheckConfig
151

152
Represents an uptime check configuration.
153

154
```python { .api }
155
class UptimeCheckConfig:
156
    name: str  # Resource name
157
    display_name: str  # Human-readable name
158
    monitored_resource: MonitoredResource  # Resource to monitor
159
    resource_group: UptimeCheckConfig.ResourceGroup  # Resource group to monitor
160
    http_check: UptimeCheckConfig.HttpCheck  # HTTP check configuration
161
    tcp_check: UptimeCheckConfig.TcpCheck  # TCP check configuration
162
    period: Duration  # Check frequency
163
    timeout: Duration  # Check timeout
164
    content_matchers: List[UptimeCheckConfig.ContentMatcher]  # Response content validation
165
    checker_type: UptimeCheckConfig.CheckerType  # Type of checker
166
    selected_regions: List[UptimeCheckRegion]  # Regions to run checks from
167
    is_internal: bool  # Whether check is internal
168
    internal_checkers: List[InternalChecker]  # Internal checker configurations
169
    user_labels: Dict[str, str]  # User-defined labels
170

171
class UptimeCheckConfig.HttpCheck:
172
    request_method: UptimeCheckConfig.HttpCheck.RequestMethod  # HTTP method
173
    use_ssl: bool  # Whether to use HTTPS
174
    path: str  # URL path to check
175
    port: int  # Port number
176
    auth_info: UptimeCheckConfig.HttpCheck.BasicAuthentication  # Authentication
177
    mask_headers: bool  # Whether to mask headers in logs
178
    headers: Dict[str, str]  # HTTP headers
179
    content_type: UptimeCheckConfig.HttpCheck.ContentType  # Request content type
180
    validate_ssl: bool  # Whether to validate SSL certificates
181
    body: bytes  # Request body
182
    accepted_response_status_codes: List[UptimeCheckConfig.HttpCheck.ResponseStatusCode]  # Accepted status codes
183
    ping_config: UptimeCheckConfig.PingConfig  # Ping configuration
184

185
class UptimeCheckConfig.TcpCheck:
186
    port: int  # Port number
187
    ping_config: UptimeCheckConfig.PingConfig  # Ping configuration
188

189
class UptimeCheckConfig.ContentMatcher:
190
    content: str  # Content to match
191
    matcher: UptimeCheckConfig.ContentMatcher.ContentMatcherOption  # Matching option
192
    json_path_matcher: UptimeCheckConfig.ContentMatcher.JsonPathMatcher  # JSON path matcher
193

194
class UptimeCheckConfig.ResourceGroup:
195
    group_id: str  # Group ID
196
    resource_type: GroupResourceType  # Resource type
197

198
class UptimeCheckConfig.CheckerType(enum.Enum):
199
    CHECKER_TYPE_UNSPECIFIED = 0
200
    STATIC_IP_CHECKERS = 1
201
    VPC_CHECKERS = 2
202
```
203

204
### UptimeCheckIp
205

206
Represents an IP address used by uptime checkers.
207

208
```python { .api }
209
class UptimeCheckIp:
210
    region: UptimeCheckRegion  # Region of the checker
211
    location: str  # Location description
212
    ip_address: str  # IP address
213
```
214

215
### InternalChecker
216

217
Represents an internal uptime checker configuration.
218

219
```python { .api }
220
class InternalChecker:
221
    name: str  # Checker name
222
    display_name: str  # Human-readable name
223
    network: str  # Network to check from
224
    gcp_zone: str  # GCP zone
225
    peer_project_id: str  # Peer project ID
226
    state: InternalChecker.State  # Checker state
227

228
class InternalChecker.State(enum.Enum):
229
    UNSPECIFIED = 0
230
    CREATING = 1
231
    RUNNING = 2
232
```
233

234
### Request and Response Types
235

236
```python { .api }
237
class CreateUptimeCheckConfigRequest:
238
    parent: str  # Required. Project name
239
    uptime_check_config: UptimeCheckConfig  # Required. Config to create
240

241
class DeleteUptimeCheckConfigRequest:
242
    name: str  # Required. Config name to delete
243

244
class GetUptimeCheckConfigRequest:
245
    name: str  # Required. Config name to retrieve
246

247
class ListUptimeCheckConfigsRequest:
248
    parent: str  # Required. Project name
249
    filter: str  # Filter expression
250
    page_size: int  # Maximum results per page
251
    page_token: str  # Page token
252

253
class ListUptimeCheckConfigsResponse:
254
    uptime_check_configs: List[UptimeCheckConfig]  # Uptime check configs
255
    next_page_token: str  # Next page token
256
    total_size: int  # Total number of configs
257

258
class ListUptimeCheckIpsRequest:
259
    page_size: int  # Maximum results per page
260
    page_token: str  # Page token
261

262
class ListUptimeCheckIpsResponse:
263
    uptime_check_ips: List[UptimeCheckIp]  # IP addresses
264
    next_page_token: str  # Next page token
265

266
class UpdateUptimeCheckConfigRequest:
267
    uptime_check_config: UptimeCheckConfig  # Required. Updated config
268
    update_mask: FieldMask  # Fields to update
269
```
270

271
## Usage Examples
272

273
### Creating an HTTP Uptime Check
274

275
```python
276
from google.cloud.monitoring import UptimeCheckServiceClient
277
from google.cloud.monitoring_v3.types import UptimeCheckConfig, UptimeCheckRegion
278
from google.protobuf.duration_pb2 import Duration
279

280
client = UptimeCheckServiceClient()
281
project_name = f"projects/{project_id}"
282

283
# Create HTTP uptime check
284
config = UptimeCheckConfig()
285
config.display_name = "Website Health Check"
286

287
# Configure HTTP check
288
http_check = UptimeCheckConfig.HttpCheck()
289
http_check.use_ssl = True
290
http_check.path = "/health"
291
http_check.port = 443
292
http_check.request_method = UptimeCheckConfig.HttpCheck.RequestMethod.GET
293

294
# Add custom headers
295
http_check.headers["User-Agent"] = "Google-Cloud-Monitoring-Uptime-Check"
296
http_check.headers["Accept"] = "application/json"
297

298
config.http_check = http_check
299

300
# Set monitored resource
301
config.monitored_resource.type = "uptime_url"
302
config.monitored_resource.labels["project_id"] = project_id
303
config.monitored_resource.labels["host"] = "example.com"
304

305
# Configure check frequency (5 minutes)
306
period = Duration()
307
period.seconds = 300
308
config.period = period
309

310
# Configure timeout (10 seconds)
311
timeout = Duration()
312
timeout.seconds = 10
313
config.timeout = timeout
314

315
# Select regions for checking
316
config.selected_regions = [
317
    UptimeCheckRegion.USA,
318
    UptimeCheckRegion.EUROPE,
319
    UptimeCheckRegion.ASIA_PACIFIC
320
]
321

322
# Add content matcher
323
content_matcher = UptimeCheckConfig.ContentMatcher()
324
content_matcher.content = "status"
325
content_matcher.matcher = UptimeCheckConfig.ContentMatcher.ContentMatcherOption.CONTAINS_STRING
326
config.content_matchers = [content_matcher]
327

328
# Add user labels
329
config.user_labels["environment"] = "production"
330
config.user_labels["team"] = "ops"
331

332
created_config = client.create_uptime_check_config(
333
    parent=project_name,
334
    uptime_check_config=config
335
)
336
print(f"Created uptime check: {created_config.name}")
337
print(f"Display name: {created_config.display_name}")
338
```
339

340
### Creating a TCP Uptime Check
341

342
```python
343
# Create TCP uptime check
344
tcp_config = UptimeCheckConfig()
345
tcp_config.display_name = "Database Connection Check"
346

347
# Configure TCP check
348
tcp_check = UptimeCheckConfig.TcpCheck()
349
tcp_check.port = 5432  # PostgreSQL port
350

351
config.tcp_check = tcp_check
352

353
# Set monitored resource for TCP check
354
tcp_config.monitored_resource.type = "gce_instance"
355
tcp_config.monitored_resource.labels["project_id"] = project_id
356
tcp_config.monitored_resource.labels["instance_id"] = "database-server-1"
357
tcp_config.monitored_resource.labels["zone"] = "us-central1-a"
358

359
# Configure check frequency (1 minute)
360
period = Duration()
361
period.seconds = 60
362
tcp_config.period = period
363

364
# Configure timeout (5 seconds)
365
timeout = Duration()
366
timeout.seconds = 5
367
tcp_config.timeout = timeout
368

369
created_tcp_config = client.create_uptime_check_config(
370
    parent=project_name,
371
    uptime_check_config=tcp_config
372
)
373
print(f"Created TCP uptime check: {created_tcp_config.name}")
374
```
375

376
### Creating an HTTP Check with Authentication
377

378
```python
379
# Create HTTP check with basic authentication
380
auth_config = UptimeCheckConfig()
381
auth_config.display_name = "Authenticated API Check"
382

383
# Configure HTTP check with authentication
384
auth_http_check = UptimeCheckConfig.HttpCheck()
385
auth_http_check.use_ssl = True
386
auth_http_check.path = "/api/v1/status"
387
auth_http_check.port = 443
388
auth_http_check.request_method = UptimeCheckConfig.HttpCheck.RequestMethod.GET
389

390
# Configure basic authentication
391
auth_info = UptimeCheckConfig.HttpCheck.BasicAuthentication()
392
auth_info.username = "monitor"
393
auth_info.password = "secret_password"
394
auth_http_check.auth_info = auth_info
395

396
auth_config.http_check = auth_http_check
397

398
# Set resource
399
auth_config.monitored_resource.type = "uptime_url" 
400
auth_config.monitored_resource.labels["project_id"] = project_id
401
auth_config.monitored_resource.labels["host"] = "api.example.com"
402

403
created_auth_config = client.create_uptime_check_config(
404
    parent=project_name,
405
    uptime_check_config=auth_config
406
)
407
print(f"Created authenticated uptime check: {created_auth_config.name}")
408
```
409

410
### Creating an Internal Uptime Check
411

412
```python
413
# Create internal uptime check (from VPC)
414
internal_config = UptimeCheckConfig()
415
internal_config.display_name = "Internal Service Check"
416
internal_config.is_internal = True
417
internal_config.checker_type = UptimeCheckConfig.CheckerType.VPC_CHECKERS
418

419
# Configure HTTP check for internal resource
420
internal_http = UptimeCheckConfig.HttpCheck()
421
internal_http.path = "/internal/health"
422
internal_http.port = 8080
423
internal_config.http_check = internal_http
424

425
# Set internal monitored resource
426
internal_config.monitored_resource.type = "gce_instance"
427
internal_config.monitored_resource.labels["project_id"] = project_id
428
internal_config.monitored_resource.labels["instance_id"] = "internal-service-1"
429
internal_config.monitored_resource.labels["zone"] = "us-central1-a"
430

431
# Configure internal checker
432
internal_checker = InternalChecker()
433
internal_checker.display_name = "VPC Checker"
434
internal_checker.network = f"projects/{project_id}/global/networks/default"
435
internal_checker.gcp_zone = "us-central1-a"
436
internal_config.internal_checkers = [internal_checker]
437

438
created_internal = client.create_uptime_check_config(
439
    parent=project_name,
440
    uptime_check_config=internal_config
441
)
442
print(f"Created internal uptime check: {created_internal.name}")
443
```
444

445
### Listing Uptime Check Configurations
446

447
```python
448
# List all uptime check configurations
449
print("Uptime check configurations:")
450
for config in client.list_uptime_check_configs(parent=project_name):
451
    print(f"- {config.display_name}: {config.name}")
452
    if config.http_check:
453
        print(f"  HTTP check: {config.monitored_resource.labels.get('host', 'N/A')}")
454
        print(f"  Path: {config.http_check.path}")
455
        print(f"  SSL: {config.http_check.use_ssl}")
456
    elif config.tcp_check:
457
        print(f"  TCP check on port: {config.tcp_check.port}")
458
    
459
    print(f"  Period: {config.period.seconds}s")
460
    print(f"  Regions: {len(config.selected_regions)}")
461

462
# Filter by labels
463
filter_expr = 'user_labels.environment="production"'
464
print(f"\nProduction uptime checks:")
465
for config in client.list_uptime_check_configs(parent=project_name, filter=filter_expr):
466
    print(f"- {config.display_name}")
467
```
468

469
### Updating an Uptime Check Configuration
470

471
```python
472
from google.protobuf import field_mask_pb2
473

474
# Get existing configuration
475
config_name = f"projects/{project_id}/uptimeCheckConfigs/{config_id}"
476
config = client.get_uptime_check_config(name=config_name)
477

478
# Update configuration
479
config.display_name = "Updated Website Health Check"
480
config.http_check.path = "/api/health"
481

482
# Update timeout
483
config.timeout.seconds = 15
484

485
# Update user labels
486
config.user_labels["version"] = "v2.0"
487

488
# Create field mask for selective update
489
update_mask = field_mask_pb2.FieldMask()
490
update_mask.paths.extend([
491
    "display_name", 
492
    "http_check.path", 
493
    "timeout", 
494
    "user_labels"
495
])
496

497
updated_config = client.update_uptime_check_config(
498
    uptime_check_config=config,
499
    update_mask=update_mask
500
)
501
print(f"Updated uptime check: {updated_config.display_name}")
502
```
503

504
### Working with JSON Path Content Matchers
505

506
```python
507
# Create uptime check with JSON path matcher
508
json_config = UptimeCheckConfig()
509
json_config.display_name = "API JSON Response Check"
510

511
# Configure HTTP check
512
json_http_check = UptimeCheckConfig.HttpCheck()
513
json_http_check.use_ssl = True
514
json_http_check.path = "/api/v1/health"
515
json_http_check.port = 443
516
json_config.http_check = json_http_check
517

518
# Set resource
519
json_config.monitored_resource.type = "uptime_url"
520
json_config.monitored_resource.labels["project_id"] = project_id
521
json_config.monitored_resource.labels["host"] = "api.example.com"
522

523
# Add JSON path content matcher
524
json_matcher = UptimeCheckConfig.ContentMatcher()
525
json_path_matcher = UptimeCheckConfig.ContentMatcher.JsonPathMatcher()
526
json_path_matcher.json_path = "$.status"
527
json_path_matcher.json_matcher = UptimeCheckConfig.ContentMatcher.ContentMatcherOption.MATCHES_JSON_PATH
528
json_matcher.json_path_matcher = json_path_matcher
529
json_matcher.content = "healthy"
530

531
json_config.content_matchers = [json_matcher]
532

533
created_json_config = client.create_uptime_check_config(
534
    parent=project_name,
535
    uptime_check_config=json_config
536
)
537
print(f"Created JSON path uptime check: {created_json_config.name}")
538
```
539

540
### Listing Uptime Check IP Addresses
541

542
```python
543
# List IP addresses used by uptime checkers
544
print("Uptime checker IP addresses:")
545
for ip_info in client.list_uptime_check_ips():
546
    print(f"- Region: {ip_info.region}")
547
    print(f"  Location: {ip_info.location}")
548
    print(f"  IP: {ip_info.ip_address}")
549
```
550

551
### Deleting Uptime Check Configurations
552

553
```python
554
config_name = f"projects/{project_id}/uptimeCheckConfigs/{config_id}"
555
client.delete_uptime_check_config(name=config_name)
556
print(f"Deleted uptime check: {config_name}")
557
```
558

559
### Async Uptime Check Operations
560

561
```python
562
import asyncio
563
from google.cloud.monitoring import UptimeCheckServiceAsyncClient
564

565
async def manage_uptime_checks():
566
    client = UptimeCheckServiceAsyncClient()
567
    project_name = f"projects/{project_id}"
568
    
569
    # List configurations asynchronously
570
    async for config in await client.list_uptime_check_configs(parent=project_name):
571
        print(f"Async uptime check: {config.display_name}")
572
    
573
    # Get configuration asynchronously
574
    config = await client.get_uptime_check_config(name=config_name)
575
    print(f"Retrieved async config: {config.display_name}")
576

577
asyncio.run(manage_uptime_checks())
578
```
579

580
## Resource Path Helpers
581

582
```python { .api }
583
class UptimeCheckServiceClient:
584
    @staticmethod
585
    def uptime_check_config_path(project: str, uptime_check_config: str) -> str:
586
        """Returns a fully-qualified uptime_check_config string."""
587
        
588
    @staticmethod
589
    def parse_uptime_check_config_path(path: str) -> Dict[str, str]:
590
        """Parses an uptime_check_config path into its component segments."""
591

592
class SyntheticMonitorTarget:
593
    """Describes a Synthetic Monitor to be invoked by Uptime."""
594
    
595
    class CloudFunctionV2Target:
596
        """A Synthetic Monitor deployed to a Cloud Functions V2 instance."""
597
        name: str  # Required. Fully qualified GCFv2 resource name
598
        cloud_run_revision: MonitoredResource  # Output only. Associated cloud_run_revision
599
    
600
    cloud_function_v2: CloudFunctionV2Target  # Target a Synthetic Monitor GCFv2 instance
601
```
602

603
## Error Handling
604

605
Uptime check operations can raise specific exceptions:
606

607
```python
608
from google.api_core import exceptions
609
from google.cloud.monitoring import UptimeCheckServiceClient
610

611
client = UptimeCheckServiceClient()
612

613
try:
614
    config = client.get_uptime_check_config(name="invalid/path")
615
except exceptions.NotFound:
616
    print("Uptime check configuration not found")
617
except exceptions.InvalidArgument as e:
618
    print(f"Invalid uptime check configuration: {e}")
619
except exceptions.PermissionDenied:
620
    print("Insufficient permissions")
621
except exceptions.ResourceExhausted as e:
622
    print(f"Uptime check quota exceeded: {e}")
623
```