Description

This PR adds a diagnostics handler for the Python SDK of Cosmos DB. In short the python sdk diagnostics handler works a bit differently than the other SDKs in order to best fit the development needs and style of the Python programming language. The way the handler works in the Python SDK is that the handler is used to determine if http requests and responses should be logged using the Cosmos Http Logging Policy. By default, the behaviour is to log every request if the diagnostics is enabled, with the handler the user can customize the conditions for logging by either passing in a custom should_log method or by subclassing the handler and overriding the should_log method. They can also pass in an object with the mapping protocol that matches the key and values (simple lambdas) the http logging policy expects. The most customizable way to make the handler is making a function. The passed in function can also be passed and treated as a class method to allow the user access to log additional things such as cpu usage using their own preferred library or just maximize the customization of what conditions they want to log under. A CosmosDiagnosticsHandler class is also available to use as an easy way to define the logging conditions by simply initializing it and passing in the client. Here is a diagram to show how it works:

flowchart TD
    A[Initialize Cosmos Client] --> B{Is Diagnostics Enabled?}
    B -- No --> C[Continue with Default Behavior]
    B -- Yes --> D{Is Handler Callable?}
    D -- Yes --> E[Set should_log Method to Callable]
    D -- No --> F{Is Handler a Dictionary?}
    F -- Yes --> G[Set should_log Method in Cosmos Logging Policy to dict_should_log]
    F -- No --> C[Continue with Default Behavior]

Azure / azure-sdk-for-python

Cosmos Diagnostics Handler for Python SDK #38581

Description