Repository files navigation

Warning: Themain branch was force-pushed on October 30th, 2025.

If you cloned or checked out this repository before that date, you may encounter issues when pulling new changes. Toresolve this, reset your localmain branch to match the remote:

git fetch origingit checkout main git reset --hard origin/main

Caution: This will discard any local changes on yourmain branch.

This is a collection of support libraries for Java applications (Java 11 and above) that serves three main purposes:

1. Provide means to emitstructured application log messages
2. Instrument parts of your application stack tocollect request metrics
3. Allow auto-configuration of OpenTelemetry exporters.

The libraries started out to support applications running on Cloud Foundry.This integration has become optional.The library can be used in any runtime environment such as Kubernetes or Kyma.

When we say structured, we actually mean in JSON format.In that sense, it shares ideas withlogstash-logback-encoder,but takes a simpler approach as we want to ensure that these structured messages adhere to standardized formats.With such standardized formats in place, it becomes much easier to ingest, process and search such messages in loganalysis stacks such asELK.

If you're interested in the specifications of these standardized formats, you may want to have a closer look at thefields.yml files in thebeats folder.

Whilelogstash-logback-encoder is tiedtologback, we've tried to keep implementation neutral and have implemented the corefunctionality on top ofslf4j, but provided implementations forbothlogback andlog4j2 (and we're open tocontributions that would support other implementations).

The instrumentation part is currently focusing onprovidingrequest filters for Java Servlets, but again,we're open to contributions for other APIs and frameworks.

Lastly, there is also a project onnode.js logging support.

As you can see from the structure of this repository, we're not providing oneuber JAR that contains everything, butprovide each feature separately. We also try to stay away from wiring up too many dependencies by tagging almost all ofthem asprovided. As a consequence, it's your task to get all runtime dependencies resolved in your application POMfile.

All in all, you should do the following:

1. Make up your mind which features you actually need.
2. Adjust your Maven dependencies accordingly.
3. Pick your favorite logging implementation.And
4. Adjust your logging configuration accordingly.

Let's say you want to make use of theservlet filter feature, then you need to add the following dependency to yourPOM with propertycf-logging-version referring to the latest nexus version (currently4.0.0):

<properties>    <cf-logging-version>4.0.0</cf-logging-version></properties>

<dependency>  <groupId>com.sap.hcp.cf.logging</groupId>  <artifactId>cf-java-logging-support-servlet</artifactId>  <version>${cf-logging-version}</version></dependency>

This feature only depends on the servlet API which you have included in your POM anyhow. You can find more informationabout theservlet filter feature (like e.g. how to adjust the web.xml) intheWiki.

Thecore feature (on which all other features rely) is just using theorg.slf4j API, but to actually get logswritten, you need to pick an implementation feature. As stated above, we have two implementations:

• cf-java-logging-support-logback based onlogback, and
• cf-java-logging-support-log4j2 based onlog4j2.

Again, we don't include dependencies to those implementation backends ourselves, so you need to provide thecorresponding dependencies in your POM file:

Using logback:

<dependency><groupId>com.sap.hcp.cf.logging</groupId>  <artifactId>cf-java-logging-support-logback</artifactId>  <version>${cf-logging-version}</version></dependency><dependency>  <groupId>ch.qos.logback</groupId>   <artifactId>logback-classic</artifactId>   <version>1.5.20</version> </dependency>

Using log4j2:

<dependency><groupId>com.sap.hcp.cf.logging</groupId>  <artifactId>cf-java-logging-support-log4j2</artifactId>  <version>${cf-logging-version}</version></dependency><dependency><groupId>org.apache.logging.log4j</groupId><artifactId>log4j-slf4j-impl</artifactId><version>2.25.2</version></dependency><dependency><groupId>org.apache.logging.log4j</groupId><artifactId>log4j-core</artifactId><version>2.25.2</version></dependency>

As they have slightly differ in configuration, you again will need to do that yourself. But we hope that we've found aneasy way to accomplish that. The one thing you have to do is pick ourencoder in yourlogback.xml if you're usinglogback or ourlayout in yourlog4j2.xmlif you're usinglog4j2.

Here are the minimal configurations you'd need:

logback.xml:

<configurationdebug="false"scan="false"><appendername="STDOUT-JSON"class="ch.qos.logback.core.ConsoleAppender">       <encoderclass="com.sap.hcp.cf.logback.encoder.JsonEncoder"/>    </appender><!-- for local development, you may want to switch to a more human-readable layout-->    <appendername="STDOUT"class="ch.qos.logback.core.ConsoleAppender">        <encoder>            <pattern>%date %-5level [%thread] - [%logger] [%mdc] - %msg%n</pattern>        </encoder>    </appender>    <rootlevel="${LOG_ROOT_LEVEL:-WARN}"><!-- Use 'STDOUT' instead for human-readable output-->       <appender-refref="STDOUT-JSON" />    </root><!-- request metrics are reported using INFO level, so make sure the instrumentation loggers are set to that level-->    <loggername="com.sap.hcp.cf"level="INFO" /></configuration>

log4j2.xml:

<Configurationstatus="warn"strict="true"><Appenders>        <Consolename="STDOUT-JSON"target="SYSTEM_OUT"follow="true">            <JsonPatternLayoutcharset="utf-8"/>        </Console>        <Consolename="STDOUT"target="SYSTEM_OUT"follow="true">            <PatternLayoutpattern="%d{HH:mm:ss.SSS} [%t] %-5level %logger{36} [%mdc] - %msg%n"/>        </Console></Appenders>  <Loggers>     <Rootlevel="${LOG_ROOT_LEVEL:-WARN}"><!-- Use 'STDOUT' instead for human-readable output-->        <AppenderRefref="STDOUT-JSON" />     </Root><!-- request metrics are reported using INFO level, so make sure the instrumentation loggers are set to that level-->     <Loggername="com.sap.hcp.cf"level="INFO"/>  </Loggers></Configuration>

This library provides the possibility to change the log-level threshold for asingle thread by adding a token in the header of a request. A detaileddescription about how to apply this feature can be foundhere.

Stacktraces can be logged within one log message. Further details can be foundhere.

In order to illustrate how the different features are used, this repository includes one sample application:

• a Spring Boot implementation in the./sample-spring-boot folder

More info on the actual implementation can be found in theWiki.

Please see ourLICENSE for copyright and license information. Detailed information including third-partycomponents and their licensing/copyright information is available viatheREUSE tool.