1. Transaction Manager for Microservices Developer Guide
  2. Monitor and Trace Transactions
  3. Logs
  4. Define the Syntax of Log Messages

14.4.1 Define the Syntax of Log Messages

Specify the details that you want to record in the logs and the syntax of the log messages.

To view the logs emitted by MicroTx in a Kubernetes cluster, you can set up one of the following stacks or any other application to aggregate and view the log files of MicroTx coordinator and applications at a single place.
  • Elasticsearch, Fluentd or Fluent bit, and Kibana (EFK) stack
  • Elasticsearch, LogStash, and Kibana (ELK) stack

For information about setting up EFK or ELK stack, refer to the application's product documentation.

After setting up the EFK or ELK stack, you must perform the following steps once to specify the details that you want to record in the logs and the syntax of the log messages.
  1. Define the parser filters for the log aggregator. The following example defines the parsers for Fluentbit. The Regex field provides the syntax of the log message and the details that are logged. Similarly, you can define the parsers for any log aggregator that you want to use. Refer to the log aggregator's product documentation for more details.
        [PARSER]
        Name  mtxnodejslib
        Format regex
        Regex  ^(?<timestamp>\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{3}Z)\s+::\s+(?<transactionId>[a-f0-9-]+)\s+-\s+(?<message>.+)$
        Time_Key timestamp
        Time_Format %Y-%m-%dT%H:%M:%S.%zZ
     
    [PARSER]
        Name  mtxlraspringbootlib
        Format regex
        Regex  ^(?<timestamp>\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2}\.\d{3})\s+(?<log_level>\w+)\s+(?<numeric_value>\d+)\s+---\s+\[(?<thread_info>[\w-]+)\]\s+(?<logger_name>\S+)\s+:\s+(?<transactionId>\S+)\s+-\s+(?<message>.+)$
        Time_Key timestamp
        Time_Format %Y-%m-%d %H:%M:%S.%z
 
    [PARSER]
        Name  mtxhelidon
        Format regex
        Regex  ^(?<timestamp>\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2}\.\d{3})\s+(?<log_level>\w+)\s+---\s+\[(?<thread_name>[^\]]+)\]\s+(?<logger_name>[^:]+)\s+:\s+(?<transactionId>[a-f0-9-]+)\s+:\s+(?<log_message>.+)$
        Time_Key timestamp
        Time_Format %Y-%m-%d %H:%M:%S.%z
 
    [PARSER]
        Name  mtxxaspringbootlib
        Format regex
        Regex  ^(?<timestamp>\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2}\.\d{3})\s+(?<log_level>\w+)\s+\d+\s+---\s+\[(?<thread_name>[^\]]+)\]\s+(?<logger_name>[^:]+)\s+:\s+(?<transactionId>[a-f0-9-]+)\s+:\s+(?<log_message>.+)$
        Time_Key timestamp
        Time_Format %Y-%m-%d %H:%M:%S.%z
    To view the example logs that correspond to the syntax you have specified in the parser, see Sample Log Messages.
  2. For the MicroTx Java library for Helidon applications, create an XML file, such as log4j2.xml, in your application's resources folder to specify the syntax of the log messages. For example, src/main/resources/log4j2.xml.

    1. The following code sample demonstrates how you can specify the position of the various fields in the log message. 

      <Console name="MicroTxLib" target="SYSTEM_OUT">
            <PatternLayout pattern="%d{yyyy-MM-dd HH:mm:ss.SSS}  %-5level --- [%t] %-50.70C : [microtx-log] %X{microtx-txnId} : %msg%n%throwable"/>
        </Console>

      Where,

      • MicroTxLib Note down this name as you will provide this name later in the Logger section to define the packages that you want to log.
      • PatternLayout specifies the syntax of the log messages.
      • [microtx-log] is prefixed to the log messages generated by the MicroTx library. This helps you differentiate the log messages generated by the MicroTx library from the messages generated by the application. Use [microtx-log] to filter all the log messages generated by the MicroTx library.
      • %X{microtx-txnId} refers to the unique transaction ID. When MicroTx logs a message, %X{microtx-txnId} is replaced with the actual transaction ID.
    2. Provide the names of the MicroTx packages which will use the log message definition that you have provided in the previous step.
      <Logger name="oracle.tmm" level="DEBUG" additivity="false">
        <AppenderRef ref="MicroTxLib"/>
</Logger>

<Logger name="com.oracle" level="TRACE" additivity="false">
        <AppenderRef ref="MicroTxLib"/>
</Logger>

      Where,

      • oracle.tmm and com.oracle are the names of the MicroTx packages for which you want the messages to be logged.
      • DEBUG and TRACE are the log levels. Enter one of the following values to specify the log level for the MicroTx library:
        • INFO: Logs events that occur during the normal operation of the MicroTx. This setting logs the least amount of information. This is the default setting.
        • WARNING: Logs events that may cause potentially harmful situations.
        • ERROR: Logs events to indicate that there is an issue that requires troubleshooting.
        • DEBUG: Logs all the events. Use this setting when you want to debug an issue.
      • MicroTxLib is the value of AppenderRef. This value must match the value of the name that you have entered in the previous step.

    The following code provides sample entries for the log4j2.xml file. 

    <?xml version="1.0" encoding="UTF-8"?>
<Configuration status="WARN">
    <Appenders>
        <Console name="Console" target="SYSTEM_OUT">
            <PatternLayout pattern="%d{yyyy-MM-dd HH:mm:ss.SSS}  %-5level --- [%t] %-50.70C : [microtx-log] %X{microtx-txnId} : %msg%n%throwable"/>
        </Console>
 
        <Console name="MicroTxLib" target="SYSTEM_OUT">
            <PatternLayout pattern="%d{yyyy-MM-dd HH:mm:ss.SSS}  %-5level --- [%t] %-50.70C : [microtx-log] %X{microtx-txnId} : %msg%n%throwable"/>
        </Console>
    </Appenders>
    <Loggers>
        <Logger name="oracle.tmm" level="DEBUG" additivity="false">
            <AppenderRef ref="MicroTxLib"/>
        </Logger>
        <Logger name="com.oracle" level="TRACE" additivity="false">
            <AppenderRef ref="MicroTxLib"/>
        </Logger>

        <Root level="info">
            <AppenderRef ref="Console"/>
        </Root>
    </Loggers>
</Configuration>
  3. For the MicroTx Java library for Spring REST applications, create an XML file in your application's resources folder to specify the syntax of the log messages. For example, src/main/resources/logback-spring.xml.

    1. The following code sample demonstrates how you can define the appender to specify the position of the various fields in the log message. 

      <appender name="ConsoleMTX"
              class="ch.qos.logback.core.ConsoleAppender">
        <layout class="ch.qos.logback.classic.PatternLayout">
            <Pattern>
                %clr(%d{${LOG_DATEFORMAT_PATTERN:-yyyy-MM-dd HH:mm:ss.SSS}}){faint} %clr(${LOG_LEVEL_PATTERN:-%5p}) %clr(${PID:- }){magenta} %clr(---){faint} %clr([%15.15t]){faint} %clr(%-40.40logger{39}){cyan} %clr(:){faint} [microtx-log] %X{microtx-txnId} : %m%n${LOG_EXCEPTION_CONVERSION_WORD:-%wEx}
            </Pattern>
        </layout>
    </appender>

      Where,

      • ConsoleMTX Note down this name as you will provide this name later in the Logger section to define the packages that you want to log.
      • Pattern specifies the syntax of the log messages.
      • [microtx-log] is prefixed to the log messages generated by the MicroTx library. This helps you differentiate the log messages generated by the MicroTx library from the messages generated by the application. Use [microtx-log] to filter all the log messages generated by the MicroTx library.
      • %X{microtx-txnId} refers to the unique transaction ID. When MicroTx logs a message, %X{microtx-txnId} is replaced with the actual transaction ID.
    2. Provide the names of the MicroTx packages which will use the appender that you have defined in the previous step.
      <Logger name="oracle.tmm" level="TRACE" additivity="false">
        <AppenderRef ref="ConsoleMTX"/>
</Logger>
<Logger name="com.oracle" level="DEBUG" additivity="false">
        <AppenderRef ref="ConsoleMTX"/>
</Logger>

      Where,

      • oracle.tmm and com.oracle are the names of the MicroTx packages for which you want the messages to be logged.
      • TRACE and DEBUG are the log levels. Enter one of the following values to specify the log level for the MicroTx library:
        • INFO: Logs events that occur during the normal operation of the MicroTx. This setting logs the least amount of information. This is the default setting.
        • WARNING: Logs events that may cause potentially harmful situations.
        • ERROR: Logs events to indicate that there is an issue that requires troubleshooting.
        • DEBUG: Logs all the events. Use this setting when you want to debug an issue.
      • ConsoleMTX is the value of AppenderRef. This value must match the value of the appender name that you have entered in the previous step.

If you want to use another tool to log the information, provide the syntax of the log message in a similar way.

Parent topic: Logs