Understanding Service Logs
Overview
In this
In Services Administration, you'll define which services integrate with your application. You can also choose to log your API's request and response bodies. This information is beneficial when you're troubleshooting failed calls. When a call fails, Service Logs can show you exactly why that call failed. First, let's set up Service Logs for external APIs and remote execute calls. Then, let's talk about how to return those Service Logs.
What You'll Learn
In this article, you'll learn how to:
Setting up Service Logs for External APIs
You'll use Services Administration to set up APIs you want to log in Unqork's Service Logs. By capturing request and response bodies, you'll have the right information to troubleshoot any failed call.
You'll set up logging preferences under the Logging section of Services Administration. Below, you'll see what these settings mean and how to use them.
|
Setting |
Description |
|---|---|
|
Capture Request & Response Bodies |
Selecting this checkbox sets that a service records the details (bodies) of the call's request and response. If you have a failed API call, the log's request and response body gives you information on why the call failed. It can also help if an API request was successful, but the data sent wasn't handled correctly. So, the request and response body shows you the details of your call. By default, this checkbox is unchecked. We recommend turning this option ON (checked) for every external service. |
|
Retention Days |
Defines how long to keep Service Logs. If left blank, Unqork stores the Service Logs for 30 days. |
|
Pagerduty Service Key |
When configured, PagerDuty sends alerts if there are errors in your Unqork application. To use the PagerDuty integration, you must have your own PagerDuty account. To set this up, you can visit this link and create an account: https://www.pagerduty.com. For the purpose of this |
Once you set your logging settings, you're good to go. The Service Logs automatically save to Unqork's database so you can query the logs at any time. We'll show you how to access these longs in a bit. First, let's set up Service Logs for remote execute calls.
Setting up Service Logs for Remote Executes
You can also set up Service Logs to capture the details of your remote execute calls. Remote executes are when a module executes on Unqork's server. You have some flexibility with what you capture in these logs. Capturing the request and response bodies of your calls makes future troubleshooting easier. You'll set up the request and response body log through Environment Administration.
Let's look at the options for the Server Side Execution Request/Response Body Log drop-down in Environment Administration.
|
Setting |
Description |
|---|---|
|
Do Not Capture Request/Response Bodies |
Logs won't show the details (request and response body) of remote execute calls. |
|
Capture Request/Response Bodies on Failure |
Unqork only logs request and response bodies if a remote execute fails. |
|
Capture All Request/Response Bodies |
Unqork logs request and response bodies for all remote executes. |
We recommend choosing Capture all request/response bodies. Even if a call is successful, the data to and from may be incorrect. Having access to the request and response bodies for all calls gives you the information you need to troubleshoot any call.
You can also set up PagerDuty alerts from Environment Administration. When configured, PagerDuty sends alerts when there are errors in your Unqork application. To use the PagerDuty integration, you must have your own PagerDuty account. Again, you can visit this link to set up an account: https://www.pagerduty.com.
Now that you have Service Logs saving to the database for your remote executes, let's go over how to find the Service Logs.
Checking Service Logs Using an API Call
Now, let's check the Service Logs to see the status of external API calls and remote execute calls.
We recommend installing a Chrome extension that formats JSON. Without a JSON formatting extension, Service Logs return as long lines of text. Using a Chrome extension organizes the Service Logs in a user-friendly way.
The Service Logs look something like this:
The table below gives a description of each response item you'll see in the Service Logs.
|
Response Item |
Description |
|---|---|
|
id |
A unique identifier the Service Log returns. |
|
type |
Could be service or remoteExecute.
|
|
submissionId |
A basic identifier for each submission made. Your end-user creates a new submission any time they save or submit their module. |
|
moduleId |
This ID refers to the executed module. In the case of a remote execute, the ID refers to the executed module. If you're logging a service, this ID indicates the module that made the API call. |
|
componentKey |
Shows the Property Name of the component that made the external API call. With remote executes, components aren't traced. |
|
requestTime |
Shows the date and time when you made the request to the remote execute or external service. requestTime and responseTime are useful because you can filter your search to a specific time. |
|
responseTime |
Shows the date and time when the module finishes executing and sends a response, or when the external API finishes executing and sends a response. requestTime and responseTime are useful because you can filter your search to a specific time. |
|
serviceName |
The name of the service you added in Services Administration. |
|
userId |
The user ID of the person or integration job that submitted the request. Filtering your search by user ID can help you find out what went wrong for a specific user. |
|
url |
The URL of the request made. |
|
responseCode |
HTTP response status codes. The codes you'll see in Unqork are:
For example, you can query by responseCode >= 400. This search returns Service Logs for failed calls. |
|
responseText |
Text with a basic description of the responseCode. You won't get an actual response code. Some examples you might see include "Bad Request", "Not Found," or "OK". |
|
requestBody |
The details of the API call or the remote execute request. There will only be a requestBody with a POST or a PUT-type call. |
|
responseBody |
The call details returned. Depending on the API call, you may or may not see a responseBody. |
|
expireAt |
Shows the date and time when the record will drop off the log. The default is 30 days. You can change this setting by going to Services Administration and updating the Retention Days setting. |
|
created |
Shows the date and time when Unqork created the log record. |
|
modified |
Shows the date and time of a log's modification. |
Viewing Service Logs Through Chrome
To get back Service Logs, you'll use the following endpoint:
| 1. | Enter https://{your-environment}.unqork.io/fbu/uapi/logs/services in your Chrome address bar. |
Replace {your-environment} with your actual environment name.
| 2. | Press Enter or Return. |
Bringing Service Logs Directly into a Module
You can also bring Service Logs into a module using a Plug-In component:
| 1. | Select Get Service Logs from the Internal Services drop-down. |
The Data Source URL automatically populates with /fbu/uapi/logs/services. You can see this highlighted in the image below.
| 2. | Click Save. |
Searching and Filtering Service Logs
Because Service Logs store all API calls made at Unqork, finding yours can be difficult. Thankfully, built-in filtering operators let you customize your search. Maybe you only want to query failed calls or find calls made during a certain timeframe. Or, maybe you want to narrow your Service Logs down to remote executes only. The query string can specify the service name, filter conditions, and sorting.
For example, to return Service Logs for a certain service, you'll enter the following API call into your browser: https://{your-environment}.unqork.io/fbu/uapi/logs/services?serviceName={serviceName}. Then, you’ll see the response for the service you queried.
To view your filtering options, go to the following link and scroll to the Filtering operator's table: https://github.com/loris/api-query-params.
