Configure Log4j

Overview

Retrace supports both Log4j 1.x and 2.x. You will find the instructions in the succeeding sections below on how to integrate logs from this logging framework into Retrace for both versions.

Downloads and Includes

Maven artifacts are available in the central Maven repository within a few hours after a new release. https://search.maven.org/#search%7Cga%7C1%7CStackify. The group id is com.stackify.

v1.x

The artifact id is stackify-log-log4j12. Substitute the version number you wish to use in the dependency snippet below.

<dependency>
    <groupId>com.stackify</groupId>
    <artifactId>stackify-log-log4j12</artifactId>
    <version>INSERT_LATEST_MAVEN_CENTRAL_VERSION</version>
</dependency>

v2.x

The artifact id is stackify-log-log4j2. Substitute the version number you wish to use in the dependency snippet below.

<dependency>
    <groupId>com.stackify</groupId>
    <artifactId>stackify-log-log4j2</artifactId>
    <version>INSERT_LATEST_MAVEN_CENTRAL_VERSION</version>
    <scope>runtime</scope>
</dependency>
<dependency>
    <groupId>javax.xml.bind</groupId>
    <artifactId>jaxb-api</artifactId>
    <version>INSERT_LATEST_MAVEN_CENTRAL_VERSION</version> 
</dependency>

Configuration

v1.x

Using the Properties file (e.g. log4j.properties):

log4j.appender.STACKIFY=com.stackify.log.log4j12.StackifyLogAppender
log4j.appender.STACKIFY.apiKey=YOUR_ACTIVATION_KEY
log4j.appender.STACKIFY.application=YOUR_APPLICATION_NAME
log4j.appender.STACKIFY.environment=YOUR_ENVIRONMENT
...
log4j.rootLogger=..., STACKIFY

Configuration via XML file (e.g. log4j.xml):

<appender name="STACKIFY" class="com.stackify.log.log4j12.StackifyLogAppender">
    <param name="apiKey" value="YOUR_ACTIVATION_KEY"/>
    <param name="application" value="YOUR_APPLICATION_NAME"/>
    <param name="environment" value="YOUR_ENVIRONMENT"/>
</appender>
...
<root>
    ...
    <appender-ref ref="STACKIFY" />
</root>

v2.x

Using the properties file (e.g. log4j2.properties):

packages=com.stackify.log.log4j2
# Stackify
appender.stackifyLog.type=StackifyLog
appender.stackifyLog.name=STACKIFY
appender.stackifyLog.apiKey=YOUR_ACTIVATION_KEY
appender.stackifyLog.application=YOUR_APPLICATION_NAME
appender.stackifyLog.environment=YOUR_ENVIRONMENT
### 
# ...other appenders/options...
###
rootLogger=DEBUG, STACKIFY

Configuration using XML (e.g. log4j2.xml):

<Configuration packages="com.stackify.log.log4j2">
    <Appenders>
        <StackifyLog name="Stackify" apiKey="YOUR_ACTIVATION_KEY" application="YOUR_APPLICATION_NAME" environment="YOUR_ENVIRONMENT" />
   </Appenders>
    <Loggers>
        <Root level="DEBUG">
            <AppenderRef ref="Stackify" />
        </Root>
    </Loggers>
</Configuration>

Be sure to shut down Log4j to flush this appender of any errors and shutdown the background thread:

LogManager.shutdown();

Masking

The Stackify appender has built-in data masking for credit cards and social security number values.

Enable Masking:

v1.x

Add <param name="maskEnabled" value="true"/> inside the <appender> ... </appender> tag.

v2.x

Add <MaskEnabled>true</MaskEnabled> inside the <StackifyLog> ... </StackifyLog> tag.

Customize Masking:

The example below has the following customizations:

1. Credit Card value masking is disabled (maskCreditCard=true).
2. Social Security Numbers (maskSSN=true)
3. IP Address masking is enabled (maskIP=true).
4. Custom masking to remove vowels using a regex (maskCustom=[aeiou]).

v1.x

log4j.appender.STACKIFY=com.stackify.log.log4j12.StackifyLogAppender
log4j.appender.STACKIFY.apiKey=YOUR_API_KEY
log4j.appender.STACKIFY.application=YOUR_APPLICATION_NAME
log4j.appender.STACKIFY.environment=YOUR_ENVIRONMENT
 
log4j.appender.STACKIFY.maskEnabled=true
# Option to mask credit card numbers
log4j.appender.STACKIFY.maskCreditCard=true
# Mask social security numbers
log4j.appender.STACKIFY.maskSSN=true
# Enable masking of IPs
log4j.appender.STACKIFY.maskIP=true 
# Custom masking by using a regular expression to remove vowels
log4j.appender.STACKIFY.maskCustom=[aeiou] 

<appender name="STACKIFY" class="com.stackify.log.log4j12.StackifyLogAppender">
    <param name="apiKey" value="YOUR_API_KEY"/>
    <param name="application" value="YOUR_APPLICATION_NAME"/>
    <param name="environment" value="YOUR_ENVIRONMENT"/>
      
    <param name="maskEnabled" value="true"/>
    <param name="maskCreditCard" value="true"/>
    <param name="maskSSN" value="true"/>
    <param name="maskIP" value="true"/>
    <param name="maskCustom" value="[aeiou]"/> 
</appender>

v2.x

# ... Base Stackify appender configuration...
# Credit Card
appender.stackifyLog.mask_cc.type=Mask
appender.stackifyLog.mask_cc.value=CREDITCARD
appender.stackifyLog.mask_cc.enabled=true
# Social Security Number
appender.stackifyLog.mask_ssn.type=Mask
appender.stackifyLog.mask_ssn.value=SSN
appender.stackifyLog.mask_ssn.enabled=true
# IP
appender.stackifyLog.mask_ip.type=Mask
appender.stackifyLog.mask_ip.value=IP
appender.stackifyLog.mask_ip.enabled=true
# Custom - aeiou
appender.stackifyLog.mask_custom.type=Mask
appender.stackifyLog.mask_custom.value=[aeiou]
appender.stackifyLog.mask_custom.enabled=true

<!-- ... Other configuration tags... -->
<Appenders>
        <StackifyLog name="STACKIFY" apiKey="YOUR_API_KEY" application="YOUR_APPLICATION_NAME" environment="YOUR_ENVIRONMENT">
            <MaskEnabled>true</MaskEnabled>
            <Mask enabled="false">CREDITCARD</Mask>
            <Mask enabled="true">SSN</Mask>
            <Mask enabled="true">IP</Mask>
            <Mask enabled="true">[aeiou]</Mask>
        </StackifyLog>
        <!--... Other appenders... -->
</Appenders>
<!-- ... Other configuration tags... -->

Sending Logs Through a Proxy

If you are wanting to send your logs into Stackify through a proxy, you will want to set the 'https.proxyHost' and 'https.proxyPort' system properties. If both of these properties are set in your app, your logs go through the proxy specified.

Advanced Features: MDC, and NDC

If you're utilizing MDC (Mapped Diagnostic Context) or NDC (Nested Diagnostic Context), Stackify will automatically pick up and report any data you add via MDC/NDC. This information will be available to you under the Custom Properties heading in the error details screen within Retrace.