index.html - logging-log4j-scala - Git at Google

 <!DOCTYPE html>
 <html lang="en">
   <head>
     <meta charset="utf-8">
     <meta name="viewport" content="width=device-width,initial-scale=1">
     <title>Log4j Scala API :: Apache Log4j Scala</title>
     <link rel="canonical" href="https://logging.apache.org/log4j/scala/index.html">
     <meta name="generator" content="Antora 3.2.0-alpha.4">
 <link rel="stylesheet" href="./_/css/site.css">
 <link rel="icon" href="./_/../_images/favicon.ico" type="image/x-icon">
 <!-- `@asciidoctor/tabs` extension styles -->
 <link rel="stylesheet" href="./_/css/vendor/tabs.css">
 <style>
   /* Default `h4` and `h5` are smaller than the normal text, fix header font sizing: */
   .doc h1 { font-size: 1.9rem; }
   .doc h2 { font-size: 1.7rem; }
   .doc h3 { font-size: 1.5rem; font-weight: 400; }
   .doc h4 { font-size: 1.3rem; font-weight: 500; }
   .doc h5 { font-size: 1.1rem; font-weight: 500; text-decoration: underline; }
   /* Default `code`, `pre`, and `.colist` (source code annotations) fonts are too big, adjust them: */
   .doc .colist>table code, .doc p code, .doc thead code { font-size: 0.8em; }
   .doc pre { font-size: 0.7rem; }
   .doc .colist { font-size: 0.75rem; }
   /* Make links more visible: */
   .doc a { text-decoration: underline; }
   .doc a code { text-decoration: underline; color: #1565c0; }
   /* Tab header fonts aren't rendered good, adjusting the font weight: */
   .tablist > ul li { font-weight: 500; }
   /* `page-toclevels` greater than 4 are not supported by Antora UI, patching it: */
   .toc .toc-menu li[data-level="4"] a {
     padding-left: 2.75rem;
   }
   /* Replace the default highlight.js color for strings from red (unnecessarily signaling something negative) to green: */
   .hljs-string {
     color: #0f8532;
   }
 </style>
   </head>
   <body class="article">
 <header class="header">
   <nav class="navbar">
     <div class="navbar-brand">
       <span class="navbar-item title">Apache Log4j Scala</span>
     </div>
     <div id="topbar-nav" class="navbar-menu">
       <div class="navbar-end">
         <a class="navbar-item" href="https://logging.apache.org">a subproject of&nbsp;<strong>Apache Logging Services</strong></a>
       </div>
     </div>
   </nav>
 </header>
 <div class="body">
 <div class="nav-container" data-component="ROOT" data-version="">
   <aside class="nav">
     <div class="panels">
 <div class="nav-panel-menu is-active" data-panel="menu">
   <nav class="nav-menu">
     <button class="nav-menu-toggle" aria-label="Toggle expand/collapse all" style="display: none"></button>
     <h3 class="title"><a href="index.html">Home</a></h3>
 <ul class="nav-list">
   <li class="nav-item" data-depth="0">
 <ul class="nav-list">
   <li class="nav-item" data-depth="1">
     <a class="nav-link" href="development.html">Development</a>
   </li>
   <li class="nav-item" data-depth="1">
     <a class="nav-link" href="release-notes.html">Release notes</a>
   </li>
   <li class="nav-item" data-depth="1">
     <a class="nav-link" href="https://logging.apache.org/download.html">Download</a>
   </li>
   <li class="nav-item" data-depth="1">
     <a class="nav-link" href="https://logging.apache.org/support.html">Support</a>
   </li>
   <li class="nav-item" data-depth="1">
     <a class="nav-link" href="https://logging.apache.org/security.html">Security</a>
   </li>
 </ul>
   </li>
 </ul>
   </nav>
 </div>
     </div>
   </aside>
 </div>
 <main class="article">
 <div class="toolbar" role="navigation">
 <button class="nav-toggle"></button>
   <a href="index.html" class="home-link is-current"></a>
 <nav class="breadcrumbs" aria-label="breadcrumbs">
   <ul>
     <li><a href="index.html">Home</a></li>
     <li><a href="index.html">Log4j Scala API</a></li>
   </ul>
 </nav>
 <div class="edit-this-page"><a href="https://github.com/apache/logging-log4j-scala/edit/main/src/site/antora/modules/ROOT/pages/index.adoc">Edit this Page</a></div>
 </div>
   <div class="content">
 <aside class="toc sidebar" data-title="Contents" data-levels="2">
   <div class="toc-menu"></div>
 </aside>
 <article class="doc">
 <h1 class="page">Log4j Scala API</h1>
 <div id="preamble">
 <div class="sectionbody">
 <div class="paragraph">
 <p>Log4j Scala API provides a Scala-friendly interface to log against <a href="https://logging.apache.org/log4j/2.x/manual/api-separation.html">the Log4j API</a>.
 It supports Scala <code>2.10</code>, <code>2.11</code>, <code>2.12</code>, <code>2.13</code>, and <code>3</code>.</p>
 </div>
 <div class="admonitionblock important">
 <table>
 <tr>
 <td class="icon">
 <i class="fa icon-important" title="Important"></i>
 </td>
 <td class="content">
 <div class="paragraph">
 <p>This is just a logging API.
 Your application still needs to have a logging backend (e.g., <a href="https://logging.apache.org/log4j/2.x">Log4j</a>) configured.</p>
 </div>
 </td>
 </tr>
 </table>
 </div>
 </div>
 </div>
 <div class="sect1">
 <h2 id="dependencies"><a class="anchor" href="#dependencies"></a>Dependencies</h2>
 <div class="sectionbody">
 <div class="paragraph">
 <p>You need to have the <code>org.apache.logging.log4j:log4j-api-scala</code> dependency in your classpath:</p>
 </div>
 <div class="listingblock">
 <div class="content">
 <pre class="highlightjs highlight"><code class="language-sbt hljs" data-lang="sbt">libraryDependencies ++= Seq(
   "org.apache.logging.log4j" %% "log4j-api-scala" % "13.2.0-SNAPSHOT"
 )</code></pre>
 </div>
 </div>
 <div class="paragraph">
 <p>Java module name is set to <code>org.apache.logging.log4j.api.scala</code>.
 OSGi <code>Bundle-SymbolicName</code>s are set to <code>org.apache.logging.log4j.api.scala.2.10</code>, <code>org.apache.logging.log4j.api.scala.2.11</code>, and so on.</p>
 </div>
 </div>
 </div>
 <div class="sect1">
 <h2 id="usage"><a class="anchor" href="#usage"></a>Usage</h2>
 <div class="sectionbody">
 <div class="paragraph">
 <p>Using the Scala API is as simple as mixing in the <code>Logging</code> trait to your class:</p>
 </div>
 <div class="listingblock">
 <div class="content">
 <pre class="highlightjs highlight"><code class="language-scala hljs" data-lang="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")
   }

   def doStuffWithUser(user: User): Unit = {
     logger.info(s"Doing stuff with ${user.getName}.")
   }

 }</code></pre>
 </div>
 </div>
 </div>
 </div>
 <div class="sect1">
 <h2 id="params"><a class="anchor" href="#params"></a>Parameter substitution</h2>
 <div class="sectionbody">
 <div class="paragraph">
 <p>Unlike in Java, Scala provides native functionality for string interpolation <a href="https://docs.scala-lang.org/overviews/core/string-interpolation.html">beginning in Scala 2.10</a>.
 As all logger calls are implemented as macros, using string interpolation directly does not require additional if checks:</p>
 </div>
 <div class="listingblock">
 <div class="content">
 <pre class="highlightjs highlight"><code class="language-scala hljs" data-lang="scala">logger.debug(s"Logging in user ${user.getName} with birthday ${user.calcBirthday}")</code></pre>
 </div>
 </div>
 </div>
 </div>
 <div class="sect1">
 <h2 id="logger-names"><a class="anchor" href="#logger-names"></a>Logger names</h2>
 <div class="sectionbody">
 <div class="paragraph">
 <p>Most logging implementations use a hierarchical scheme for matching logger names with logging configuration.
 In this scheme the logger name hierarchy is represented by <code>.</code> characters in the logger name, in a fashion very similar to the hierarchy used for Java/Scala package names.
 The <code>Logger</code> property added by the <code>Logging</code> trait follows this convention: the trait ensures the <code>Logger</code> is automatically named according to the class it is being used in.</p>
 </div>
 </div>
 </div>
 </article>
   </div>
 </main>
 </div>
 <footer class="footer">
   <p>
     Copyright © 1999-2024 <a href="https://www.apache.org/">The Apache Software Foundation</a>.
     Licensed under the <a href="https://www.apache.org/licenses/LICENSE-2.0">Apache Software License, Version 2.0</a>.
     Please read our <a href="https://privacy.apache.org/policies/privacy-policy-public.html">privacy policy</a>.
   </p>
   <p>
     Apache, Log4j, and the Apache feather logo are trademarks or registered trademarks of The Apache Software Foundation.
     Oracle and Java are registered trademarks of Oracle and/or its affiliates.
     Other names may be trademarks of their respective owners.
   </p>
 </footer>
 <script id="site-script" src="./_/js/site.js" data-ui-root-path="./_"></script>
 <script async src="./_/js/vendor/highlight.js"></script>
 <!-- `@asciidoctor/tabs` extension scripts -->
 <script async src="./_/js/vendor/tabs.js"></script>
   </body>
 </html>
	<!DOCTYPE html>
	<html lang="en">
	<head>
	<meta charset="utf-8">
	<meta name="viewport" content="width=device-width,initial-scale=1">
	<title>Log4j Scala API :: Apache Log4j Scala</title>
	<link rel="canonical" href="https://logging.apache.org/log4j/scala/index.html">
	<meta name="generator" content="Antora 3.2.0-alpha.4">
	<link rel="stylesheet" href="./_/css/site.css">
	<link rel="icon" href="./_/../_images/favicon.ico" type="image/x-icon">
	<!-- `@asciidoctor/tabs` extension styles -->
	<link rel="stylesheet" href="./_/css/vendor/tabs.css">
	<style>
	/* Default `h4` and `h5` are smaller than the normal text, fix header font sizing: */
	.doc h1 { font-size: 1.9rem; }
	.doc h2 { font-size: 1.7rem; }
	.doc h3 { font-size: 1.5rem; font-weight: 400; }
	.doc h4 { font-size: 1.3rem; font-weight: 500; }
	.doc h5 { font-size: 1.1rem; font-weight: 500; text-decoration: underline; }
	/* Default `code`, `pre`, and `.colist` (source code annotations) fonts are too big, adjust them: */
	.doc .colist>table code, .doc p code, .doc thead code { font-size: 0.8em; }
	.doc pre { font-size: 0.7rem; }
	.doc .colist { font-size: 0.75rem; }
	/* Make links more visible: */
	.doc a { text-decoration: underline; }
	.doc a code { text-decoration: underline; color: #1565c0; }
	/* Tab header fonts aren't rendered good, adjusting the font weight: */
	.tablist > ul li { font-weight: 500; }
	/* `page-toclevels` greater than 4 are not supported by Antora UI, patching it: */
	.toc .toc-menu li[data-level="4"] a {
	padding-left: 2.75rem;
	}
	/* Replace the default highlight.js color for strings from red (unnecessarily signaling something negative) to green: */
	.hljs-string {
	color: #0f8532;
	}
	</style>
	</head>
	<body class="article">
	<header class="header">
	<nav class="navbar">
	<div class="navbar-brand">
	<span class="navbar-item title">Apache Log4j Scala</span>
	</div>
	<div id="topbar-nav" class="navbar-menu">
	<div class="navbar-end">
	<a class="navbar-item" href="https://logging.apache.org">a subproject of <strong>Apache Logging Services</strong></a>
	</div>
	</div>
	</nav>
	</header>
	<div class="body">
	<div class="nav-container" data-component="ROOT" data-version="">
	<aside class="nav">
	<div class="panels">
	<div class="nav-panel-menu is-active" data-panel="menu">
	<nav class="nav-menu">
	<button class="nav-menu-toggle" aria-label="Toggle expand/collapse all" style="display: none"></button>
	<h3 class="title"><a href="index.html">Home</a></h3>
	<ul class="nav-list">
	<li class="nav-item" data-depth="0">
	<ul class="nav-list">
	<li class="nav-item" data-depth="1">
	<a class="nav-link" href="development.html">Development</a>
	</li>
	<li class="nav-item" data-depth="1">
	<a class="nav-link" href="release-notes.html">Release notes</a>
	</li>
	<li class="nav-item" data-depth="1">
	<a class="nav-link" href="https://logging.apache.org/download.html">Download</a>
	</li>
	<li class="nav-item" data-depth="1">
	<a class="nav-link" href="https://logging.apache.org/support.html">Support</a>
	</li>
	<li class="nav-item" data-depth="1">
	<a class="nav-link" href="https://logging.apache.org/security.html">Security</a>
	</li>
	</ul>
	</li>
	</ul>
	</nav>
	</div>
	</div>
	</aside>
	</div>
	<main class="article">
	<div class="toolbar" role="navigation">
	<button class="nav-toggle"></button>
	<a href="index.html" class="home-link is-current"></a>
	<nav class="breadcrumbs" aria-label="breadcrumbs">
	<ul>
	<li><a href="index.html">Home</a></li>
	<li><a href="index.html">Log4j Scala API</a></li>
	</ul>
	</nav>
	<div class="edit-this-page"><a href="https://github.com/apache/logging-log4j-scala/edit/main/src/site/antora/modules/ROOT/pages/index.adoc">Edit this Page</a></div>
	</div>
	<div class="content">
	<aside class="toc sidebar" data-title="Contents" data-levels="2">
	<div class="toc-menu"></div>
	</aside>
	<article class="doc">
	<h1 class="page">Log4j Scala API</h1>
	<div id="preamble">
	<div class="sectionbody">
	<div class="paragraph">
	<p>Log4j Scala API provides a Scala-friendly interface to log against <a href="https://logging.apache.org/log4j/2.x/manual/api-separation.html">the Log4j API</a>.
	It supports Scala <code>2.10</code>, <code>2.11</code>, <code>2.12</code>, <code>2.13</code>, and <code>3</code>.</p>
	</div>
	<div class="admonitionblock important">
	<table>
	<tr>
	<td class="icon">
	<i class="fa icon-important" title="Important"></i>
	</td>
	<td class="content">
	<div class="paragraph">
	<p>This is just a logging API.
	Your application still needs to have a logging backend (e.g., <a href="https://logging.apache.org/log4j/2.x">Log4j</a>) configured.</p>
	</div>
	</td>
	</tr>
	</table>
	</div>
	</div>
	</div>
	<div class="sect1">
	<h2 id="dependencies"><a class="anchor" href="#dependencies"></a>Dependencies</h2>
	<div class="sectionbody">
	<div class="paragraph">
	<p>You need to have the <code>org.apache.logging.log4j:log4j-api-scala</code> dependency in your classpath:</p>
	</div>
	<div class="listingblock">
	<div class="content">
	<pre class="highlightjs highlight"><code class="language-sbt hljs" data-lang="sbt">libraryDependencies ++= Seq(
	"org.apache.logging.log4j" %% "log4j-api-scala" % "13.2.0-SNAPSHOT"
	)</code></pre>
	</div>
	</div>
	<div class="paragraph">
	<p>Java module name is set to <code>org.apache.logging.log4j.api.scala</code>.
	OSGi <code>Bundle-SymbolicName</code>s are set to <code>org.apache.logging.log4j.api.scala.2.10</code>, <code>org.apache.logging.log4j.api.scala.2.11</code>, and so on.</p>
	</div>
	</div>
	</div>
	<div class="sect1">
	<h2 id="usage"><a class="anchor" href="#usage"></a>Usage</h2>
	<div class="sectionbody">
	<div class="paragraph">
	<p>Using the Scala API is as simple as mixing in the <code>Logging</code> trait to your class:</p>
	</div>
	<div class="listingblock">
	<div class="content">
	<pre class="highlightjs highlight"><code class="language-scala hljs" data-lang="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")
	}

	def doStuffWithUser(user: User): Unit = {
	logger.info(s"Doing stuff with ${user.getName}.")
	}

	}</code></pre>
	</div>
	</div>
	</div>
	</div>
	<div class="sect1">
	<h2 id="params"><a class="anchor" href="#params"></a>Parameter substitution</h2>
	<div class="sectionbody">
	<div class="paragraph">
	<p>Unlike in Java, Scala provides native functionality for string interpolation <a href="https://docs.scala-lang.org/overviews/core/string-interpolation.html">beginning in Scala 2.10</a>.
	As all logger calls are implemented as macros, using string interpolation directly does not require additional if checks:</p>
	</div>
	<div class="listingblock">
	<div class="content">
	<pre class="highlightjs highlight"><code class="language-scala hljs" data-lang="scala">logger.debug(s"Logging in user ${user.getName} with birthday ${user.calcBirthday}")</code></pre>
	</div>
	</div>
	</div>
	</div>
	<div class="sect1">
	<h2 id="logger-names"><a class="anchor" href="#logger-names"></a>Logger names</h2>
	<div class="sectionbody">
	<div class="paragraph">
	<p>Most logging implementations use a hierarchical scheme for matching logger names with logging configuration.
	In this scheme the logger name hierarchy is represented by <code>.</code> characters in the logger name, in a fashion very similar to the hierarchy used for Java/Scala package names.
	The <code>Logger</code> property added by the <code>Logging</code> trait follows this convention: the trait ensures the <code>Logger</code> is automatically named according to the class it is being used in.</p>
	</div>
	</div>
	</div>
	</article>
	</div>
	</main>
	</div>
	<footer class="footer">
	<p>
	Copyright © 1999-2024 <a href="https://www.apache.org/">The Apache Software Foundation</a>.
	Licensed under the <a href="https://www.apache.org/licenses/LICENSE-2.0">Apache Software License, Version 2.0</a>.
	Please read our <a href="https://privacy.apache.org/policies/privacy-policy-public.html">privacy policy</a>.
	</p>
	<p>
	Apache, Log4j, and the Apache feather logo are trademarks or registered trademarks of The Apache Software Foundation.
	Oracle and Java are registered trademarks of Oracle and/or its affiliates.
	Other names may be trademarks of their respective owners.
	</p>
	</footer>
	<script id="site-script" src="./_/js/site.js" data-ui-root-path="./_"></script>
	<script async src="./_/js/vendor/highlight.js"></script>
	<!-- `@asciidoctor/tabs` extension scripts -->
	<script async src="./_/js/vendor/tabs.js"></script>
	</body>
	</html>