From the Trenches: How to use API logs
A common approach to troubleshooting errors that occur when using the DocuSign eSignature platform is to capture API logs. API logs provide a standard format of data to show to what resource you made the request, the payload of your request, and what response DocuSign returns. Having this data will help you understand what is going wrong with your API requests and how to resolve them when errors do occur. In this post I’ll describe how to capture API logs, how to understand the folder you download containing all the logs, and how to make sense of the specific API logs inside the folder.
Capturing the API Log
To capture an API log requires you to log in to the user account that is making the API request. API logs don’t capture data on all users in an account. Instead, they run on a specific user of your choice.
The first step to capture an API log is to identify the user who is making the API request. Once the user is identified, perform the following steps:
- Log in to the DocuSign account of the user for whom you want to capture logs.
- Select the users icon in the top right of the page and select My Preferences.
- Select Enable Logging and then select Save.
- Reproduce the error while logs are running.
- Refresh the page on which you enabled the logs and select Download, which will download the logs to a folder on your computer. See API Request Logging on DocuSign Support for a step-by-step example with visuals.
A more advanced approach to capturing API logs would be to enable and download them via the API. This can be beneficial if you are wanting to avoid the extra logs that are downloaded when capturing logs using the web console described in more detail below. See the RequestLogs Resource in the eSignature REST API Reference for more details.
Making sense of the folder of logs
Once you have downloaded the logs, you will want to unzip the folder to a destination of your choice. A common folder of logs will look like the following:
The logs are generated in such a way that the first request captured is shown at the bottom of the folder. In other words, if you read the files from the top down, you are viewing the most recent requests first, and going down the list of files sequentially shows you the older requests that were made.
Each file has a similar format:
[number]-[status]-[resource].
The status identifies the status of the request: for example, “NotFound”, “OK”, “Created” or “BadRequest”.
The resource identifies the resource being accessed: for example, the endpoint to create an envelope (CreateAndSendEnvelope) or the endpoint used to get templates in an account (RequestTemplates).
You will have many different files inside the folder that might not seem relevant at first glance. The reason for this is that when you refresh any page in DocuSign, API logs are generated. Additionally, when you navigate around the DocuSign web console, logs are also generated. These log files are normal, but if you are trying to capture a request specifically made by your custom application via the API, the logs generated by the DocuSign web console won’t be related to your custom API requests.
An example of this behavior is shown in the first file in the above image. Notice the first log is titled NotFound_GetUserProfileImage.txt. This is an example of a log that was generated but not relevant to an actual problem. When you refresh the page and you don’t have a profile image, the GET request that DocuSign makes for that profile image returns the error that the profile image was not found.
Similarly, simply refreshing the page in the web console loads multiple resources needed for the DocuSign user interface to function and will generate API logs.
How to find the relevant request in the folder of logs
The folder of logs can contain at most 50 files, so you might need to sift through the files depending on the size of the folder.
If, for example, you are using a custom-built application and are getting an error “ENVELOPE_IS_INCOMPLETE”, the log you would want to look for would contain “BadRequest_CreateAndSendEnvelope”. The API request being made and the status of the request will drive what the name of the log is. A common approach to finding the correct log would be to look for logs with “BadRequest” in the name if you are specifically looking for logs that resulted in an error.
Understanding a specific API log
The structure of an API log is the same across different API requests. The main differences you will encounter is a different request body in JSON format.
The metadata and header portion of the log is valuable, as it shows a timestamp of the request along with the actual request being made. For example, you might see something like:
POST https://demo.docusign.net:7801/restapi/v2.1/accounts/12345678/envelopes/
Which aligns with this REST endpoint
Or
GET https://demo.docusign.net:7802/restapi/v2.1/accounts/12345678/templates/64a3e862-xxxx-xxxx-xxxx-xxxxxxxxxx
Which aligns with this REST endpoint
These requests will match up with the specific structure of a REST resource found on our REST API Reference.
Comparing the structure to the request might help to identify if you are potentially missing a parameter or what specifications these requests require.
The request body is required for most POST requests. The body can be valuable, as it can help illustrate what is wrong when used in combination with the actual error. For example, if you generate an embedded recipient view via your custom application but don’t get a URL returned back, you could generate API logs and use the body and status included in the log to help resolve the issue.
The body of the request in the logs will be in JSON format and will display exactly what your third-party tool, SDK, or direct API request is sending to DocuSign. For example, the following is a body of an embedded recipient view request shown in a log:
{
"returnUrl": "http://httpbin.org/get",
"authenticationMethod": "none",
"email": "SampleEmail@gmail.com",
"userName": "Bob SmithX",
"clientUserID":"123",
"roleName": "Client"
}
The error thrown in this specific example contains a clear identifier to the problem:
400 BadRequest
Content-Type: application/json; charset=utf-8
Content-Length: 140
X-DocuSign-TraceToken: 54e65713-xxxx-xxxx-xxxx-2fa2e22352a0
{"errorCode":"UNKNOWN_ENVELOPE_RECIPIENT","message":"The recipient you have identified is not a valid recipient of the specified envelope."}
With this information you can infer that the issue has to do with an incorrect recipient being provided to DocuSign in the API request.
This specific problem would be resolved by ensuring that the recipient you provided exactly matches up with the recipient on the envelope. In this example I purposefully added an “X” to the recipient name in the API request, which caused the name being passed into the API to not align with the name on the envelope, causing the error above.
Troubleshooting log capture
Here are some common problems with capturing logs and how to address them:
- If you are trying to debug authentication errors, API logs will not be generated at all. The reason for this is that API logs are captured for specific users. If you aren’t yet authenticated, then the API requests aren’t being made by any specific user. A better approach would be to use a tool like Wireshark or Fiddler to capture the network logs and review the exact HTTP request being made for authentication issues.
- If you enable logs and reproduce a problem, but the logs don’t appear in the folder, you are likely not logged in as the correct user. To resolve this issue, review your code that is making the API request and find the user ID of the user making the request. You must make sure the user ID is the same ID of the user you are enabling logs for.
- When using a third-party tool and trying to capture logs for that third-party tool, you need to reach out to the third-party provider for input on how the tool was configured and what user is making the API requests.
- API logging is limited to the eSignature APIs; DocuSign Admin, Rooms, CLM, and other APIs will not be captured.
- When logging calls made against the eSignature SOAP API, only the call body is captured; the response from DocuSign will be omitted.
