Understanding Service Logs

Overview

In this article, you'll learn how to read Unqork Service Logs. And, you'll learn how to use the service logs API (application programming interface) call. The Service Logs collect all the API calls made at Unqork. Here, you'll find the information on API calls made to internal and external services.

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:

• Set up Service Logs for external APIs.

• Set up Service Logs for remote executes.

• Check Service Logs using an API call.

• Searching and filtering Service Logs.

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. NOTE  For the purpose of this lesson, you'll leave the PagerDuty service key field empty.

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.

NOTE  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.

NOTE  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. service: Refers to any external APIs that you set up in Services Administration. remoteExecute: Refers to any module that you execute server-side.
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: 200-299: Successful - response received, understood, and accepted. 300-399: Redirection - more action needed to complete the request. 400+: Client or server error - the request can't be fulfilled. 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.

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.

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.