0
# Usage Monitoring
1

2
Monitoring and reporting capabilities for Recovery Services vault usage metrics, replication usage statistics, and capacity planning information. These operations provide insights into storage consumption, backup operations, and service utilization for cost management and capacity planning.
3

4
## Capabilities
5

6
### Get Vault Usage Information
7

8
Retrieves usage metrics for a specific Recovery Services vault including storage consumption and backup item counts.
9

10
```python { .api }
11
def list_by_vaults(resource_group_name: str, vault_name: str, **kwargs) -> ItemPaged[VaultUsage]:
12
    """
13
    Fetches the usages of the vault.
14
    
15
    Parameters:
16
    - resource_group_name: str - The name of the resource group
17
    - vault_name: str - The name of the recovery services vault
18
    
19
    Returns:
20
    ItemPaged[VaultUsage]: An iterator of vault usage information
21
    """
22
```
23

24
**Usage Example:**
25

26
```python
27
# Get vault usage information
28
usages = client.usages.list_by_vaults(
29
    resource_group_name="my-rg", 
30
    vault_name="my-vault"
31
)
32

33
for usage in usages:
34
    print(f"Usage Metric: {usage.name.localized_value}")
35
    print(f"  Current Value: {usage.current_value}")
36
    print(f"  Limit: {usage.limit}")
37
    print(f"  Unit: {usage.unit}")
38
    
39
    # Calculate percentage used
40
    if usage.limit and usage.limit > 0:
41
        percentage = (usage.current_value / usage.limit) * 100
42
        print(f"  Usage: {percentage:.1f}%")
43
    print()
44
```
45

46
### Get Replication Usage Information
47

48
Retrieves replication usage statistics for site recovery operations within a vault.
49

50
```python { .api }
51
def list(resource_group_name: str, vault_name: str, **kwargs) -> ItemPaged[ReplicationUsage]:
52
    """
53
    Fetches the replication usages of the vault.
54
    
55
    Parameters:
56
    - resource_group_name: str - The name of the resource group  
57
    - vault_name: str - The name of the recovery services vault
58
    
59
    Returns:
60
    ItemPaged[ReplicationUsage]: An iterator of replication usage information
61
    """
62
```
63

64
**Usage Example:**
65

66
```python
67
# Get replication usage information
68
replication_usages = client.replication_usages.list(
69
    resource_group_name="my-rg",
70
    vault_name="my-vault"
71
)
72

73
for usage in replication_usages:
74
    print(f"Replication Usage: {usage.monitor_summary.events_summary}")
75
    print(f"  Jobs Summary: {usage.jobs_summary}")
76
    print(f"  Monitoring Summary: {usage.monitor_summary}")
77
    print()
78
```
79

80
## Usage Types
81

82
### Vault Usage
83

84
```python { .api }
85
class VaultUsage:
86
    """
87
    Usages of a vault.
88
    
89
    Parameters:
90
    - unit: Optional[UsagesUnit] - Unit of the usage (Count, Bytes, Seconds, Percent, CountPerSecond, BytesPerSecond)
91
    - quota_period: Optional[str] - Quota period of usage
92
    - next_reset_time: Optional[datetime] - Next reset time of usage
93
    - name: Optional[NameInfo] - The name of the usage
94
    - current_value: Optional[int] - Current value of usage
95
    - limit: Optional[int] - Limit of usage
96
    """
97
```
98

99
### Vault Usage List
100

101
```python { .api }
102
class VaultUsageList:
103
    """
104
    Usage for vault.
105
    
106
    Parameters:
107
    - value: Optional[List[VaultUsage]] - The list of usages for the given vault
108
    """
109
```
110

111
### Replication Usage
112

113
```python { .api }
114
class ReplicationUsage:
115
    """
116
    Replication usage of a vault.
117
    
118
    Parameters:
119
    - monitor_summary: Optional[MonitoringSummary] - Summary of the replication monitoring data for this vault
120
    - jobs_summary: Optional[JobsSummary] - Summary of the replication jobs data for this vault
121
    """
122
```
123

124
### Replication Usage List
125

126
```python { .api }
127
class ReplicationUsageList:
128
    """
129
    Replication usages for vault.
130
    
131
    Parameters:
132
    - value: Optional[List[ReplicationUsage]] - The list of replication usages for the given vault
133
    """
134
```
135

136
### Name Info
137

138
```python { .api }
139
class NameInfo:
140
    """
141
    The name of usage.
142
    
143
    Parameters:
144
    - value: Optional[str] - Value of usage
145
    - localized_value: Optional[str] - Localized value of usage
146
    """
147
```
148

149
### Monitoring Summary
150

151
```python { .api }
152
class MonitoringSummary:
153
    """
154
    Summary of the replication monitoring data for this vault.
155
    
156
    Parameters:
157
    - unhealthy_vm_count: Optional[int] - Count of unhealthy VMs
158
    - unhealthy_provider_count: Optional[int] - Count of unhealthy replication providers
159
    - events_summary: Optional[Dict[str, int]] - Summary of events
160
    - deprecated_provider_count: Optional[int] - Count of deprecated providers
161
    - supported_provider_count: Optional[int] - Count of supported providers
162
    - unsupported_provider_count: Optional[int] - Count of unsupported providers
163
    """
164
```
165

166
### Jobs Summary
167

168
```python { .api }
169
class JobsSummary:
170
    """
171
    Summary of the replication jobs data for this vault.
172
    
173
    Parameters:
174
    - failed_jobs: Optional[int] - Count of failed jobs
175
    - suspended_jobs: Optional[int] - Count of suspended jobs
176
    - in_progress_jobs: Optional[int] - Count of in-progress jobs
177
    """
178
```
179

180
## Usage Units
181

182
```python { .api }
183
class UsagesUnit(str, Enum):
184
    """
185
    Unit of the usage.
186
    """
187
    COUNT = "Count"
188
    BYTES = "Bytes"
189
    SECONDS = "Seconds"
190
    PERCENT = "Percent"
191
    COUNT_PER_SECOND = "CountPerSecond"
192
    BYTES_PER_SECOND = "BytesPerSecond"
193
```
194

195
## Usage Patterns
196

197
### Comprehensive Vault Usage Report
198

199
```python
200
from datetime import datetime
201

202
def generate_vault_usage_report(client, resource_group: str, vault_name: str):
203
    """
204
    Generate a comprehensive usage report for a Recovery Services vault.
205
    """
206
    
207
    print(f"=== Usage Report for Vault: {vault_name} ===")
208
    print(f"Generated at: {datetime.now().strftime('%Y-%m-%d %H:%M:%S')}")
209
    print(f"Resource Group: {resource_group}")
210
    print()
211
    
212
    try:
213
        # Get vault usage information
214
        print("📊 VAULT USAGE METRICS")
215
        print("-" * 50)
216
        
217
        usages = client.usages.list_by_vaults(resource_group, vault_name)
218
        usage_found = False
219
        
220
        for usage in usages:
221
            usage_found = True
222
            print(f"Metric: {usage.name.localized_value}")
223
            print(f"  Current: {usage.current_value:,}")
224
            print(f"  Limit: {usage.limit:,}" if usage.limit else "  Limit: Unlimited")
225
            print(f"  Unit: {usage.unit}")
226
            
227
            # Calculate and display percentage if limit exists
228
            if usage.limit and usage.limit > 0:
229
                percentage = (usage.current_value / usage.limit) * 100
230
                print(f"  Usage: {percentage:.1f}%")
231
                
232
                # Add warning for high usage
233
                if percentage > 80:
234
                    print("  ⚠️  WARNING: High usage detected!")
235
                elif percentage > 95:
236
                    print("  🚨 CRITICAL: Near limit!")
237
            
238
            # Show next reset time if available
239
            if usage.next_reset_time:
240
                print(f"  Next Reset: {usage.next_reset_time}")
241
            
242
            print()
243
        
244
        if not usage_found:
245
            print("No usage metrics available")
246
        
247
        # Get replication usage information
248
        print("🔄 REPLICATION USAGE METRICS")
249
        print("-" * 50)
250
        
251
        replication_usages = client.replication_usages.list(resource_group, vault_name)
252
        replication_found = False
253
        
254
        for repl_usage in replication_usages:
255
            replication_found = True
256
            
257
            # Jobs summary
258
            if repl_usage.jobs_summary:
259
                jobs = repl_usage.jobs_summary
260
                print("Job Statistics:")
261
                print(f"  ✅ In Progress: {jobs.in_progress_jobs or 0}")
262
                print(f"  ❌ Failed: {jobs.failed_jobs or 0}")
263
                print(f"  ⏸️  Suspended: {jobs.suspended_jobs or 0}")
264
                
265
                # Calculate total jobs
266
                total_jobs = (jobs.in_progress_jobs or 0) + (jobs.failed_jobs or 0) + (jobs.suspended_jobs or 0)
267
                print(f"  📊 Total: {total_jobs}")
268
                
269
                if jobs.failed_jobs and jobs.failed_jobs > 0:
270
                    print("  ⚠️  WARNING: Failed jobs detected!")
271
                print()
272
            
273
            # Monitoring summary  
274
            if repl_usage.monitor_summary:
275
                monitor = repl_usage.monitor_summary
276
                print("Health Statistics:")
277
                print(f"  🏥 Unhealthy VMs: {monitor.unhealthy_vm_count or 0}")
278
                print(f"  🔧 Unhealthy Providers: {monitor.unhealthy_provider_count or 0}")
279
                print(f"  ✅ Supported Providers: {monitor.supported_provider_count or 0}")
280
                print(f"  ❌ Unsupported Providers: {monitor.unsupported_provider_count or 0}")
281
                print(f"  📅 Deprecated Providers: {monitor.deprecated_provider_count or 0}")
282
                
283
                if monitor.unhealthy_vm_count and monitor.unhealthy_vm_count > 0:
284
                    print("  ⚠️  WARNING: Unhealthy VMs detected!")
285
                
286
                # Events summary
287
                if monitor.events_summary:
288
                    print("\nEvent Summary:")
289
                    for event_type, count in monitor.events_summary.items():
290
                        print(f"  {event_type}: {count}")
291
                print()
292
        
293
        if not replication_found:
294
            print("No replication usage metrics available")
295
            
296
    except Exception as e:
297
        print(f"Error generating usage report: {e}")
298
        raise
299
```
300

301
### Usage Monitoring and Alerting
302

303
```python
304
def monitor_vault_usage_with_alerts(client, resource_group: str, vault_name: str, alert_threshold: float = 80.0):
305
    """
306
    Monitor vault usage and generate alerts when thresholds are exceeded.
307
    """
308
    
309
    alerts = []
310
    
311
    try:
312
        # Monitor vault usage
313
        usages = client.usages.list_by_vaults(resource_group, vault_name)
314
        
315
        for usage in usages:
316
            if usage.limit and usage.limit > 0:
317
                percentage = (usage.current_value / usage.limit) * 100
318
                
319
                if percentage >= alert_threshold:
320
                    alert = {
321
                        "vault": vault_name,
322
                        "metric": usage.name.localized_value,
323
                        "current_value": usage.current_value,
324
                        "limit": usage.limit,
325
                        "percentage": percentage,
326
                        "unit": usage.unit,
327
                        "severity": "critical" if percentage >= 95 else "warning"
328
                    }
329
                    alerts.append(alert)
330
        
331
        # Monitor replication health
332
        replication_usages = client.replication_usages.list(resource_group, vault_name)
333
        
334
        for repl_usage in replication_usages:
335
            # Check for failed jobs
336
            if repl_usage.jobs_summary and repl_usage.jobs_summary.failed_jobs:
337
                if repl_usage.jobs_summary.failed_jobs > 0:
338
                    alert = {
339
                        "vault": vault_name,
340
                        "metric": "Failed Replication Jobs",
341
                        "current_value": repl_usage.jobs_summary.failed_jobs,
342
                        "severity": "warning",
343
                        "message": f"{repl_usage.jobs_summary.failed_jobs} replication jobs have failed"
344
                    }
345
                    alerts.append(alert)
346
            
347
            # Check for unhealthy VMs
348
            if repl_usage.monitor_summary and repl_usage.monitor_summary.unhealthy_vm_count:
349
                if repl_usage.monitor_summary.unhealthy_vm_count > 0:
350
                    alert = {
351
                        "vault": vault_name,
352
                        "metric": "Unhealthy VMs",
353
                        "current_value": repl_usage.monitor_summary.unhealthy_vm_count,
354
                        "severity": "warning",
355
                        "message": f"{repl_usage.monitor_summary.unhealthy_vm_count} VMs are in unhealthy state"
356
                    }
357
                    alerts.append(alert)
358
        
359
        return alerts
360
        
361
    except Exception as e:
362
        print(f"Error monitoring vault usage: {e}")
363
        raise
364

365
def process_usage_alerts(alerts):
366
    """Process and display usage alerts."""
367
    
368
    if not alerts:
369
        print("✅ No usage alerts - all metrics within normal range")
370
        return
371
    
372
    print(f"🚨 {len(alerts)} usage alert(s) detected:")
373
    print()
374
    
375
    critical_alerts = [a for a in alerts if a.get("severity") == "critical"]
376
    warning_alerts = [a for a in alerts if a.get("severity") == "warning"]
377
    
378
    if critical_alerts:
379
        print("🚨 CRITICAL ALERTS:")
380
        for alert in critical_alerts:
381
            print(f"  Vault: {alert['vault']}")
382
            print(f"  Metric: {alert['metric']}")
383
            if 'percentage' in alert:
384
                print(f"  Usage: {alert['percentage']:.1f}% ({alert['current_value']:,}/{alert['limit']:,} {alert['unit']})")
385
            else:
386
                print(f"  Value: {alert['current_value']}")
387
                if 'message' in alert:
388
                    print(f"  Details: {alert['message']}")
389
            print()
390
    
391
    if warning_alerts:
392
        print("⚠️  WARNING ALERTS:")
393
        for alert in warning_alerts:
394
            print(f"  Vault: {alert['vault']}")
395
            print(f"  Metric: {alert['metric']}")
396
            if 'percentage' in alert:
397
                print(f"  Usage: {alert['percentage']:.1f}% ({alert['current_value']:,}/{alert['limit']:,} {alert['unit']})")
398
            else:
399
                print(f"  Value: {alert['current_value']}")
400
                if 'message' in alert:
401
                    print(f"  Details: {alert['message']}")
402
            print()
403
```
404

405
### Historical Usage Tracking
406

407
```python
408
import json
409
from pathlib import Path
410
from datetime import datetime
411

412
def track_usage_history(client, resource_group: str, vault_name: str, history_file: str = "vault_usage_history.json"):
413
    """
414
    Track vault usage over time by appending current metrics to a history file.
415
    """
416
    
417
    timestamp = datetime.now().isoformat()
418
    
419
    # Collect current usage data
420
    usage_data = {
421
        "timestamp": timestamp,
422
        "vault_name": vault_name,
423
        "resource_group": resource_group,
424
        "vault_usage": [],
425
        "replication_usage": []
426
    }
427
    
428
    try:
429
        # Get vault usage
430
        usages = client.usages.list_by_vaults(resource_group, vault_name)
431
        for usage in usages:
432
            usage_record = {
433
                "metric": usage.name.localized_value,
434
                "current_value": usage.current_value,
435
                "limit": usage.limit,
436
                "unit": usage.unit,
437
                "percentage": (usage.current_value / usage.limit * 100) if usage.limit and usage.limit > 0 else None
438
            }
439
            usage_data["vault_usage"].append(usage_record)
440
        
441
        # Get replication usage
442
        replication_usages = client.replication_usages.list(resource_group, vault_name)
443
        for repl_usage in replication_usages:
444
            repl_record = {}
445
            
446
            if repl_usage.jobs_summary:
447
                repl_record["jobs"] = {
448
                    "in_progress": repl_usage.jobs_summary.in_progress_jobs,
449
                    "failed": repl_usage.jobs_summary.failed_jobs,
450
                    "suspended": repl_usage.jobs_summary.suspended_jobs
451
                }
452
            
453
            if repl_usage.monitor_summary:
454
                repl_record["monitoring"] = {
455
                    "unhealthy_vms": repl_usage.monitor_summary.unhealthy_vm_count,
456
                    "unhealthy_providers": repl_usage.monitor_summary.unhealthy_provider_count,
457
                    "supported_providers": repl_usage.monitor_summary.supported_provider_count
458
                }
459
            
460
            if repl_record:
461
                usage_data["replication_usage"].append(repl_record)
462
        
463
        # Load existing history
464
        history = []
465
        history_path = Path(history_file)
466
        if history_path.exists():
467
            with open(history_path, 'r') as f:
468
                history = json.load(f)
469
        
470
        # Append new data
471
        history.append(usage_data)
472
        
473
        # Keep only last 30 days of data (assuming daily collection)
474
        if len(history) > 30:
475
            history = history[-30:]
476
        
477
        # Save updated history
478
        with open(history_path, 'w') as f:
479
            json.dump(history, f, indent=2, default=str)
480
        
481
        print(f"Usage data saved to {history_file}")
482
        return usage_data
483
        
484
    except Exception as e:
485
        print(f"Error tracking usage history: {e}")
486
        raise
487
```