Log files and Troubleshooting Adapters

In this training module you will learn about troubleshooting the RET Adapters and investigating errors through the analysis of Adapter logs.

Download the presentations for this course.

More information on logging can be found in the online developer documentation: RET adapter log files.

Objectives

You will learn about using adapter log files to investigate RET Adapter issues, where you will:

Understand where log files are stored, and how to access them for all the components in your environment: Liberator, Transformer and each of the RET Adapters
Understand how logs are configured, and learn about the various log files that exist and their purposes
Use a systematic approach to analyse a set of log files, and use the analysis to resolve Adapter issues

Accessing the log files

Liberator and Transformer logs

First find your Deployment Framework root directory:

The log files for Liberator can be found in <DeploymentFramework>/servers/Liberator/var
The log files for Transformer can be found in <DeploymentFramework>/servers/Transformer/var

RET Adapter Logs

First find your Deployment Framework root directory. The logs for the RET Adapters can be found in <DeploymentFramework>/active_blades/<Adapter>/Blade/DataSource/var.

The Caplin RET Adapter Toolkit uses the Apache logging library Log4J. Each RET Adapter contains a log4j.xml under RetAdapter/Blade/Datasource/etc/. If you want to know more about configuring log files using Log4J, see How can I… Troubleshoot my RET Adapter.

By default, logs are configured for each adapter with the log level INFO which is used to display the majority of logging information for each Adapter.

Analysing log files

The <AdapterName>-adapter.log file is a good example for log analysis as it contains most of the package names from different sources. It can contain logs for the following package names:

Package Name Description

Package Name	Description
com.caplin.example.ret	Customers specific logs. As each RET Adapter contains at least one class that does not belong to the RET adapter toolkit, it can contain customer specific log lines. An example from our `CalendarAdapterExample`, log lines would contain the following package name.
com.caplin.motif.fx.ret	RETAdapterToolkit logs can be identified by this package name.
com.caplin.ret.trapi	RETIntegrationAPI layer logs can be identified by this package name.
com.m_systems.trapi	RET API specific logs from Refinitiv trapi-lib library
admin.api.AdminAPI	RET AdminAPI logs
com.caplin.datasource	Caplin Platform specific

com.caplin.example.ret

Customers specific logs. As each RET Adapter contains at least one class that does not belong to the RET adapter toolkit, it can contain customer specific log lines. An example from our CalendarAdapterExample, log lines would contain the following package name.

com.caplin.motif.fx.ret

RETAdapterToolkit logs can be identified by this package name.

com.caplin.ret.trapi

RETIntegrationAPI layer logs can be identified by this package name.

com.m_systems.trapi

RET API specific logs from Refinitiv trapi-lib library

admin.api.AdminAPI

RET AdminAPI logs

com.caplin.datasource

Caplin Platform specific

Creating an exception

We will now use log analysis to solve an adapter issue. You will enable Refinitiv logging and then simulate some possible connection issues. You will then look at ways of resolving the connection issues using a systematic approach.

Refinitiv log files

The ret.log is a RET API specific log that is switched off by default. To enable the ret.logs of the FxTradingAdapters go to global-config/overrides/FxTradingAdapters/etc/trapi-connection.properties and add the following line:

ret_log_enabled=true

As you have now made adapter configuration changes you will need to restart the FxTradingAdapters to reload it and update your environment with the new adapter config. Do this by opening a Cygwin console on your machine and navigate to your Deployment Framework’s topmost directory. Then execute the following command:

./dfw start FxTradingAdapters

Now look inside your log file folder under <DeploymentFramework>/kits/FxTradingAdapter/Latest/DataSource/var - you should now find a new file ret.log for a Refinitiv proxy connection.

The ret.log file is required by RET support in order to investigate any issues with their RET-AD system. Exceptions thrown by Refinitiv APIs — trapi-lib, rates-plugin, admin, lbn — are usually cached within the RET Adapter Toolkit (with the package name: com.caplin.ret.trapi) where they are also logged as well as handled.

You are usually able to view the version number of a library (e.g. trapi-lib-3.5.126.jar) that might be needed as information for investigations.

Analysing the logs

Using what you learnt above about RET log files, we are now going to simulate a connection issue and use log analysis to resolve it. The steps covered below are based on the Caplin Troubleshooting Checklist that can be used as a systematic approach to resolving adapter issues.

Follow the steps below:

Create an error by renaming the licence file <DeploymentFramework>/global_config/overrides/FxTradingAdapters/etc/trapi.lic to trapi.lic.bak
Restart the FX Trading Adapter by running the command below from the root directory of your Deployment Framework:
```
./dfw start FxTradingAdapter
```
Check the Liberator status page to check the status of the adapter. Do this by navigating to http://localhost:18080/status. The status indicator for the FxTradingAdapter should now be RED.
Before you begin investigating, launch the Caplin FX Professional web application and take a look at what the app looks like. You will find that any trade tiles are greyed out, and that if you attempt a trade an error message "Trading Not Available" is displayed. You should however still be able to carry out an Order trade (as we know that the RET Order Adapter is working). Therefore we assume that the issue is related to the Trading Adapter.
Enable the client.log of Caplin FX Professional web application by appending &debug=finer to the end of the web app URL. You should then see the following for the /PRIVATE/TRADE/FX subject.
```
In - ActionFailEvent [subject=/PRIVATE/TRADE/FX]
```
Now you can begin checking the adapter logs. Start with the javaAdapterName.log, which is a Java standard output log, to see if the adapter has crashed or not. If you cannot find that file or see anything particularly unusual here, move on to the next step.

Next, check the fxtrading-adapter.log. In this log file you should be able to view an exception thrown by trapi-lib (com.m_systems.trapi.lib.TradingEngine):

2015 Apr 17 14:11:57.788 +0100  -  [caplin.ParallelExecutor-<thread:0>] ERROR com.caplin.ret.trapi.connection.MarketOrderConnection - An error occurred in connecting for proxy user <dev_js_fx_proxy_1>, host<webserver>, port<8912>, connection label <TradingConnection1> no client
com.m_systems.trapi.lib.TradingException: Licence error - Host not licenced
        at com.m_systems.trapi.lib.TrAPI_ae.d(Unknown Source) ~[trapi-lib-3.5.126.jar:?] (1)
        at com.m_systems.trapi.lib.TrAPI_ae.c(Unknown Source) ~[trapi-lib-3.5.126.jar:?]
        at com.m_systems.trapi.lib.TrAPI_w.a(Unknown Source) ~[trapi-lib-3.5.126.jar:?]
        at com.m_systems.trapi.lib.TrAPI_w.c(Unknown Source) ~[trapi-lib-3.5.126.jar:?]
        at com.m_systems.trapi.lib.TradingEngine.Connect(Unknown Source) ~[trapi-lib-3.5.126.jar:?]
        at com.caplin.ret.trapi.fx.execution.impl.TrAPIMarketOrderTradingEngine.connect(TrAPIMarketOrderTradingEngine.java:55) ~[RETAdapterToolkit-3.5-2.2.0-3807-6e8c45d.jar:?] (2)
        at com.caplin.ret.trapi.connection.MarketOrderConnection.performConnection(MarketOrderConnection.java:54) [RETAdapterToolkit-3.5-2.2.0-3807-6e8c45d.jar:?]
        at com.caplin.ret.trapi.connection.ReconnectionManager.isConnectionSuccessful(ReconnectionManager.java:197) [RETAdapterToolkit-3.5-2.2.0-3807-6e8c45d.jar:?]
        at com.caplin.ret.trapi.connection.ReconnectionManager.isConnectionSuccessful(ReconnectionManager.java:179) [RETAdapterToolkit-3.5-2.2.0-3807-6e8c45d.jar:?]
        at com.caplin.ret.trapi.connection.ReconnectionManager.reconnect(ReconnectionManager.java:143) [RETAdapterToolkit-3.5-2.2.0-3807-6e8c45d.jar:?]
        at com.caplin.ret.trapi.connection.ReconnectionManager.handleReconnection(ReconnectionManager.java:106) [RETAdapterToolkit-3.5-2.2.0-3807-6e8c45d.jar:?]
        at com.caplin.ret.trapi.connection.ReconnectionManager.connect(ReconnectionManager.java:61) [RETAdapterToolkit-3.5-2.2.0-3807-6e8c45d.jar:?]
        at com.caplin.ret.trapi.connection.AbstractConnection.connect(AbstractConnection.java:52) [RETAdapterToolkit-3.5-2.2.0-3807-6e8c45d.jar:?]
        at com.caplin.motif.fx.ret.fxtrading.TradingConnectionManager$1.run(TradingConnectionManager.java:66) [RETAdapterToolkit-3.5-2.2.0-3807-6e8c45d.jar:?] (3)
        at java.util.concurrent.ThreadPoolExecutor.runWorker(ThreadPoolExecutor.java:1145) [?:1.7.0_55]
        at java.util.concurrent.ThreadPoolExecutor$Worker.run(ThreadPoolExecutor.java:615) [?:1.7.0_55]
        at java.lang.Thread.run(Thread.java:745) [?:1.7.0_55]

1	log lines starting with `com.m_systems.trapi` are thrown by `trapi-lib-3.5.126.jar`
2	log lines starting with `com.caplin.ret.trapi` are thrown by `RETAdapterToolkit-3.5-2.2.0-3807-6e8c45d.jar`
3	log lines starting with `com.caplin.motif.fx.ret` are thrown by `RETAdapterToolkit-3.5-2.2.0-3807-6e8c45d.jar` There’s a lot of useful information in this stack trace. Library names and versions are included, and the package names give you a hint as to whether the issue is related to the connection to RET (`com.caplin.ret.trapi`) or to the Caplin Platform (`com.caplin.motif.fx.ret`).

If you check the adapter’s ret.log file, you won’t find many messages logged as the connection to RET is unavailable:
```
17/04/15 13:15:24.829 GMT Trading API TrAPI-3.5.126.BD Started
```
You can also check the Liberator’s event.log file under <DeploymentFramework>/servers/Liberator/var/
As our error in the log file suggested, we have to check the configuration for our log file. Rename your licence file back to trapi.lic.
Run the command below from the root directory of your Deployment Framework to restart the FX Trading Adapter:
```
./dfw start FxTradingAdapter
```
Check your FX Trading Adapter logs — fxtrading-adapter.log and ret.log — and then go back to the Liberator status page http://localhost:18080/status . A Green status should now be showing for FxTradingAdapter and trading will have been restored in the FX Professional web application.

Review

The above example demonstrates a straight forward issue that was easily identified and resolved. To investigate future issues it is recommended that you follow this systematic approach.

You can find a summary of the approach demonstrated in this tutorial here: Caplin Troubleshooting Checklist.