Troubleshooting¶
If you encounter issues while using the SDK, it is important to troubleshoot with the goal of identifying, analyzing, and resolving any unexpected issues or behaviors. You may encounter problems within the code, and the following two approaches can assist in debugging the problem:
- Debugging using the Logger
- Debugging using metrics
Debugging using the Logger¶
The SDK supports a file-based logging system, which can be further divided into multiple log levels, such as Informative, Error, and Debug.
- Informative: This is the default log level, which provides limited logs related to execution. Logging at this level records exception logs, but may not provide a complete stack trace.
- Error: The Error logs are more concise and are only created when there is an error.
- Debug: The Debug logs are currently the most verbose and provide enhanced diagnostic information to assist in troubleshooting when errors occur.
You can create an instance of logger by using “Autodesk.DataExchange.Extensions.Logging.File” and the steps for the same are as follows:
- Download and install the package
Autodesk.DataExchange.Extensions.Logging.File. - Create an instance of ILogger by passing the log directory path to the constructor as a string.
ILogger Logger = new Log(LogDirectoryPath);
- Set the Debug log level by calling the SetDebugLogLevel() method of the
Autodesk.DataExchange.Extensions.Logging.File.
Logger.SetDebugLogLevel();
- Enable HTTP logging by calling EnableHttpDebugLogging() on your client instance.
var client = new Client(sdkOptions);
client.EnableHttpDebugLogging();
EnableHttpDebugLogging is declared on the concrete Client class rather than on IClient. If your connector holds the client as IClient, cast it first:
(client as Client)?.EnableHttpDebugLogging();
The default logger of the SDK provides inbuilt Informative and Error logs, therefore there is no need to set informative or error log levels explicitly.
Debugging using metrics¶
The SDK provides access to the Insights.Metrics class, which enables you to measure various performance metrics of the code.
- You can enable the metrics by using the following method:
Insights.Metrics.EnableMetrics(true);
- To track the time taken for a particular activity you can make use of
StartTrackingandStopTrackingmethods.- In the following methods, the input parameter is the name of the activity against which the performance metrics can be calculated.
Insights.Metrics.StartTracking("CreateExchangeAsync").
Insights.Metrics.StopTracking("CreateExchangeAsync").
* Both methods also have one optional parameter `string uniqueid` which can be used to distinguish between two activities with the same name.
Insights.Metrics.StartTracking("CreateExchangeAsync", "q125g49t").
Insights.Metrics.StopTracking("CreateExchangeAsync", "q125g49t").
- To keep the numeric count of an activity, use the following method.
Insights.Metrics.CreateCounter(Id)
- To increment the numeric count of an activity, use the following method.
Insights.Metrics.IncrementCounter(Id)
- To get the data that has been tracked for different operations, use the following method.
Insights.Metrics.GetString();
- To clear all the data inside the metrics class, use the following method.
Insights.Metrics.ClearMetrics()
Resolving thread pool starvation¶
When you sync large models, the CPU-intensive geometry conversions that the SDK performs can starve the .NET thread pool of the threads it needs for I/O completion callbacks. This can surface as an error such as There were not enough free threads in the ThreadPool to complete the operation.
By default, the SDK guards against this. The GeometryConfiguration.TuneThreadPool property is true by default, which raises the process-wide thread pool minimums during client initialization so the pool creates threads eagerly rather than ramping up slowly. If you see this error, confirm that you have not set TuneThreadPool to false. Disabling it removes this safeguard. For details on the setting and when to opt out, see Tuning the thread pool.
Diagnosing a failed request in the Connector UI¶
When an HTTP request fails, the Connector UI shows the user a short generic message and keeps the diagnostic detail out of the interface. This is deliberate. Request diagnostics carry the authorization header, and anything on screen can be screenshotted and attached to a ticket or a chat message, so the interface is not a safe place to put them.
The detail is still captured. Sanitized diagnostics — the status code, the request with its authorization header removed, and the response body — are attached to the notification and recorded for analytics, so they stay available for support. When you investigate a reported failure, read the logs rather than asking the user what the message said: the message is the same for every HTTP failure and identifies nothing on its own.
For details on collecting logs, see Debugging using the Logger.
A load fails on an exchange that appears in the list¶
A 404 on load usually means the exchange no longer exists. An exchange can be removed after your connector retrieved the list, so a listing that looked valid a moment ago can point at something that has since been deleted. The user sees a failure with no indication that the exchange is gone.
Check validation status before you attempt a load rather than treating the list as authoritative. GetValidExchangesAsync returns each exchange with a ValidationStatus, where IsDeleted marks a 404 and IsUnauthorized marks a 403, so you can drop or disable those entries and tell the user what happened. See Handle exchange validation.
Understanding the OAuth consent screen¶
When the SDK opens the browser for sign-in, users see an APS authorization page that lists the permissions the app is requesting and asks them to approve. This is expected OAuth behavior.
The APS consent screen displays permission labels in platform terminology. The following table describes what each scope means in the context of the Data Exchange SDK:
| Scope | What it allows |
|---|---|
data:read |
Read project files, folders, and exchange data from your Forma account |
data:write |
Update exchange data and write file content to your Forma projects |
data:create |
Create new exchanges and upload files to your Forma projects |