blob: ec8825f59892756eb3a2fb6f66bbd01c1fba26f5 [file] [log] [blame]
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="utf-8">
<meta http-equiv="X-UA-Compatible" content="IE=edge">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<!-- This is broken by doc revisioning.
-->
<link rel="shortcut icon" href="../../../../img/favicon.ico">
<title>toc - Apache Mynewt</title>
<link href="../../../../css/bootstrap-3.0.3.min.css" rel="stylesheet">
<link rel="stylesheet" href="../../../../css/highlight.css">
<link href="../../../../css/base.css" rel="stylesheet">
<link href="../../../../css/custom.css" rel="stylesheet">
<link href="../../../../css/v2.css" rel="stylesheet">
<link href="https://fonts.googleapis.com/css?family=Lato" rel="stylesheet">
<link rel="stylesheet" href="https://maxcdn.bootstrapcdn.com/font-awesome/4.5.0/css/font-awesome.min.css">
<!-- HTML5 shim and Respond.js IE8 support of HTML5 elements and media queries -->
<!--[if lt IE 9]>
<script src="https://oss.maxcdn.com/libs/html5shiv/3.7.0/html5shiv.js"></script>
<script src="https://oss.maxcdn.com/libs/respond.js/1.3.0/respond.min.js"></script>
<![endif]-->
<script>
(function(i, s, o, g, r, a, m) {
i["GoogleAnalyticsObject"] = r;
(i[r] =
i[r] ||
function() {
(i[r].q = i[r].q || []).push(arguments);
}),
(i[r].l = 1 * new Date());
(a = s.createElement(o)), (m = s.getElementsByTagName(o)[0]);
a.async = 1;
a.src = g;
m.parentNode.insertBefore(a, m);
})(window, document, "script", "//www.google-analytics.com/analytics.js", "ga");
ga("create", "UA-72162311-1", "auto");
ga("send", "pageview");
</script>
</head>
<body class="toc">
<div class="container">
<div class="row v2-main-banner">
<a class="logo-cell" href="/">
<img class="logo" src="/img/logo.png">
</a>
<div class="tagline-cell">
<h4 class="tagline">An OS to build, deploy and securely manage billions of devices</h4>
</div>
<div class="news-cell">
<div class="well">
<h4>Latest News:</h4> <a href="/download">Apache Mynewt 1.11.0, Apache NimBLE 1.6.0 </a> released (September 7, 2023)
</div>
</div>
</div>
</div>
<nav id="navbar" class="navbar navbar-inverse affix-top" data-spy="affix" data-offset-top="150" role="navigation">
<div class="container">
<!-- Collapsed navigation -->
<div class="navbar-header">
<!-- Expander button -->
<button type="button" class="navbar-toggle" data-toggle="collapse" data-target=".navbar-collapse">
<span class="sr-only">Toggle navigation</span>
<span class="icon-bar"></span>
<span class="icon-bar"></span>
<span class="icon-bar"></span>
</button>
</div>
<!-- Expanded navigation -->
<div class="navbar-collapse collapse">
<!-- Main navigation -->
<ul class="nav navbar-nav navbar-right">
<li
class=""
>
<a href="/"><i class="fa fa-home" style="font-size: larger;"></i></a>
</li>
<li
class="important"
>
<a href="/quick-start/">Quick Start</a>
</li>
<li
class=""
>
<a href="/about/">About</a>
</li>
<li
class=""
>
<a href="/talks/">Talks</a>
</li>
<li
class="active"
>
<a href="/documentation/">Documentation</a>
</li>
<li
class=""
>
<a href="/download/">Download</a>
</li>
<li
class=""
>
<a href="/community/">Community</a>
</li>
<li
class=""
>
<a href="/events/">Events</a>
</li>
</ul>
</div>
</div>
</nav>
<div class="container">
<div class="row">
<div class="col-md-3 v2-sidebar sidebar-container"><div id="docSidebar" class="hidden-print" role="complementary">
<div class="top">
<div role="search">
<form id="rtd-search-form" class="wy-form" action="../../../../search.html" method="get">
<div class="form-group">
<input type="text" name="q" class="form-control" placeholder="Search documentation" />
</div>
</form>
</div>
</div>
<ul class="toc-nav">
<li class="doc-version"><select class="form-control" onchange="if (this.value) window.location.href=this.value">
<option value="/latest">
Version: master
</option>
<option value="/v1_11_0/" >
Version: 1.11.0
</option>
<option value="/v1_10_0/" >
Version: 1.10.0
</option>
<option value="/v1_9_0/" >
Version: 1.9.0
</option>
<option value="/v1_8_0/" >
Version: 1.8.0
</option>
<option value="/v1_7_0/" >
Version: 1.7.0
</option>
<option value="/v1_6_0/" >
Version: 1.6.0
</option>
<option value="/v1_5_0/" >
Version: 1.5.0
</option>
<option value="/v1_4_0/" >
Version: 1.4.0
</option>
<option value="/v1_3_0/os/introduction" >
Version: 1.3.0
</option>
<option value="/v1_2_0/os/introduction" >
Version: 1.2.0
</option>
<option value="/v1_1_0/os/introduction" >
Version: 1.1.0
</option>
<option value="/v1_0_0/os/introduction" >
Version: 1.0.0
</option>
<option value="/v0_9_0/os/introduction" selected="selected" >
Version: 0.9.0
</option>
</select></li>
<li ><a href="../../../introduction/">Mynewt Documentation</a>
<ul>
<li ><a href="../../../get_started/get_started/">Basic Setup</a>
</li>
<li >
<a href="../../../get_started/vocabulary/">Concepts</a>
</li>
<li ><a href="../../../tutorials/tutorials/">Tutorials</a>
</li>
<li ><a href="../../../os_user_guide/">OS User Guide</a>
<ul>
<li ><a href="../../../core_os/mynewt_os/">OS Core</a>
</li>
<li ><a href="../../../core_os/porting/port_os/">Porting to your Platform</a>
</li>
<li ><a href="../../console/console/">Console</a>
</li>
<li ><a href="../../shell/shell/">Shell</a>
</li>
<li ><a href="../../bootloader/bootloader/">Bootloader</a>
</li>
<li><a href="
../../fs/fs/fs/
">File System</a>
</li>
<li ><a href="../../hal/hal/">Hardware Abstraction Layer</a>
</li>
<li ><a href="../../testutil/testutil/">Test Utilities</a>
</li>
<li ><a href="../../imgmgr/imgmgr/">Image Manager</a>
</li>
<li >
<a href="../../baselibc/">Baselibc library</a>
</li>
<li ><a href="../../elua/elua/">Embedded Lua</a>
</li>
<li ><a href="../../json/json/">JSON</a>
</li>
<li ><a href="../../stats/stats/">Stats</a>
</li>
<li class="active"><a href="./">Logs</a>
<ul>
</ul>
</li>
</ul>
</li>
<li><a href="
../../../../network/ble/ble_intro/
">BLE User Guide</a>
</li>
<li ><a href="../../../../newt/newt_intro/">Newt Tool Guide</a>
</li>
<li ><a href="../../../../newtmgr/overview/">Newt Manager Guide</a>
</li>
<li >
<a href="../../../../known_issues/">Known Issues</a>
</li>
</ul>
</li>
<li><a href="
../../../../faq/how_to_edit_docs/
">Appendix</a>
</li>
</ul>
</div></div>
<div class="col-md-9" role="main">
<div class="doc-header">
<div role="navigation" aria-label="breadcrumbs navigation">
<ul class="wy-breadcrumbs">
<li><a href="/documentation/">Docs</a></li>
<li>&raquo; Logs</li>
<li>&raquo; <a href="os/os_user_guide/">OS User Guide</a></li>
<li>&raquo; <a href="os/introduction/">Mynewt Documentation</a></li>
</ul>
</div>
</div>
<div class="alert alert-warning">
<p>
Version 0.9.0 is not the most recent version of the Apache Mynewt
documentation. Click <a href="/latest">here</a> to read the latest
version.
</p>
</div>
<h2 id="mynewt-logging">Mynewt Logging</h2>
<p>Apache Mynewt has a logging package (<code>apache-mynewt-core/sys/log</code>) to support
logging of information within a Mynewt application.</p>
<p><br></p>
<h3 id="description">Description</h3>
<p>Logging API is provided in <code>apache-mynewt-core/sys/log/include/log/log.h</code>.</p>
<p>It allows packages to define their own log streams with separate
names. It also allows an application to control the output destinations
of logs. </p>
<p><br></p>
<h4 id="compile-time-settings">Compile Time Settings</h4>
<p>To save space at compile time, there is a compile time log level that
includes/excludes certain logs at compile time, saving image space. For
example, during debug, you can have significant logs present, but disable
these at compile time to ensure the code size limits are met.</p>
<p>A compiler flag <code>LOG_LEVEL</code> can be set in your <code>target.cflags</code> or within
your app <code>pkg.cflags</code> files to set the compile time log level. The
log level are defined in <code>apache-mynewt-core/sys/log/include/log/log.h</code>
but must be added by number to your <code>yml</code> file.</p>
<p>For example:</p>
<div class="codehilite" style="background: #ffffff"><pre style="line-height: 125%;"><span></span><code> pkg.cflags -DLOG_LEVEL=8
</code></pre></div>
<p>or </p>
<div class="codehilite" style="background: #ffffff"><pre style="line-height: 125%;"><span></span><code> newt target set my_target cflags=-DLOG_LEVEL=8
</code></pre></div>
<p>would both set the compile-time log level to <code>LOG_LEVEL_ERROR</code>. All logs
of less than <code>LOG_LEVEL_ERROR</code> severity would be disabled at compile
time and take no space within the Mynewt application image.</p>
<p>These compile time settings are applicable to all logs registered with the
system.</p>
<p><br></p>
<h3 id="log">Log</h3>
<p>Each log stream requires a log structure to define its logging properties.
It is typical for modules to extern this structure.</p>
<p><br></p>
<h3 id="log-handler">Log Handler</h3>
<p>To use logs, a log-handler is required, which is responsible for handling
the I/O from the log. The log package comes with two pre-built log handlers.</p>
<ul>
<li>console -- streams log events directly to the console port. Does
not support walking and reading.</li>
<li>cbmem -- writes/reads log events to a circular buffer. Supports walking
and reading for access by <code>newtmgr</code> and shell commands.</li>
</ul>
<p>In addition, it is possible to create custom log handlers for other methods.
Examples may include</p>
<ul>
<li>Flash file system</li>
<li>Flat flash buffer</li>
<li>Streamed over some other interface</li>
</ul>
<p>To use logging, you will not typically need to create your own log handler.
You can use one of the two supplied above. </p>
<p>In Mynewt today, each module will register its logs with a default log handler.
Its up to the application to use or override this log handler for its
specific purposes. See below for an example.</p>
<p><br></p>
<h3 id="typical-use-of-logging-when-writing-an-application">Typical use of logging when writing an application</h3>
<p>When writing an application that is using other's log modules, you
may want to override their log handlers and log levels.</p>
<p>Add the logging to your package file.</p>
<div class="codehilite" style="background: #ffffff"><pre style="line-height: 125%;"><span></span><code> pkg.deps:
- &quot;@apache-mynewt-core/sys/log&quot;
</code></pre></div>
<p><br></p>
<p>Initialize the logs in your startup code. It may look like this </p>
<div class="codehilite" style="background: #ffffff"><pre style="line-height: 125%;"><span></span><code><span style="color: #633820">#include</span> <span style="color: #177500">&lt;module1/module1.h&gt;</span>
<span style="color: #633820">#include</span> <span style="color: #177500">&lt;module3/module2.h&gt;</span>
<span style="color: #633820">#include</span> <span style="color: #177500">&lt;module3/module3.h&gt;</span>
<span style="color: #633820">#include</span> <span style="color: #177500">&lt;log/log.h&gt;</span>
<span style="color: #177500">/* log to console */</span>
<span style="color: #A90D91">static</span> <span style="color: #A90D91">struct</span> <span style="color: #3F6E75">log_handler</span> <span style="color: #000000">app_log_handler</span>;
<span style="color: #177500">/* this has to be after all the modules are </span>
<span style="color: #177500"> * initialized and have registered</span>
<span style="color: #177500"> * their log modules */</span>
<span style="color: #A90D91">void</span> <span style="color: #000000">app_log_init</span>(<span style="color: #A90D91">void</span>)
{
<span style="color: #177500">/* create a log handler for all logs . FOr this application</span>
<span style="color: #177500"> ** send them directly to the console port */</span>
<span style="color: #000000">log_console_handler_init</span>(<span style="color: #000000">&amp;app_log_handler</span>);
...
<span style="color: #177500">/* set up logging for the modules appropriately */</span>
<span style="color: #000000">module1_log</span>.<span style="color: #000000">log_level</span> <span style="color: #000000">=</span> <span style="color: #000000">LOG_LEVEL_WARN</span>;
<span style="color: #000000">module2_log</span>.<span style="color: #000000">log_level</span> <span style="color: #000000">=</span> <span style="color: #000000">LOG_LEVEL_INFO</span>;
<span style="color: #000000">module3_log</span>.<span style="color: #000000">log_level</span> <span style="color: #000000">=</span> <span style="color: #000000">LOG_LEVEL_DEBUG</span>;
<span style="color: #177500">/* set up a single handler for all modules */</span>
<span style="color: #000000">module1_log</span>.<span style="color: #000000">log_handler</span> <span style="color: #000000">=</span> <span style="color: #000000">&amp;app_log_handler</span>;
<span style="color: #000000">module2_log</span>.<span style="color: #000000">log_handler</span> <span style="color: #000000">=</span> <span style="color: #000000">&amp;app_log_handler</span>;
<span style="color: #000000">module3_log</span>.<span style="color: #000000">log_handler</span> <span style="color: #000000">=</span> <span style="color: #000000">&amp;app_log_handler</span>;
}
</code></pre></div>
<p><br></p>
<h3 id="typical-use-of-logging-when-writing-a-module">Typical use of Logging when writing a module</h3>
<p>When creating a package using its own logging, you can have this type of
structure. </p>
<div class="codehilite" style="background: #ffffff"><pre style="line-height: 125%;"><span></span><code><span style="color: #177500">/* my_package.h*/</span>
<span style="color: #177500">/* pick a unique name here */</span>
<span style="color: #A90D91">extern</span> <span style="color: #A90D91">struct</span> <span style="color: #3F6E75">log</span> <span style="color: #000000">my_log</span>;
</code></pre></div>
<p><br></p>
<p>with an implementation in your module that looks like this: </p>
<div class="codehilite" style="background: #ffffff"><pre style="line-height: 125%;"><span></span><code><span style="color: #177500">/* my_package.c */</span>
<span style="color: #A90D91">struct</span> <span style="color: #3F6E75">log_handler</span> <span style="color: #000000">log_console_handler</span>;
<span style="color: #A90D91">struct</span> <span style="color: #3F6E75">log</span> <span style="color: #000000">my_log</span>;
{
...
<span style="color: #177500">/* create a default handler for this log stream */</span>
<span style="color: #000000">log_console_handler_init</span>(<span style="color: #000000">&amp;log_console_handler</span>);
<span style="color: #177500">/* register my log with a name to the system */</span>
<span style="color: #000000">log_register</span>(<span style="color: #C41A16">&quot;log&quot;</span>, <span style="color: #000000">&amp;my_log</span>, <span style="color: #000000">&amp;log_console_handler</span>);
<span style="color: #177500">/* set up default log level for my package */</span>
<span style="color: #000000">my_log</span>.<span style="color: #000000">log_level</span> <span style="color: #000000">=</span> <span style="color: #000000">LOG_LEVEL_DEBUG</span>;
<span style="color: #000000">LOG_DEBUG</span>(<span style="color: #000000">&amp;my_log</span>, <span style="color: #000000">LOG_MODULE_DEFAULT</span>, <span style="color: #C41A16">&quot;bla&quot;</span>);
<span style="color: #000000">LOG_DEBUG</span>(<span style="color: #000000">&amp;my_log</span>, <span style="color: #000000">LOG_MODULE_DEFAULT</span>, <span style="color: #C41A16">&quot;bab&quot;</span>);
}
</code></pre></div>
<div class="row">
<ul class="nav nav-pills" style="margin-bottom: 10px">
<li>
</li>
<li class="pull-right">
</li>
</ul>
</div>
<footer class="row">
<div class="col-xs-12">
<p class="copyright">Apache Mynewt (incubating) is available under Apache License, version 2.0.</p>
</div>
<div class="col-xs-12">
<div class="logos">
<a href="https://www.apache.org/">
<img src="/img/asf_logo_wide_small.png" alt="Apache" title="Apache">
</a>
<p>
Copyright © 2015-2021 The Apache Software Foundation.<br>
<small class="footnote">
Apache Mynewt, Mynewt, Apache, the Apache feather logo, and the Apache Mynewt
project logo are either registered trademarks or trademarks of the Apache
Software Foundation in the United States and other countries.
</small>
</p>
<a href="">
<img src="https://www.countit.com/images/add_to_slack.png" alt="Slack Icon" title="Join our Slack Community" />
</a>
</div>
</div>
<a href="https://www.apache.org/licenses/">
<button class="button-footer-asf">
License
</button>
</a>
<a href="https://www.apache.org/foundation/sponsorship.html">
<button class="button-footer-asf">
Sponsorship
</button>
</a>
<a href="https://www.apache.org/foundation/thanks.html">
<button class="button-footer-asf">
Thanks
</button>
</a>
<a href="https://www.apache.org/security/">
<button class="button-footer-asf">
Security
</button>
</a>
<a href="https://apache.org/events/current-event">
<button class="button-footer-asf">
ASF Events
</button>
</a>
</footer>
</div>
</div>
</div>
<script src="../../../../js/jquery-1.10.2.min.js"></script>
<script src="../../../../js/bootstrap-3.0.3.min.js"></script>
<script src="../../../../js/highlight.pack.js"></script>
<script src="../../../../js/base.js"></script>
<script src="../../../../js/custom.js"></script>
<script src="search/main.js"></script>
</body>
</html>