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.

Note: More information on logging can be found in the online developer documentation: Troubleshoot my RET Adapter.

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 service - 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
com.caplin.example.ret

Customers specific logs. As each RET Adapter contains at least one class that does not belong to the RETAdapterToolkit, 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 Reuters 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 Reuters logging and then simulate some possible connection issues. You will then look at ways of resolving the connection issues using a systematic approach.

Reuters 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 Reuters 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 Reuters APIs —  trapi-lib, rates-plugin, admin, lbn — are usually cached within the RETAdapterToolkit (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 is based on the Caplin Troubleshooting Checklist that can be used as a systematic approach to resolving adapter issues.

Follow the steps below:

  1. First, you will reproduce an error by going to <DeploymentFramework>/global_config/overrides/FxTradingAdapters/etc and renaming the file trapi.lic to something different like trapi.lic.bak.
  2. Then restart the FxTradingAdapter by opening a Cygwin console on your machine, navigating to your Deployment Framework's topmost directory and executing the following command: 

    ./dfw start FxTradingAdapter
    
  3. Now check the Liberator status page to confirm the error/issue is present. Do this by navigating to http://localhost:18080/status. The status indicator for the FxTradingAdapter should now be RED, meaning we will need to investigate this adapter first.
  4. Before you begin investigating, launch the FX Professional Motif 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 an RFS or SWAP trade an error message will display "Trading Not Available". 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 directly to the Trading Adapter.
  5. Enable the client.log of the FX Professional Motif 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]
  6. 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.
  7. Next, check the fxtrading-adapter.log. In this log file you should be able to view an exception being thrown by the trapi-lib (com.m_systems.trapi.lib.TradingEngine) whereby the correct licence is missing.

    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
    // com.m_systems.trapi are log lines thrown by trapi-lib-3.5.126.jar
            at com.m_systems.trapi.lib.TrAPI_ae.d(Unknown Source) ~[trapi-lib-3.5.126.jar:?]
            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:?]
    // log lines starting with com.caplin.ret.trapi thrown by RETAdapterToolkit-3.5-2.2.0-3807-6e8c45d.jar
            at com.caplin.ret.trapi.fx.execution.impl.TrAPIMarketOrderTradingEngine.connect(TrAPIMarketOrderTradingEngine.java:55) ~[RETAdapterToolkit-3.5-2.2.0-3807-6e8c45d.jar:?]
            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:?]
    // log lines starting with com.caplin.motif.fx.ret thrown by 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:?]
            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]
    

    If you look at this log file example you can already see there's a lot of information. You can view which library is throwing an exception, and you can also view the version of that library. The package name give you a hint as to which level an exception is thrown, whether it is along the communication between the Adapter and the RET system (com.caplin.ret.trapi) OR via the communication between the Adapter and the FX Professional Motif (com.caplin.motif.fx.ret), within the Caplin RETAdapterToolkit.

  8. If you go and check your ret.log file not much will be displayed as the connection is unavailable, and therefore no data is being sent through.

    17/04/15 13:15:24.829 GMT Trading API TrAPI-3.5.126.BD Started
  9. You can also check the Liberator's event.log file under <DeploymentFramework>/servers/Liberator/var/
  10. As our error in the log file suggested, we have to check the configuration for our log file, so rename your licence file back to trapi.lic.
  11. Now restart the FxTradingAdapter by opening a Cygwin console on your machine, navigating to your Deployment Framework's topmost directory and executing the following command: 

    ./dfw start FxTradingAdapter
    
  12. Finally, go back and check your FxTradingAdapter 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/enabled in the FX Professional Motif 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. Use our Caplin Troubleshooting Checklist to do so, you may have to do a full stack log and follow requests all the way from the Client through to Caplin components, right down to RET.