src/site/asciidoc/manual/scala-api.adoc

////
    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

        https://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.
////
= Log4j 2 Scala API
Mikael Ståldal <mikes@apache.org>

Log4j 2 has a companion Log4j Scala project that contains a convenient
Scala wrapper for the
link:../log4j-api/apidocs/org/apache/logging/log4j/Logger.html[`Logger`]
API.

== Requirements

Log4j 2 Scala API is dependent on the Log4j 2 API, Scala runtime library
and reflection. It currently supports Scala 2.10, 2.11 and 2.12. See
link:../maven-artifacts.html#Scala_API[instructions] on including this
in an SBT, Maven, Ivy, or Gradle project.

== Example

[source,scala]
----
import org.apache.logging.log4j.scala.Logging
import org.apache.logging.log4j.Level

class MyClass extends BaseClass with Logging {
  def doStuff(): Unit = {
    logger.info("Doing stuff")
  }
  def doStuffWithLevel(level: Level): Unit = {
    logger(level, "Doing stuff with arbitrary level")
  }
}
----

The output from the call to `logger.info()` will vary significantly
depending on the configuration used. See the
link:./configuration.html[Configuration] section for more details.

== Substituting Parameters

Frequently the purpose of logging is to provide information about what
is happening in the system, which requires including information about
the objects being manipulated. In Scala, you can use
http://docs.scala-lang.org/overviews/core/string-interpolation.html[string
interpolation] to achieve this:

[source,scala]
----
logger.debug(s"Logging in user ${user.getName} with birthday ${user.calcBirthday}")
----

Since the Scala Logger is implemented with macros, the String
construction and method invocations will only occur when debug logging
is enabled.

== Logger Names

Most logging implementations use a hierarchical scheme for matching
logger names with logging configuration. In this scheme the logger name
hierarchy is represented by '.' characters in the logger name, in a
fashion very similar to the hierarchy used for Java/Scala package names.
The Logging trait will automatically name the Logger accordingly to the
class it is being used in.

Please see the http://logging.apache.org/log4j/scala/index.html[Log4j
Scala] project for more details.