diff --git a/.changes/unreleased/added-20250206-133034.yaml b/.changes/unreleased/added-20250206-133034.yaml new file mode 100644 index 00000000..bbec7b8b --- /dev/null +++ b/.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" diff --git a/.vscode/launch.json b/.vscode/launch.json index ea7e1434..5aa4e4ab 100644 --- a/.vscode/launch.json +++ b/.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" diff --git a/.vscode/settings.json b/.vscode/settings.json index a89fa725..f38c7cb0 100644 --- a/.vscode/settings.json +++ b/.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": [ diff --git a/docs/guides/troubleshooting.md b/docs/guides/troubleshooting.md index 610152a3..f378e259 100644 --- a/docs/guides/troubleshooting.md +++ b/docs/guides/troubleshooting.md @@ -15,7 +15,7 @@ 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. @@ -23,12 +23,38 @@ By default, logs are sent to `stderr`. To send logs to a file, set the `TF_LOG_P 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` diff --git a/go.mod b/go.mod index 0f1bbecc..aeb26f91 100644 --- a/go.mod +++ b/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 diff --git a/internal/provider/client/logging.go b/internal/provider/client/logging.go new file mode 100644 index 00000000..baf64ace --- /dev/null +++ b/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 +} diff --git a/internal/provider/provider.go b/internal/provider/provider.go index ec5193cd..9f3b8bb1 100644 --- a/internal/provider/provider.go +++ b/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 } diff --git a/templates/guides/troubleshooting.md b/templates/guides/troubleshooting.md index 610152a3..f378e259 100644 --- a/templates/guides/troubleshooting.md +++ b/templates/guides/troubleshooting.md @@ -15,7 +15,7 @@ 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. @@ -23,12 +23,38 @@ By default, logs are sent to `stderr`. To send logs to a file, set the `TF_LOG_P 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`