feat(logging): enable api/sdk interaction logging (#237)

# 📥 Pull Request

## ❓ What are you trying to address

This pull request introduces logging enhancements for API/SDK
interactions and updates related documentation and configuration files.
The key changes include enabling detailed logging for API calls and
updating the troubleshooting guide.

## ✨ Description of new changes

### Logging Enhancements:

* Added a new logging subsystem for the Microsoft Fabric SDK to capture
detailed API interactions. (`internal/provider/client/logging.go`)
* Integrated the new logging subsystem into the provider client creation
process. (`internal/provider/provider.go`)

### Documentation Updates:

* Updated the troubleshooting guide to include instructions for enabling
low-level logging for API calls. (`docs/guides/troubleshooting.md`,
`templates/guides/troubleshooting.md`)

---------

Co-authored-by: Pablo Zaidenvoren <[email protected]>

.changes/unreleased/added-20250206-133034.yaml

@@ -0,0 +1,5 @@
+kind: added
+body: Enable API/SDK interaction logging.
+time: 2025-02-06T13:30:34.6324433+01:00
+custom:
+    Issue: "237"

.vscode/launch.json

@@ -8,7 +8,8 @@
       "mode": "debug",
       "program": "${workspaceFolder}",
       "env": {
-        "FABRIC_PREVIEW": "true"
+        "FABRIC_PREVIEW": "true",
+        "FABRIC_SDK_GO_LOGGING": "trace"
       },
       "args": [
         "-debug"

.vscode/settings.json

@@ -62,7 +62,8 @@
   "go.testEnvVars": {
     "TF_LOG": "ERROR",
     "TF_ACC": "1",
-    "FABRIC_PREVIEW": "true"
+    "FABRIC_PREVIEW": "true",
+    "FABRIC_SDK_GO_LOGGING": "trace"
   },
   "go.formatTool": "goimports",
   "go.formatFlags": [

docs/guides/troubleshooting.md

@@ -15,20 +15,46 @@ The guide provides troubleshooting steps for common issues that you might encoun
 
 ---
 
-## Logging
+## Terraform Logging
 
 The Microsoft Fabric Terraform Provider outputs logs that you can enable by setting the `TF_LOG` environment variable to `DEBUG` or any other log level that Terraform supports.
 
 By default, logs are sent to `stderr`. To send logs to a file, set the `TF_LOG_PATH` environment variable to the target file path.
 
 For example, you can run the following command to enable logging at the debug level, and to output logs in monochrome format to a file named `tf.log` relative to the current working directory, while the `terraform apply` command runs:
 
-```bash
+```sh
+# sh
 TF_LOG=DEBUG TF_LOG_PATH=tf.log terraform apply -no-color
 ```
 
+```powershell
+# PowerShell
+$env:TF_LOG="DEBUG"
+$env:TF_LOG_PATH="tf.log"
+terraform apply -no-color
+```
+
 For more information about Terraform logging, see [Debugging Terraform](https://developer.hashicorp.com/terraform/internals/debugging).
 
+## Fabric API logging
+
+Low-level logging is possible which will handle API calls. This type of logging can be very useful for debugging issues related to API interactions. By setting the logging level to `TRACE`, you can capture detailed information about the API calls made by Terraform. This includes request and response details, which can help in diagnosing problems or understanding the behavior of the API.
+
+To enable low-level logging for API calls, you need to setup environment variables `TF_LOG` and `FABRIC_SDK_GO_LOGGING` with `TRACE` value.
+
+```sh
+# sh
+TF_LOG=TRACE FABRIC_SDK_GO_LOGGING=TRACE terraform apply -no-color
+```
+
+```powershell
+# PowerShell
+$env:TF_LOG="TRACE"
+$env:FABRIC_SDK_GO_LOGGING="TRACE"
+terraform apply -no-color
+```
+
 ## FAQ
 
 ### I am getting error `The feature is not available`

go.mod

@@ -8,6 +8,7 @@ require (
 	github.com/dcarbone/terraform-plugin-framework-utils/v3 v3.8.0
 	github.com/go-sprout/sprout v1.0.0
 	github.com/google/go-cmp v0.6.0
+	github.com/hashicorp/go-hclog v1.6.3
 	github.com/hashicorp/go-uuid v1.0.3
 	github.com/hashicorp/terraform-plugin-framework v1.13.0
 	github.com/hashicorp/terraform-plugin-framework-jsontypes v0.2.0
@@ -43,7 +44,6 @@ require (
 	github.com/hashicorp/go-checkpoint v0.5.0 // indirect
 	github.com/hashicorp/go-cleanhttp v0.5.2 // indirect
 	github.com/hashicorp/go-cty v1.4.1-0.20200414143053-d3edf31b6320 // indirect
-	github.com/hashicorp/go-hclog v1.6.3 // indirect
 	github.com/hashicorp/go-multierror v1.1.1 // indirect
 	github.com/hashicorp/go-plugin v1.6.2 // indirect
 	github.com/hashicorp/go-retryablehttp v0.7.7 // indirect

internal/provider/client/logging.go

@@ -0,0 +1,38 @@
+// Copyright (c) Microsoft Corporation
+// SPDX-License-Identifier: MPL-2.0
+
+package client
+
+import (
+	"context"
+	"os"
+
+	"github.com/hashicorp/go-hclog"
+	"github.com/hashicorp/terraform-plugin-log/tflog"
+)
+
+const (
+	FabricSDKLoggerName   = "fabric-sdk-go"
+	AzureSDKLoggingEnvVar = "AZURE_SDK_GO_LOGGING"
+	AzureSDKLoggingAll    = "all"
+)
+
+func NewFabricSDKLoggerSubsystem(ctx context.Context) (context.Context, hclog.Level, error) {
+	targetLevel := hclog.LevelFromString(os.Getenv("FABRIC_SDK_GO_LOGGING"))
+
+	// If the level is not set, or is set to "off", disable logging
+	if targetLevel == hclog.NoLevel {
+		targetLevel = hclog.Off
+	} else {
+		// Enable azcore logging
+		err := os.Setenv(AzureSDKLoggingEnvVar, AzureSDKLoggingAll)
+		if err != nil {
+			return ctx, targetLevel, err
+		}
+	}
+
+	ctx = tflog.NewSubsystem(ctx, FabricSDKLoggerName, tflog.WithLevel(targetLevel))
+	ctx = tflog.SubsystemMaskFieldValuesWithFieldKeys(ctx, FabricSDKLoggerName, "Authorization")
+
+	return ctx, targetLevel, nil
+}

internal/provider/provider.go

@@ -6,12 +6,15 @@ package provider
 import (
 	"context"
 	"math"
+	"os"
 	"strconv"
 	"strings"
 	"time"
 
 	"github.com/Azure/azure-sdk-for-go/sdk/azcore/cloud"
+	azlog "github.com/Azure/azure-sdk-for-go/sdk/azcore/log"
 	"github.com/Azure/azure-sdk-for-go/sdk/azcore/policy"
+	"github.com/hashicorp/go-hclog"
 	"github.com/hashicorp/terraform-plugin-framework-timetypes/timetypes"
 	"github.com/hashicorp/terraform-plugin-framework-validators/listvalidator"
 	"github.com/hashicorp/terraform-plugin-framework-validators/stringvalidator"
@@ -104,7 +107,7 @@ func NewFunc(version string) func() provider.Provider {
 func createDefaultClient(ctx context.Context, cfg *pconfig.ProviderConfig) (*fabric.Client, error) {
 	resp, err := auth.NewCredential(*cfg.Auth)
 	if err != nil {
-		tflog.Error(ctx, "Failed to initialize authentication", map[string]any{"error": err})
+		tflog.Error(ctx, "Failed to initialize authentication", map[string]any{"error": err.Error()})
 
 		return nil, err
 	}
@@ -126,9 +129,25 @@ func createDefaultClient(ctx context.Context, cfg *pconfig.ProviderConfig) (*fab
 	// A value less than zero means there is no cap.
 	fabricClientOpt.Retry.MaxRetryDelay = -1
 
+	ctx, lvl, err := pclient.NewFabricSDKLoggerSubsystem(ctx)
+	if err != nil {
+		tflog.Error(ctx, "Failed to initialize Microsoft Fabric SDK logger subsystem", map[string]any{"error": err.Error()})
+
+		return nil, err
+	}
+
+	if cls := os.Getenv(pclient.AzureSDKLoggingEnvVar); cls == pclient.AzureSDKLoggingAll && lvl != hclog.Off {
+		azlog.SetListener(func(ev azlog.Event, msg string) {
+			tflog.SubsystemTrace(ctx, pclient.FabricSDKLoggerName, "SDK", map[string]any{
+				"event":   ev,
+				"message": msg,
+			})
+		})
+	}
+
 	client, err := fabric.NewClient(resp.Cred, &cfg.Endpoint, fabricClientOpt)
 	if err != nil {
-		tflog.Error(ctx, "Failed to initialize Microsoft Fabric client", map[string]any{"error": err})
+		tflog.Error(ctx, "Failed to initialize Microsoft Fabric client", map[string]any{"error": err.Error()})
 
 		return nil, err
 	}

templates/guides/troubleshooting.md

@@ -15,20 +15,46 @@ The guide provides troubleshooting steps for common issues that you might encoun
 
 ---
 
-## Logging
+## Terraform Logging
 
 The Microsoft Fabric Terraform Provider outputs logs that you can enable by setting the `TF_LOG` environment variable to `DEBUG` or any other log level that Terraform supports.
 
 By default, logs are sent to `stderr`. To send logs to a file, set the `TF_LOG_PATH` environment variable to the target file path.
 
 For example, you can run the following command to enable logging at the debug level, and to output logs in monochrome format to a file named `tf.log` relative to the current working directory, while the `terraform apply` command runs:
 
-```bash
+```sh
+# sh
 TF_LOG=DEBUG TF_LOG_PATH=tf.log terraform apply -no-color
 ```
 
+```powershell
+# PowerShell
+$env:TF_LOG="DEBUG"
+$env:TF_LOG_PATH="tf.log"
+terraform apply -no-color
+```
+
 For more information about Terraform logging, see [Debugging Terraform](https://developer.hashicorp.com/terraform/internals/debugging).
 
+## Fabric API logging
+
+Low-level logging is possible which will handle API calls. This type of logging can be very useful for debugging issues related to API interactions. By setting the logging level to `TRACE`, you can capture detailed information about the API calls made by Terraform. This includes request and response details, which can help in diagnosing problems or understanding the behavior of the API.
+
+To enable low-level logging for API calls, you need to setup environment variables `TF_LOG` and `FABRIC_SDK_GO_LOGGING` with `TRACE` value.
+
+```sh
+# sh
+TF_LOG=TRACE FABRIC_SDK_GO_LOGGING=TRACE terraform apply -no-color
+```
+
+```powershell
+# PowerShell
+$env:TF_LOG="TRACE"
+$env:FABRIC_SDK_GO_LOGGING="TRACE"
+terraform apply -no-color
+```
+
 ## FAQ
 
 ### I am getting error `The feature is not available`