Logging

<< Click to Display Table of Contents >>

Navigation:  Webservices > Integration >

Logging

 

DTS Webservices can be created with special logging parameters in order to create customized logs that can be processed by other tools for reporting, statistics, or other purposes.

Information-icon_16px For the moment, customized logging is only compatible with Tomcat application servers.

 

 

Separate Logging

 

By default, DTS Webservices will log messages in the application server's main output log (e.g. [tomcat]/logs/catalina.out).

To turn on customized Webservice logging, the GUI Controller must be started with the DTS_WS_LOGGING_PATH environment variable set.

DTS_WS_LOGGING_PATH=/opt/tomcat/logs/dts

 

This directory path set here will be the target for the logs created by all DTS Webservices on the machine or container running the application server where the services are deployed.

Information-icon_16px Only Webservices generated while the Webapp is connected to a GUI Controller with DTS_WS_LOGGING_PATH set will be capable of customized logging.

 

Information-icon_16px If the Application Server is running in a Docker container, it is a good idea to map this path to the host for easy access to the logs.

 

The webservices will create daily log files in this directory with the following names:

[service-name].YYYY-MM-DD.log

 

When separate/customized logging is enabled, the log messages created by DTS Webservices will use the format:

[YYYY-MM-DD HH:MM:SS] [LEVEL]: [MESSAGE][STACK_TRACE]

 

[LEVEL] represents the logging level of the message (INFO, WARNING, ERROR, DEBUG, SEVERE, etc.)

[MESSAGE] represents the actual message being logged (created either by the Application Server or the Webservice)

[STACK_TRACE] represents a JVM stack trace to help diagnose errors.

 

Customization Parameters

 

Certain parameters can be customized for Webservice logging. This is done by setting environment variables either globally on the machine or container running the application server, or within the startup scripts of the application server itself.

 

Like all DTS modules, the Webservices respond to the DTS_DEBUG_LOGGING environment variable which, if set to true, will increase the verbosity of the output for debugging purposes.

DTS_DEBUG_LOGGING=true

 

Information-icon_16px Debug logging can increase output volume substantially. If log files become too large, please check if DTS_DEBUG_LOGGING is on and needed.

 

Information-icon_16px Unlike other logging customization options, debug logging can be enabled for any Webservice, regardless of how it was created.

 

 

DTS Webservices can also be configured to log all transactions they handle by setting the DTS_TRANSACTION_LOGGING environment variable to true.

DTS_TRANSACTION_LOGGING=true

 

Information-icon_16px Transaction logging will fork the input and output streams of request and response message in order to perform its function, so it may have a perceivable performance impact in certain scenarios.

 

 

Transaction logging can be further customized by setting the DTS_TRANSACTION_FORMAT environment variable to a specific tokenized string, thus instructing the logger to create messages that include certain information.

The following tokens are currently available for the transaction format:

Token

Name

Description

%a

REMOTE_HOST_TOKEN

The address of the remote host that invoked the transaction

%u

REMOTE_USER_TOKEN

The username that invoked the transaction

%t

TIMESTAMP_TOKEN

The timestamp of the request receipt

%T

RETURN_TIME_TOKEN

The number of milliseconds it took for the service to resolve the request

%m

METHOD_TOKEN

The type of http method that was invoked (GET, POST, etc.)

%r

URI_TOKEN

The operation URI

%q

QUERY_TOKEN

The query being perfomed (GET only)

%b

REQ_BODY_TOKEN

The body of the http request

%B

RESP_BODY_TOKEN

The body of the http response

%h

REQ_HEADER_TOKEN

A specific header in the http request [*]

%H

RESP_HEADER_TOKEN

A specific header in the http response [*]

%n

NEW_LINE_TOKEN

A system-specific new line character

Information-icon_16px [*] Header tokens require the name of a header to be specified after the token between {{ and }}.

For example %h{{connection}} will extract the header value for the "connection" tag.

Header names are not case sensitive.

 

If transaction logging is enabled but no specific format is set, the webservices will use the following default format:

TRANSACTION: %a %m %r %q %T%nREQ: %b%nRESP: %B

 

Information-icon_16px The transaction format affects only the [MESSAGE] section of the resulting log message.

 

Example Messages (Default Format)

 

GET Transaction:

[2021-03-12 16:46:04] INFO: TRANSACTION: 192.168.199.1 GET /test_ora_abcd_DEV_v2/app/ora1/SG_DATA1_EO_COMPOSITE_SWITCH/records ID=4553 34ms

REQ: 

RESP: [{"device_TYPE":10,"phase_CONTEXT":999,"mounting":20,"number0":null,"owner_TYPE":10,"owner_NAME":10,"asset_ID":null,"date_INSTALLED":null,"source_ID":null,"source_DATA":null,"style_SUBCODE":10020,"design":null,"rwo_ID":4860,"alias_DESCRIPTION":"Composite Switch (4553)","location_DESCRIPTION":null,"remarks":null,"map_ID_INTERNALS":0,"status":20,"network_TYPE":20,"nominal_VOLTAGE_PP":290,"phasing":100,"id":4553}]

 

POST Transaction:

[2021-03-12 16:43:40] INFO: TRANSACTION: 192.168.199.1 POST /test_ora_abcd_DEV_v2/app/ora1/SG_DATA1_EO_COMPOSITE_SWITCH/records-with-pred - 177ms

REQ: {"predicate": {"operatorName": "eq","attributeName": "ID","attributeValue": "4553"},"dts__size": 1}

RESP: [{"device_TYPE":10,"phase_CONTEXT":999,"mounting":20,"number0":null,"owner_TYPE":10,"owner_NAME":10,"asset_ID":null,"date_INSTALLED":null,"source_ID":null,"source_DATA":null,"style_SUBCODE":10020,"design":null,"rwo_ID":4860,"alias_DESCRIPTION":"Composite Switch (4553)","location_DESCRIPTION":null,"remarks":null,"map_ID_INTERNALS":0,"status":20,"network_TYPE":20,"nominal_VOLTAGE_PP":290,"phasing":100,"id":4553}]

 

Severe Exception:

[2021-03-12 16:43:25] SEVERE: Servlet.service() for servlet [abcd] in context with path [/test_ora_abcd_DEV_v2] threw exception

org.apache.cxf.interceptor.Fault: DTS Endpoint ora1 not available to use!

     at org.apache.cxf.service.invoker.AbstractInvoker.createFault(AbstractInvoker.java:162)

     at org.apache.cxf.service.invoker.AbstractInvoker.invoke(AbstractInvoker.java:128)

     at org.apache.cxf.jaxrs.JAXRSInvoker.invoke(JAXRSInvoker.java:201)

     at org.apache.cxf.jaxrs.JAXRSInvoker.invoke(JAXRSInvoker.java:104) […]