| <!-- vim: set syn=markdown : --> |
| <!-- |
| 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. |
| --> |
| #set($h1='#') |
| #set($h2='##') |
| #set($h3='###') |
| #macro(maven $artifactIds) |
| #mavenVersion($artifactIds $Log4jReleaseVersion) |
| #end |
| #macro(mavenVersion $artifactIds $version) |
| `pom.xml` |
| |
| ``` |
| <dependencies> |
| #foreach($artifactId in $artifactIds) |
| <dependency> |
| <groupId>org.apache.logging.log4j</groupId> |
| <artifactId>${artifactId}</artifactId> |
| <version>${version}</version> |
| </dependency> |
| #end |
| </dependencies> |
| ``` |
| #end |
| #macro(ivy $artifactIds) |
| #ivyVersion($artifactIds $Log4jReleaseVersion) |
| #end |
| #macro(ivyVersion $artifactIds $version) |
| `ivy.xml` |
| |
| ``` |
| <dependencies> |
| #foreach($artifactId in $artifactIds) |
| <dependency org="org.apache.logging.log4j" name="${artifactId}" rev="${version}" /> |
| #end |
| </dependencies> |
| ``` |
| #end |
| #macro(gradle $artifactIds) |
| #gradleVersion($artifactIds $Log4jReleaseVersion) |
| #end |
| #macro(gradleVersion $artifactIds $version) |
| `build.gradle` |
| |
| ``` |
| dependencies { |
| #foreach($artifactId in $artifactIds) |
| compile group: 'org.apache.logging.log4j', name: '${artifactId}', version: '${version}' |
| #end |
| } |
| ``` |
| #end |
| #macro(sbt $artifactIds) |
| #sbtVersion($artifactIds $Log4jReleaseVersion) |
| #end |
| #macro(sbtVersion $artifactIds $version) |
| `build.sbt` |
| |
| ``` |
| #foreach($artifactId in $artifactIds) |
| libraryDependencies += "org.apache.logging.log4j" %#if($artifactId.endsWith('scala'))%#end "${artifactId}" % "${version}" |
| #end |
| ``` |
| #end |
| ## prints out maven/ivy/gradle/sbt snippet for a list of artifactIds |
| #macro(dependencies $artifactIds) |
| #maven($artifactIds) |
| #ivy($artifactIds) |
| #gradle($artifactIds) |
| #sbt($artifactIds) |
| #end |
| ## -------------------------------------- |
| |
| $h1 Maven, Ivy, Gradle, and SBT Artifacts |
| |
| Log4j 2 is broken up in an API and an implementation (core), where the API |
| provides the interface that applications should code to. |
| Strictly speaking Log4j core is only needed at runtime and not at compile time. |
| |
| However, below we list Log4j core as a compile time dependency |
| to improve the startup time for [custom plugins](manual/plugins.html) as it provides an |
| annotation processor that generates a metadata file to cache plugin information as well |
| as the necessary code to compile against to create custom plugins. |
| |
| $h2 Using Log4j in your Apache Maven build |
| |
| To build with [Apache Maven](https://maven.apache.org/), add the dependencies listed below to your |
| `pom.xml` file. |
| |
| #maven(['log4j-api', 'log4j-core']) |
| |
| $h2 Using Log4j in your Apache Ivy build |
| |
| To build with [Apache Ivy](https://ant.apache.org/ivy/), add the dependencies listed below to your |
| `ivy.xml` file. |
| |
| #ivy(['log4j-api', 'log4j-core']) |
| |
| $h2 Using Log4j in your Gradle build |
| |
| To build with [Gradle](https://gradle.org/), add the dependencies listed below to your |
| `build.gradle` file. |
| |
| #gradle(['log4j-api', 'log4j-core']) |
| |
| $h2 Using Log4j in your SBT build |
| |
| To build with [SBT](http://www.scala-sbt.org/), add the dependencies listed below to your `build.sbt` file. |
| |
| #sbt(['log4j-api', 'log4j-core']) |
| |
| $h2 Bill of Material |
| |
| To keep your Log4j module versions in sync with each other, a |
| <abbr id="Bill of Material">BOM</abbr> |
| pom.xml file is provided for your convenience. To use this with |
| [Maven](https://maven.apache.org/), add the dependency listed below to your |
| `pom.xml` |
| file. When you specify the version identifier in this section, you don't have to specify the version in your |
| `<dependencies/>` section. |
| |
| `pom.xml` |
| |
| ``` |
| <dependencyManagement> |
| <dependencies> |
| <dependency> |
| <groupId>org.apache.logging.log4j</groupId> |
| <artifactId>log4j-bom</artifactId> |
| <version>${Log4jReleaseVersion}</version> |
| <scope>import</scope> |
| <type>pom</type> |
| </dependency> |
| </dependencies> |
| </dependencyManagement> |
| ``` |
| |
| To use this with Gradle, an additional [Gradle plugin](https://github.com/spring-gradle-plugins/dependency-management-plugin) |
| is required for dependency management functionality. |
| |
| `build.gradle` |
| |
| ``` |
| plugins { |
| id 'io.spring.dependency-management' version '1.0.1.RELEASE' |
| } |
| |
| dependencyManagement { |
| imports { |
| mavenBom 'org.apache.logging.log4j:log4j-bom:${Log4jReleaseVersion}' |
| } |
| } |
| |
| dependencies { |
| compile 'org.apache.logging.log4j:log4j-api' |
| compile 'org.apache.logging.log4j:log4j-core' |
| // etc. |
| } |
| ``` |
| |
| $h2 Optional Components |
| |
| Log4j 2.x contains several optional components that can be included in an application. |
| |
| $h3 Log4j 1.x API Bridge |
| |
| If existing components use Log4j 1.x and you want to have this logging routed to Log4j 2, |
| then remove any log4j 1.x dependencies and add the following. |
| |
| #dependencies(['log4j-1.2-api']) |
| |
| $h3 Apache Commons Logging Bridge |
| |
| If existing components use Apache Commons Logging 1.x and you want to have this logging routed to Log4j 2, |
| then add the following but do not remove any Commons Logging 1.x dependencies. |
| |
| #dependencies(['log4j-jcl']) |
| |
| $h3 SLF4J Bridge |
| |
| If existing components use SLF4J and you want to have this logging routed to Log4j 2, then add the |
| following but do not remove any SLF4J dependencies. |
| |
| #dependencies(['log4j-slf4j-impl']) |
| |
| $h3 JUL Adapter |
| |
| If existing components use Java Util Logging and you want to have this logging routed to Log4j 2, |
| then add the following. |
| |
| #dependencies(['log4j-jul']) |
| |
| $h3 Web Servlet Support |
| |
| In order to properly support and handle the ClassLoader environment and container lifecycle of a web |
| application, an additional module is required. This module is only required at runtime. In addition, if |
| you're using servlets in an OSGi environment, make sure your preferred version of the servlet API is |
| already available (e.g., if you want to use 3.0, but you've also got 2.5 loaded, make sure both are |
| loaded). |
| |
| #dependencies(['log4j-web']) |
| |
| $h3 Tag Library |
| |
| The Log4j Log Tag Library creates the capability of inserting log statements in JSPs without |
| the use of Java scripting. It uses the standard Log4j 2 API to log messages according to |
| your Log4j configuration. |
| |
| #dependencies(['log4j-taglib']) |
| |
| $h3 Apache Flume Appender |
| |
| The Flume Appender allows applications to send events to Flume Agents. |
| |
| #dependencies(['log4j-flume-ng']) |
| |
| $h3 Log4j to SLF4J Adapter |
| |
| The Log4j 2 to SLF4J Adapter allows applications coded to the Log4j 2 API to be routed to SLF4J. Use of this |
| adapter may cause some loss of performance as the Log4j 2 Messages must be formatted before they can be passed |
| to SLF4J. The SLF4J Bridge must NOT be on the class path when this is in use. |
| |
| #dependencies(['log4j-to-slf4j']) |
| |
| $h3 CouchDB |
| |
| If your configuration uses the NoSQL CouchDB appender, then add the following. |
| |
| #dependencies(['log4j-couchdb']) |
| |
| $h3 MongoDB |
| |
| If your configuration uses the NoSQL MongoDB appender, then add the following. |
| |
| #dependencies(['log4j-mongodb']) |
| |
| $h3 Cassandra |
| |
| If your configuration uses the Cassandra appender, then add the following. |
| |
| #dependencies(['log4j-cassandra']) |
| |
| $h3 IO Streams |
| |
| Log4j IO Streams allow applications to have data that is written to an OutputStream |
| or a Writer be redirected to a Logger, or have data that is read from an InputStream or |
| a Reader be wiretapped by a Logger. To use IO Streams, add the following. |
| |
| #dependencies(['log4j-iostreams']) |
| |
| $h3 Scala API |
| |
| A convenient Scala wrapper for the Logger API. SBT users can add the following to their |
| `build.sbt`: |
| |
| #sbtVersion(['log4j-api-scala'], '11.0') |
| |
| Maven, Ivy, and Gradle users need to add the Scala version to the artifact name. |
| |
| Scala 2.12 users can use the following: |
| |
| #mavenVersion(['log4j-api-scala_2.12'], '11.0') |
| #ivyVersion(['log4j-api-scala_2.12'], '11.0') |
| #gradleVersion(['log4j-api-scala_2.12'], '11.0') |
| |
| Scala 2.11 users can use the following: |
| |
| #mavenVersion(['log4j-api-scala_2.11'], '11.0') |
| #ivyVersion(['log4j-api-scala_2.11'], '11.0') |
| #gradleVersion(['log4j-api-scala_2.11'], '11.0') |
| |
| Scala 2.10 users can use the following: |
| |
| #mavenVersion(['log4j-api-scala_2.10'], '11.0') |
| #ivyVersion(['log4j-api-scala_2.10'], '11.0') |
| #gradleVersion(['log4j-api-scala_2.10'], '11.0') |
| |
| $h2 Snapshot builds |
| |
| You can access the latest development snapshot by using the Maven repository |
| `https://repository.apache.org/snapshots` and the current SNAPSHOT version. |
| Generally, the master branch will use the next patch version as its snapshot |
| version regardless of what the next actual version of Log4j will be. For example, |
| if the latest release were `2.0`, then master would be using the version |
| `2.0.1-SNAPSHOT`. Always verify with `pom.xml` in the master branch as described |
| in the [source repository page](source-repository.html). |
| |
| $h3 Maven |
| |
| Maven users can add the following to their `pom.xml` to enable snapshots: |
| |
| ``` |
| <repositories> |
| <repository> |
| <id>apache.snapshots</id> |
| <name>Apache Snapshot Repository</name> |
| <url>https://repository.apache.org/snapshots</url> |
| <releases> |
| <enabled>false</enabled> |
| </releases> |
| </repository> |
| </repositories> |
| ``` |
| |
| $h3 Gradle |
| |
| Gradle users can add the following to their `build.gradle` to enable snapshots: |
| |
| ``` |
| repositories { |
| mavenCentral() |
| maven { url 'https://repository.apache.org/snapshots' } |
| } |
| ``` |
| |
| $h3 SBT |
| |
| SBT users can add the following to their `build.sbt` to enable snapshots: |
| |
| ``` |
| resolvers += "Apache Snapshot Repository" at "https://repository.apache.org/snapshots" |
| ``` |