-
Notifications
You must be signed in to change notification settings - Fork 494
/
CosmosDiagnostics.cs
101 lines (95 loc) · 4.85 KB
/
CosmosDiagnostics.cs
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
//------------------------------------------------------------
// Copyright (c) Microsoft Corporation. All rights reserved.
//------------------------------------------------------------
namespace Microsoft.Azure.Cosmos
{
using System;
using System.Collections.Generic;
/// <summary>
/// Contains the cosmos diagnostic information for the current request to Azure Cosmos DB service.
/// </summary>
public abstract class CosmosDiagnostics
{
/// <summary>
/// This represent the end to end elapsed time of the request.
/// If the request is still in progress it will return the current
/// elapsed time since the start of the request.
/// </summary>
/// <returns>The clients end to end elapsed time of the request.</returns>
public virtual TimeSpan GetClientElapsedTime()
{
// Default implementation avoids breaking change for users upgrading.
throw new NotImplementedException($"CosmosDiagnostics.GetElapsedTime");
}
/// <summary>
/// This represents the start time of the request.
/// </summary>
/// <returns>This returns the start time of the request.</returns>
public virtual DateTime? GetStartTimeUtc()
{
// Default implementation avoids breaking change for users upgrading.
throw new NotImplementedException($"{nameof(CosmosDiagnostics)}.{nameof(GetStartTimeUtc)})");
}
/// <summary>
/// This represents the count of failed requests.
/// </summary>
/// <returns>The count of failed requests with cosmos service.</returns>
public virtual int GetFailedRequestCount()
{
// Default implementation avoids breaking change for users upgrading.
throw new NotImplementedException($"{nameof(CosmosDiagnostics)}.{nameof(GetFailedRequestCount)}");
}
/// <summary>
/// This represents the backend query metrics for the request.
/// </summary>
/// <remarks>
/// This is only applicable for query operations. For all other operations this will return null.
/// </remarks>
/// <returns>The accumulated backend metrics for the request.</returns>
public virtual ServerSideCumulativeMetrics GetQueryMetrics()
{
// Default implementation avoids breaking change for users upgrading.
throw new NotImplementedException($"{nameof(CosmosDiagnostics)}.{nameof(GetQueryMetrics)}");
}
/// <summary>
/// Gets the string field <see cref="CosmosDiagnostics"/> instance in the Azure Cosmos DB database service.
/// </summary>
/// <returns>The string field <see cref="CosmosDiagnostics"/> instance in the Azure Cosmos DB database service.</returns>
/// <remarks>
/// <see cref="CosmosDiagnostics"/> implements lazy materialization and is only materialized when <see cref="CosmosDiagnostics.ToString"/> is called.
/// </remarks>
/// <example>
/// Do not eagerly materialize the diagnostics until the moment of consumption to avoid unnecessary allocations, let the ToString be called only when needed.
/// You can capture diagnostics conditionally, based on latency or errors:
/// <code language="c#">
/// <![CDATA[
/// try
/// {
/// ItemResponse<Book> response = await container.CreateItemAsync<Book>(item: testItem);
/// if (response.Diagnostics.GetClientElapsedTime() > ConfigurableSlowRequestTimeSpan)
/// {
/// // Log the diagnostics and add any additional info necessary to correlate to other logs
/// logger.LogInformation("Operation took longer than expected, Diagnostics: {Diagnostics}");
/// }
/// }
/// catch (CosmosException cosmosException)
/// {
/// // Log the full exception including the stack trace
/// logger.LogError(cosmosException);
/// // The Diagnostics can be logged separately if required.
/// logger.LogError("Cosmos DB call failed with {StatusCode}, {SubStatusCode}, Diagnostics: {Diagnostics}", cosmosException.StatusCode, cosmosException.SubStatusCode, cosmosException.Diagnostics);
/// }
/// ]]>
/// </code>
/// </example>
public abstract override string ToString();
/// <summary>
/// Gets the list of all regions that were contacted for a request
/// </summary>
/// <returns>The list of tuples containing the Region name and the URI</returns>
/// <remarks>
/// The returned list contains unique regions and doesn't guarantee ordering of the regions contacted from the first to the last
/// </remarks>
public abstract IReadOnlyList<(string regionName, Uri uri)> GetContactedRegions();
}
}