How to Configure GemFire Pulse Logging in an Embedded Mode

Products

• VMware Tanzu Gemfire

Issue/Introduction

The purpose of this article is to explain some details about how GemFire Pulse logging can be configured when Pulse is running in an embedded mode, both for versions 8.X and 9.X.

The approach used for both versions differs primarily because GemFire started extensively using Apache log4j as the underlying logging framework on version 9.X.

Environment

GemFire 8.X and 9.X.

Resolution

GemFire 8.2.X

This is an easy approach as the logging configuration is directly controlled by the system properties set when starting the locator process. Below is the summary of the available properties that can be used along with a brief description of each one:
 

• pulse.Log-Level: It is the log-level to use. It can be set as "OFF, SEVERE, WARNING, INFO, CONFIG, FINE, FINER, FINEST, ALL".
• pulse.Log-Append: It specifies append mode. If set to "true", new logs will be added to the current existing file and if set to "false", a new log file will be created every time.
• pulse.Log-File-Size0: It represents the maximum number of bytes to write to any one file. This is internally represented as a simple "int", so the maximum value is "Integer.MAX_VALUE = 2e31-1".
• pulse.Log-File-Count: It is the maximum number of files to use.
• pulse.Log-File-Name: It is the file name that will be used.
• pulse.Log-File-Location: It is the folder where all the log files will be written.

As an example, assuming that the requirement is for the log files to be named "pulse.log_[fileNumber].log" stored in "/pulseLogs" using the FINEST log-level, have at maximum 5 files and rotate whenever the individual file size is 10Mb, the following parameters should be added to the locator's startup script:

--J=-Dpulse.Log-File-Name=pulse.log --J=-Dpulse.Log-File-Location=/pulseLogs --J=-Dpulse.Log-Level=FINEST --J=-Dpulse.Log-File-Size=1000000 --J=-Dpulse.Log-File-Count=5

 

GemFire 9.X.X

This approach needs some knowledge about Apache log4j. The main idea here is to get the default log4j2.xml file shipped with the product, stored in GEMFIRE_HOME/config and make the required modifications to meet the requirements. There are tons of appenders and configurations that can be used but, for the purpose of following the previous example, only RollingFile appender will be shown within this article. The full list of available appenders and the configuration options can be found in Appenders. Keep in mind that only the configuration related to Pulse should be modified. Bad configuration changes to the log4j2.xml file may result in missing statements or information in the logs.

Assuming again that the requirement is for the log files to be named pulse.log_[fileNumber].log, stored in /pulseLogs using the FINEST log-level, and have at maximum 5 files and rotate whenever the individual file size is 10Mb, the following parameters should be added to the locator's startup script:

--J=-Dlog4j.configurationFile=/gemfireConfig/log4j2-custom.xml

The contents of /gemfireConfig/log4j2-custom.xml can be found below, the sections marked with <!-- EXTENSION - START/FINISH --> are the ones added to the default GemFire logging configuration:

<?xml version="1.0" encoding="UTF-8"?>
<!--
~ Licensed to the Apache Software Foundation (ASF) under one or more
~ contributor license agreements. See the NOTICE file distributed with
~ this work for additional information regarding copyright ownership.
~ The ASF licenses this file to You under the Apache License, Version 2.0
~ (the "License"); you may not use this file except in compliance with
~ the License. You may obtain a copy of the License at
~
~ http://www.apache.org/licenses/LICENSE-2.0
~
~ Unless required by applicable law or agreed to in writing, software
~ distributed under the License is distributed on an "AS IS" BASIS,
~ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
~ See the License for the specific language governing permissions and
~ limitations under the License.
-->
<Configuration status="WARN" shutdownHook="disable" packages="org.apache.geode">
<Properties>
<Property name="geode-pattern">[%level{lowerCase=true} %date{yyyy/MM/dd HH:mm:ss.SSS z} &lt;%thread&gt; tid=%hexTid] %message%n%throwable%n</Property>
<Property name="geode-default">true</Property>
</Properties>
<Appenders>
<GeodeConsole name="STDOUT" target="SYSTEM_OUT">
<PatternLayout pattern="${geode-pattern}"/>
</GeodeConsole>
<GeodeLogWriter name="LOGWRITER">
<PatternLayout pattern="${geode-pattern}"/>
</GeodeLogWriter>
<GeodeLogWriter name="SECURITYLOGWRITER" security="true">
<PatternLayout pattern="${geode-pattern}"/>
</GeodeLogWriter>
<GeodeAlert name="ALERT"/>
<!-- EXTENSION - START -->
<RollingFile name="PulseRollingFile" fileName="pulse.log" filePattern="pulse.log_%i.log">
<PatternLayout>
<Pattern>%d %p %c{1.} [%t] %m%n</Pattern>
</PatternLayout>
<Policies>
<!-- 1KB here is to test quickly, and in real-time, this value can be anything depending on your need. e.g. 500KB, 15MB, 500MB etc.
Another important thing to remember is, do not add a space between the number and the unit. e.g. 1 KB is wrong and 1KB is right. 
-->
<SizeBasedTriggeringPolicy size="1KB"/>
</Policies>
<DefaultRolloverStrategy max="5"/>
</RollingFile>
<!-- EXTENSION - FINISH -->
</Appenders>
<Loggers>
<Logger name="com.gemstone" level="INFO" additivity="true"/>
<Logger name="org.apache.geode" level="INFO" additivity="true">
<filters>
<MarkerFilter marker="GEODE_VERBOSE" onMatch="DENY" onMismatch="NEUTRAL"/>
</filters>
</Logger>
<Logger name="org.apache.geode.security" level="INFO" additivity="false">
<AppenderRef ref="SECURITYLOGWRITER"/>
</Logger>
<Logger name="org.jgroups" level="FATAL" additivity="true"/>
<Logger name="org.eclipse.jetty" level="FATAL" additivity="true"/>
<!-- EXTENSION - START -->
<Logger name="org.apache.geode.tools.pulse.internal" level="FINEST" additivity="true">
<AppenderRef ref="PulseRollingFile"/>
</Logger>
<!-- EXTENSION - FINISH -->
<Root level="INFO">
<AppenderRef ref="STDOUT"/>
<AppenderRef ref="LOGWRITER"/>
<AppenderRef ref="ALERT"/>
</Root>
</Loggers>
</Configuration>

NOTE: If this sample file doesn't work for you, make sure you get the copy of log4j.xml provided with your GemFire installation folder, like pivotal-gemfire-9.9.1/config/log4j.xml, and name it anything you want unless you want to change the behavior of the original file permanently. And once you are sure, add these 2 blocks for RollingFile and you are good to go. Read here for more info: https://logging.apache.org/log4j/2.x/manual/appenders.html

1. Appender under <Appenders> section:

<RollingFile name="PulseRollingFile" fileName="pulse.log" filePattern="pulse.log_%i.log">
<PatternLayout>
<Pattern>%d %p %c{1.} [%t] %m%n</Pattern>
</PatternLayout>
<Policies>
<SizeBasedTriggeringPolicy size="1KB"/>
</Policies>
<DefaultRolloverStrategy max="5"/>
</RollingFile>

2. Appender's reference in <Loggers> section:

<Logger name="org.apache.geode.tools.pulse.internal" level="FINEST" additivity="true">
      <AppenderRef ref="PulseRollingFile"/>
</Logger>