Microsoft.Azure.Documents.ServiceUnavailableException is internal to Microsoft.Azure.Cosmos.Direct

Is your feature request related to a problem? Please describe. We have the need to track when Microsoft.Azure.Documents.ServiceUnavailableException exceptions are thrown by the Cosmos DB SDK. Unfortunately it and its parent class, Microsoft.Azure.Documents.DocumentClientException, are internal to the Microsoft.Azure.Cosmos.Direct assembly. Furthermore, we really want to track the sub status code on the ServiceUnavailableException but the sub status code is a field on DocumentClientException and the Microsoft.Azure.Documents.SubStatusCodes enumeration is also internal to the Microsoft.Azure.Cosmos.Direct assembly.

Describe the solution you’d like Is it possible to make ServiceUnavailableException, DocumentClientException, and SubStatusCodes public types while also making the sub status code on DocumentClientException a public property?

Describe alternatives you’ve considered To get around this, we have to catch a plain Exception then use reflection to identify the exception as a ServiceUnavailableException then get its sub status code.

try
{
    // ...
}
catch (Exception ex)
{
    var cosmosDirectAssembly = Assembly.Load("Microsoft.Azure.Cosmos.Direct");
    var typeOfServiceUnavailableException = cosmosDirectAssembly.GetType("Microsoft.Azure.Documents.ServiceUnavailableException", false);
    var typeOfCosmosSubStatusCodes = cosmosDirectAssembly.GetType("Microsoft.Azure.Documents.SubStatusCodes", false);
    var typeOfNullableCosmosSubStatusCodes = typeof(Nullable<>).MakeGenericType(typeOfCosmosSubStatusCodes);
    var typeOfDocumentClientException = cosmosDirectAssembly.GetType("Microsoft.Azure.Documents.DocumentClientException", false);
    var serviceUnavailableExceptionSubStatusCode = typeOfDocumentClientException
                    .GetFields(BindingFlags.Instance | BindingFlags.Public | BindingFlags.NonPublic)
                    .FirstOrDefault(p => p.FieldType == typeOfNullableCosmosSubStatusCodes);

    if (ex.GetType() == typeOfServiceUnavailableException)
    {
        var subStatusCode = serviceUnavailableExceptionSubStatusCode.GetValue(ex);
        // Log the substatus code
    }
}

[ealsur]

1. If there are any properties that you require access, please let us know and we’ll help understand how you can access them. Why do you need to check for GoneExceptions? It is an internal type and was not even public on V2 SDK (so it is not a migration gap), giving access just for the sake of access?
2. If the intent is to propagate to the original caller, then you can simply propagate all Headers, that should be the correct thing, because you don’t know which header the caller is interested on. Maybe the caller wants to know the Session Token. So in that scenario, just iterate over the Headers and add them to the response, for example: https://github.com/ealsur/ondotnet-cosmosdb/blob/master/src/episode1/streams/Controllers/ItemsController.cs#L40-L57. For 503 troubleshooting, there is nothing you can programmatically do based on the substatus. If its 20001 or 20002, there is no code you can change to act on it, in both cases, you are experiencing connectivity issues, the recommendation for both is the same for your application: https://learn.microsoft.com/en-us/azure/cosmos-db/nosql/conceptual-resilient-sdk-applications#timeouts-and-connectivity-related-failures-http-408503. Now, if the volume of these 503s exceeds the expectations yes, the Substatus and the entire Diagnostics help root causing, but fixing the issue is not something the application, from code, can do, it’s someone who is diagnosing the details that needs to act on it.

I want to reiterate, if the use case is there, we will help either making the information accessible through public methods or properties if it’s not or helping with how you can obtain it from the current public methods. But there should be a use case for it, there should be value in exposing that.

Everything described in this thread so far is achievable through the current public surface API.

[ohads-MSFT]

@ealsur

1. I don’t have a specific use case in mind, but for example it might be interesting to check GoneException::LocalIp or one of the DocumentClientException properties that aren’t exposed on the CosmosException (e.g. StatusDescription).
2. Getting the substatus is not the issue, indeed I have it under the public CosmosException::SubStatusCode. As you mentioned, the issue is acting upon it programmatically, namely comparing the substatus to some known values in the currently internal enum SubStatusCodes. I imagine there might be various use cases, but if I were to speak to ours, it’s for detecting client-side issues specifically (e.g. TimeoutGenerated410). For example, we might to translate these into other HTTP responses back to the original caller (e.g. 429).