[Cosmos] Add logging changes and sample (#22288)

* adds changes to client pipeline and readme sample

* fixed padding and improved ReadMe sample

* moved headers to cosmos_headers, lowercased values

* changes for fully working diagnostics

* Update README.md

* use latest azcore version

* Update README.md

* Update cosmos_client_test.go

Author: simorenoh

sdk/data/azcosmos/README.md

@@ -34,6 +34,33 @@ You can create an Azure Cosmos account using:
 
 In order to interact with the Azure Cosmos DB service you'll need to create an instance of the Cosmos client class. To make this possible you will need an URL and key of the Azure Cosmos DB service.
 
+#### Logging
+
+The SDK can make use of `azcore`'s logging implementation to collect useful information for debugging your application. In order to make use of logs, one must set the environment variable `"AZURE_SDK_GO_LOGGING"` to `"all"` like outlined in this [public document](https://pkg.go.dev/github.com/Azure/azure-sdk-for-go/sdk/azcore#hdr-Built_in_Logging).
+
+Once that is done, the SDK will begin to collect diagnostics. By default, it will output the logs to `stdout` - printing directly to your console - and will record all types of events (requests, responses, retries). If you'd like to configure a listener that acts differently, the small snippet below shows how you could do so.
+
+```go
+import (
+	"os"
+	azlog "github.com/Azure/azure-sdk-for-go/sdk/azcore/log"
+)
+
+f, err := os.Create("cosmos-log-file.txt")
+handle(err)
+defer f.Close()
+
+// Configure the listener to write to a file rather than to the console
+azlog.SetListener(func(event azlog.Event, s string) {
+	f.WriteString(s + "\n")
+})
+
+// Filter the types of events you'd like to log by removing the ones you're not interested in (if any)
+// We recommend using the default logging with no filters - but if filtering we recommend *always* including 
+// `azlog.EventResponseError` since this is the event type that will help with debugging errors
+azlog.SetEvents(azlog.EventRequest, azlog.EventResponse, azlog.EventRetryPolicy, azlog.EventResponseError) 
+```
+
 ## Examples
 
 The following section provides several code snippets covering some of the most common Cosmos DB SQL API tasks, including:

sdk/data/azcosmos/cosmos_client.go

@@ -113,9 +113,9 @@ func newPipeline(authPolicy policy.Policy, gem *globalEndpointManager, options *
 	if options == nil {
 		options = &ClientOptions{}
 	}
-
 	return azruntime.NewPipeline("azcosmos", serviceLibVersion,
 		azruntime.PipelineOptions{
+			AllowedHeaders: getAllowedHeaders(),
 			PerCall: []policy.Policy{
 				&headerPolicies{
 					enableContentResponseOnWrite: options.EnableContentResponseOnWrite,
@@ -135,6 +135,7 @@ func newInternalPipeline(authPolicy policy.Policy, options *ClientOptions) azrun
 	}
 	return azruntime.NewPipeline("azcosmos", serviceLibVersion,
 		azruntime.PipelineOptions{
+			AllowedHeaders: getAllowedHeaders(),
 			PerRetry: []policy.Policy{
 				authPolicy,
 			},
@@ -471,7 +472,7 @@ func (c *Client) executeAndEnsureSuccessResponse(request *policy.Request) (*http
 		return response, nil
 	}
 
-	return nil, newCosmosError(response)
+	return nil, azruntime.NewResponseErrorWithErrorCode(response, response.Status)
 }
 
 type pipelineRequestOptions struct {
@@ -481,3 +482,79 @@ type pipelineRequestOptions struct {
 	isRidBased            bool
 	isWriteOperation      bool
 }
+
+func getAllowedHeaders() []string {
+	return []string{
+		cosmosHeaderRequestCharge,
+		cosmosHeaderActivityId,
+		cosmosHeaderEtag,
+		cosmosHeaderSubstatus,
+		cosmosHeaderPopulateQuotaInfo,
+		cosmosHeaderPreTriggerInclude,
+		cosmosHeaderPostTriggerInclude,
+		cosmosHeaderIndexingDirective,
+		cosmosHeaderSessionToken,
+		cosmosHeaderConsistencyLevel,
+		cosmosHeaderPrefer,
+		cosmosHeaderIsUpsert,
+		cosmosHeaderOfferThroughput,
+		cosmosHeaderOfferAutoscale,
+		cosmosHeaderQuery,
+		cosmosHeaderOfferReplacePending,
+		cosmosHeaderOfferMinimumThroughput,
+		cosmosHeaderResponseContinuationTokenLimitInKb,
+		cosmosHeaderEnableScanInQuery,
+		cosmosHeaderMaxItemCount,
+		cosmosHeaderContinuationToken,
+		cosmosHeaderPopulateIndexMetrics,
+		cosmosHeaderPopulateQueryMetrics,
+		cosmosHeaderQueryMetrics,
+		cosmosHeaderIndexUtilization,
+		cosmosHeaderCorrelatedActivityId,
+		cosmosHeaderIsBatchRequest,
+		cosmosHeaderIsBatchAtomic,
+		cosmosHeaderIsBatchOrdered,
+		cosmosHeaderSDKSupportedCapabilities,
+		headerXmsDate,
+		headerContentType,
+		headerIfMatch,
+		headerIfNoneMatch,
+		headerXmsVersion,
+		headerContentLocation,
+		headerXmsGatewayVersion,
+		headerLsn,
+		headerXmsCosmosLlsn,
+		headerXmsCosmosItemLlsn,
+		headerXmsItemLsn,
+		headerXmsCosmosQuorumAckedLlsn,
+		headerXmsCurrentReplicaSetSize,
+		headerXmsCurrentWriteQuorum,
+		headerXmsGlobalCommittedLsn,
+		headerXmsLastStateChangeUtc,
+		headerXmsNumberOfReadRegions,
+		headerXmsQuorumAckedLsn,
+		headerXmsRequestDurationMs,
+		headerXmsResourceQuota,
+		headerXmsResourceUsage,
+		headerXmsSchemaVersion,
+		headerXmsServiceVersion,
+		headerXmsTransportRequestId,
+		headerXmsXpRole,
+		headerCollectionPartitionIndex,
+		headerCollectionServiceIndex,
+		headerXmsDocumentDbPartitionKeyRangeId,
+		cosmosHeaderPhysicalPartitionId,
+		headerStrictTransportSecurity,
+		headerXmsDatabaseAccountConsumedMb,
+		headerXmsDatabaseAccountProvisionedMb,
+		headerXmsDatabaseAccountReservedMb,
+		headerXmsMaxMediaStorageUsageMb,
+		headerXmsMediaStorageUsageMb,
+		headerXmsContentPath,
+		headerXmsAltContentPath,
+		cosmosHeaderMaxContentLength,
+		cosmosHeaderIsPartitionKeyDeletePending,
+		cosmosHeaderQueryExecutionInfo,
+		headerXmsItemCount,
+	}
+}

sdk/data/azcosmos/cosmos_client_test.go

@@ -10,6 +10,7 @@ import (
 	"net/http"
 	"net/url"
 	"strconv"
+	"strings"
 	"testing"
 
 	"github.com/Azure/azure-sdk-for-go/sdk/azcore"
@@ -75,9 +76,7 @@ func TestNewClientFromConnStrSuccess(t *testing.T) {
 }
 
 func TestEnsureErrorIsGeneratedOnResponse(t *testing.T) {
-	someError := &cosmosErrorResponse{
-		Code: "SomeCode",
-	}
+	someError := map[string]string{"Code": "SomeCode"}
 
 	jsonString, err := json.Marshal(someError)
 	if err != nil {
@@ -102,13 +101,24 @@ func TestEnsureErrorIsGeneratedOnResponse(t *testing.T) {
 	}
 
 	asError := err.(*azcore.ResponseError)
-	if asError.ErrorCode != someError.Code {
-		t.Errorf("Expected %v, but got %v", someError.Code, asError.ErrorCode)
+	if asError.ErrorCode != "404 Not Found" {
+		t.Errorf("Expected %v, but got %v", "404 Not Found", asError.ErrorCode)
+	}
+
+	// Verify error body
+	responseBody, err2 := io.ReadAll(asError.RawResponse.Body)
+	if err2 != nil {
+		t.Errorf("Error reading response body: %v\n", err)
+	}
+	stringBody := string(responseBody)
+	if !strings.Contains(stringBody, "SomeCode") {
+		t.Errorf("Expected %v to contain %v", stringBody, "SomeCode")
 	}
 
 	if err.Error() != asError.Error() {
 		t.Errorf("Expected %v, but got %v", err.Error(), asError.Error())
 	}
+	asError.RawResponse.Body.Close()
 }
 
 func TestEnsureErrorIsNotGeneratedOnResponse(t *testing.T) {

sdk/data/azcosmos/cosmos_error.go

@@ -15,6 +15,7 @@ import (
 	"github.com/Azure/azure-sdk-for-go/sdk/azcore/policy"
 	azruntime "github.com/Azure/azure-sdk-for-go/sdk/azcore/runtime"
 	"github.com/Azure/azure-sdk-for-go/sdk/internal/mock"
+	"github.com/stretchr/testify/assert"
 )
 
 func TestCosmosErrorOnEmptyResponse(t *testing.T) {
@@ -32,13 +33,13 @@ func TestCosmosErrorOnEmptyResponse(t *testing.T) {
 	resp, _ := pl.Do(req)
 
 	var azErr *azcore.ResponseError
-	if err := newCosmosError(resp); !errors.As(err, &azErr) {
+	if err := azruntime.NewResponseErrorWithErrorCode(resp, resp.Status); !errors.As(err, &azErr) {
 		t.Fatalf("unexpected error type %T", err)
 	}
 	if azErr.StatusCode != http.StatusNotFound {
 		t.Errorf("unexpected status code %d", azErr.StatusCode)
 	}
-	if azErr.ErrorCode != "" {
+	if azErr.ErrorCode != "404 Not Found" {
 		t.Errorf("unexpected error code %s", azErr.ErrorCode)
 	}
 	if azErr.RawResponse == nil {
@@ -62,13 +63,13 @@ func TestCosmosErrorOnNonJsonBody(t *testing.T) {
 	resp, _ := pl.Do(req)
 
 	var azErr *azcore.ResponseError
-	if err := newCosmosError(resp); !errors.As(err, &azErr) {
+	if err := azruntime.NewResponseErrorWithErrorCode(resp, resp.Status); !errors.As(err, &azErr) {
 		t.Fatalf("unexpected error type %T", err)
 	}
 	if azErr.StatusCode != http.StatusNotFound {
 		t.Errorf("unexpected status code %d", azErr.StatusCode)
 	}
-	if azErr.ErrorCode != "" {
+	if azErr.ErrorCode != "404 Not Found" {
 		t.Errorf("unexpected error code %s", azErr.ErrorCode)
 	}
 	if azErr.RawResponse == nil {
@@ -80,9 +81,7 @@ func TestCosmosErrorOnNonJsonBody(t *testing.T) {
 }
 
 func TestCosmosErrorOnJsonBody(t *testing.T) {
-	someError := &cosmosErrorResponse{
-		Code: "SomeCode",
-	}
+	someError := map[string]string{"Code": "SomeCode"}
 
 	jsonString, err := json.Marshal(someError)
 	if err != nil {
@@ -104,13 +103,15 @@ func TestCosmosErrorOnJsonBody(t *testing.T) {
 	resp, _ := pl.Do(req)
 
 	var azErr *azcore.ResponseError
-	if err := newCosmosError(resp); !errors.As(err, &azErr) {
+	err2 := azruntime.NewResponseErrorWithErrorCode(resp, resp.Status)
+	assert.Error(t, err2)
+	if err := azruntime.NewResponseErrorWithErrorCode(resp, resp.Status); !errors.As(err, &azErr) {
 		t.Fatalf("unexpected error type %T", err)
 	}
 	if azErr.StatusCode != http.StatusNotFound {
 		t.Errorf("unexpected status code %d", azErr.StatusCode)
 	}
-	if azErr.ErrorCode != someError.Code {
+	if azErr.ErrorCode != "404 Not Found" {
 		t.Errorf("unexpected error code %s", azErr.ErrorCode)
 	}
 	if azErr.RawResponse == nil {

sdk/data/azcosmos/cosmos_error_test.go

@@ -139,7 +139,7 @@ func (gem *globalEndpointManager) GetAccountProperties(ctx context.Context) (acc
 		return properties, nil
 	}
 
-	return accountProperties{}, newCosmosError(azResponse)
+	return accountProperties{}, azruntime.NewResponseErrorWithErrorCode(azResponse, azResponse.Status)
 }
 
 func newAccountProperties(azResponse *http.Response) (accountProperties, error) {

sdk/data/azcosmos/cosmos_global_endpoint_manager.go

@@ -7,6 +7,7 @@ const (
 	cosmosHeaderRequestCharge                      string = "x-ms-request-charge"
 	cosmosHeaderActivityId                         string = "x-ms-activity-id"
 	cosmosHeaderEtag                               string = "etag"
+	cosmosHeaderSubstatus                          string = "x-ms-substatus"
 	cosmosHeaderPopulateQuotaInfo                  string = "x-ms-documentdb-populatequotainfo"
 	cosmosHeaderPreTriggerInclude                  string = "x-ms-documentdb-pre-trigger-include"
 	cosmosHeaderPostTriggerInclude                 string = "x-ms-documentdb-post-trigger-include"
@@ -40,6 +41,42 @@ const (
 	headerIfMatch                                  string = "If-Match"
 	headerIfNoneMatch                              string = "If-None-Match"
 	headerXmsVersion                               string = "x-ms-version"
+	headerContentLocation                          string = "content-location"
+	headerXmsGatewayVersion                        string = "x-ms-gatewayversion"
+	headerLsn                                      string = "lsn"
+	headerXmsCosmosLlsn                            string = "x-ms-cosmos-llsn"
+	headerXmsCosmosItemLlsn                        string = "x-ms-cosmos-item-llsn"
+	headerXmsItemLsn                               string = "x-ms-item-lsn"
+	headerXmsCosmosQuorumAckedLlsn                 string = "x-ms-cosmos-quorum-acked-llsn"
+	headerXmsCurrentReplicaSetSize                 string = "x-ms-current-replica-set-size"
+	headerXmsCurrentWriteQuorum                    string = "x-ms-current-write-quorum"
+	headerXmsGlobalCommittedLsn                    string = "x-ms-global-committed-lsn"
+	headerXmsLastStateChangeUtc                    string = "x-ms-last-state-change-utc"
+	headerXmsNumberOfReadRegions                   string = "x-ms-number-of-read-regions"
+	headerXmsQuorumAckedLsn                        string = "x-ms-quorum-acked-lsn"
+	headerXmsRequestDurationMs                     string = "x-ms-request-duration-ms"
+	headerXmsResourceQuota                         string = "x-ms-resource-quota"
+	headerXmsResourceUsage                         string = "x-ms-resource-usage"
+	headerXmsSchemaVersion                         string = "x-ms-schemaversion"
+	headerXmsServiceVersion                        string = "x-ms-serviceversion"
+	headerXmsTransportRequestId                    string = "x-ms-transport-request-id"
+	headerXmsXpRole                                string = "x-ms-xp-role"
+	headerCollectionPartitionIndex                 string = "collection-partition-index"
+	headerCollectionServiceIndex                   string = "collection-service-index"
+	headerXmsDocumentDbPartitionKeyRangeId         string = "x-ms-documentdb-partitionkeyrangeid"
+	cosmosHeaderPhysicalPartitionId                string = "x-ms-cosmos-physical-partition-id"
+	headerStrictTransportSecurity                  string = "strict-transport-security"
+	headerXmsDatabaseAccountConsumedMb             string = "x-ms-databaseaccount-consumed-mb"
+	headerXmsDatabaseAccountProvisionedMb          string = "x-ms-databaseaccount-provisioned-mb"
+	headerXmsDatabaseAccountReservedMb             string = "x-ms-databaseaccount-reserved-mb"
+	headerXmsMaxMediaStorageUsageMb                string = "x-ms-max-media-storage-usage-mb"
+	headerXmsMediaStorageUsageMb                   string = "x-ms-media-storage-usage-mb"
+	headerXmsContentPath                           string = "x-ms-content-path"
+	headerXmsAltContentPath                        string = "x-ms-alt-content-path"
+	cosmosHeaderMaxContentLength                   string = "x-ms-cosmos-max-content-length"
+	cosmosHeaderIsPartitionKeyDeletePending        string = "x-ms-cosmos-is-partition-key-delete-pending"
+	cosmosHeaderQueryExecutionInfo                 string = "x-ms-cosmos-query-execution-info"
+	headerXmsItemCount                             string = "x-ms-item-count"
 )
 
 const (

sdk/data/azcosmos/cosmos_headers.go

@@ -56,7 +56,7 @@ func (c cosmosOffers) ReadThroughputIfExists(
 	if len(theOffers.Offers) == 0 {
 		azResponse.StatusCode = http.StatusNotFound
 		azResponse.Header.Add(cosmosHeaderRequestCharge, fmt.Sprint(queryRequestCharge))
-		return ThroughputResponse{}, newCosmosError(azResponse)
+		return ThroughputResponse{}, azruntime.NewResponseErrorWithErrorCode(azResponse, azResponse.Status)
 	}
 
 	// Now read the individual offer

sdk/data/azcosmos/cosmos_offers.go

@@ -4,7 +4,7 @@ go 1.18
 
 require (
 	github.com/Azure/azure-sdk-for-go v68.0.0+incompatible
-	github.com/Azure/azure-sdk-for-go/sdk/azcore v1.9.2
+	github.com/Azure/azure-sdk-for-go/sdk/azcore v1.10.0
 	github.com/Azure/azure-sdk-for-go/sdk/azidentity v1.0.0
 	github.com/Azure/azure-sdk-for-go/sdk/internal v1.5.2
 	github.com/stretchr/testify v1.8.4

sdk/data/azcosmos/go.mod

@@ -1,7 +1,7 @@
 github.com/Azure/azure-sdk-for-go v68.0.0+incompatible h1:fcYLmCpyNYRnvJbPerq7U0hS+6+I79yEDJBqVNcqUzU=
 github.com/Azure/azure-sdk-for-go v68.0.0+incompatible/go.mod h1:9XXNKU+eRnpl9moKnB4QOLf1HestfXbmab5FXxiDBjc=
-github.com/Azure/azure-sdk-for-go/sdk/azcore v1.9.2 h1:c4k2FIYIh4xtwqrQwV0Ct1v5+ehlNXj5NI/MWVsiTkQ=
-github.com/Azure/azure-sdk-for-go/sdk/azcore v1.9.2/go.mod h1:5FDJtLEO/GxwNgUxbwrY3LP0pEoThTQJtk2oysdXHxM=
+github.com/Azure/azure-sdk-for-go/sdk/azcore v1.10.0 h1:n1DH8TPV4qqPTje2RcUBYwtrTWlabVp4n46+74X2pn4=
+github.com/Azure/azure-sdk-for-go/sdk/azcore v1.10.0/go.mod h1:HDcZnuGbiyppErN6lB+idp4CKhjbc8gwjto6OPpyggM=
 github.com/Azure/azure-sdk-for-go/sdk/azidentity v1.0.0 h1:Yoicul8bnVdQrhDMTHxdEckRGX01XvwXDHUT9zYZ3k0=
 github.com/Azure/azure-sdk-for-go/sdk/azidentity v1.0.0/go.mod h1:+6sju8gk8FRmSajX3Oz4G5Gm7P+mbqE9FVaXXFYTkCM=
 github.com/Azure/azure-sdk-for-go/sdk/internal v1.5.2 h1:LqbJ/WzJUwBf8UiaSzgX7aMclParm9/5Vgp+TY51uBQ=