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.
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.
Only Webservices generated while the Webapp is connected to a GUI Controller with DTS_WS_LOGGING_PATH set will be capable of customized logging.
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
Debug logging can increase output volume substantially. If log files become too large, please check if DTS_DEBUG_LOGGING is on and needed.
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
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 |
[*] 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
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) […]