docs/1.2/admin-guide/monitoring-tracing-config/index.html - gerrit/www.eclipse.org/hono - Git at Google

 <!DOCTYPE html>
 <html lang="1.2" class="js csstransforms3d">
   <head>
     <meta charset="utf-8">
     <meta name="viewport" content="width=device-width, initial-scale=1.0">
     <meta name="generator" content="Hugo 0.81.0" />
     <meta name="description" content="A set of micro-services for connecting millions of devices.">
 <meta name="author" content="The Eclipse Hono Project">

     <link rel="apple-touch-icon" sizes="180x180" href="/hono/docs/favicon/apple-touch-icon.png">
 <link rel="icon" type="image/png" sizes="48x48" href="/hono/docs/favicon/favicon-48x48.png">
 <link rel="icon" type="image/png" sizes="32x32" href="/hono/docs/favicon/favicon-32x32.png">
 <link rel="icon" type="image/png" sizes="16x16" href="/hono/docs/favicon/favicon-16x16.png">
 <link rel="manifest" href="/hono/docs/favicon/site.webmanifest">
 <link rel="mask-icon" href="/hono/docs/favicon/safari-pinned-tab.svg" color="#5bbad5">
 <link rel="shortcut icon" href="/hono/docs/favicon/favicon.ico">
 <meta name="msapplication-TileColor" content="#da532c">
 <meta name="msapplication-config" content="/hono/docs/favicon/browserconfig.xml">
 <meta name="theme-color" content="#ffffff">

     <title>Monitoring & Tracing :: Eclipse Hono&trade; Vers.: 1.2</title>


     <link href="/hono/docs/css/nucleus.css?1626138730" rel="stylesheet">
     <link href="/hono/docs/css/fontawesome-all.min.css?1626138730" rel="stylesheet">
     <link href="/hono/docs/css/hybrid.css?1626138730" rel="stylesheet">
     <link href="/hono/docs/css/featherlight.min.css?1626138730" rel="stylesheet">
     <link href="/hono/docs/css/perfect-scrollbar.min.css?1626138730" rel="stylesheet">
     <link href="/hono/docs/css/auto-complete.css?1626138730" rel="stylesheet">
     <link href="/hono/docs/css/atom-one-dark-reasonable.css?1626138730" rel="stylesheet">
     <link href="/hono/docs/css/theme.css?1626138730" rel="stylesheet">
     <link href="/hono/docs/css/hugo-theme.css?1626138730" rel="stylesheet">

     <link href="/hono/docs/css/theme-hono.css?1626138730" rel="stylesheet">

     <link href="/hono/docs/css/hono.css?1626138730" rel="stylesheet">

     <script src="/hono/docs/js/jquery-3.3.1.min.js?1626138730"></script>

     <style>
       :root #header + #content > #left > #rlblock_left{
           display:none !important;
       }

         :not(pre) > code + span.copy-to-clipboard {
             display: none;
         }

     </style>

 <link rel="stylesheet" href="https://www.eclipse.org/eclipse.org-common/themes/solstice/public/stylesheets/vendor/cookieconsent/cookieconsent.min.css">


 <meta name="twitter:card" content="summary_large_image">
 <meta name="twitter:site" content="@EclipseHono">
 <meta name="twitter:title" content="Monitoring &amp; Tracing :: Eclipse Hono&amp;trade; Vers.: 1.2">
 <meta name="twitter:image" content="https://www.eclipse.org/hono/docs/images/twitter_image.png">
 <meta name="twitter:description" content="A set of micro-services for connecting millions of devices.">


 <meta property="og:title" content="Monitoring &amp; Tracing :: Eclipse Hono&amp;trade; Vers.: 1.2" />
 <meta property="og:type" content="website" />
 <meta property="og:url" content="https://www.eclipse.org/hono/docs/1.2/admin-guide/monitoring-tracing-config//" />
 <meta property="og:image" content="https://www.eclipse.org/hono/docs/images/twitter_image.png" />

   </head>
   <body class="" data-url="/hono/docs/1.2/admin-guide/monitoring-tracing-config/">
     <nav id="sidebar" class="">


   <div id="header-wrapper">
     <div id="header">
       <a href="https://www.eclipse.org/hono/">
     <img src="/hono/docs/images/HONO-Logo_Bild-Wort_quer-w-310x120px.svg" alt="Hono logo" class="logo-img">
 </a>

     </div>

         <div class="searchbox">
     <label for="search-by"><i class="fas fa-search"></i></label>
     <input data-search-input id="search-by" type="search" placeholder="Search...">
     <span data-search-clear=""><i class="fas fa-times"></i></span>
 </div>

 <script type="text/javascript" src="/hono/docs/js/lunr.min.js?1626138730"></script>
 <script type="text/javascript" src="/hono/docs/js/auto-complete.js?1626138730"></script>
 <script type="text/javascript">

         var baseurl = "https:\/\/www.eclipse.org\/hono\/docs\/\/1.2";

 </script>
 <script type="text/javascript" src="/hono/docs/js/search.js?1626138730"></script>


   </div>

     <div class="highlightable">
     <ul class="topics">


     <li data-nav-id="/hono/docs/1.2/concepts/" title="Concepts" class="dd-item


         ">
       <a href="/hono/docs/1.2/concepts/">
           <i class="far fa-lightbulb"></i> Concepts

       </a>


         <ul>


       <li data-nav-id="/hono/docs/1.2/concepts/device-identity/" title="Device Identity" class="dd-item ">
         <a href="/hono/docs/1.2/concepts/device-identity/">
         Device Identity

         </a>
     </li>


       <li data-nav-id="/hono/docs/1.2/concepts/tenancy/" title="Multi-Tenancy" class="dd-item ">
         <a href="/hono/docs/1.2/concepts/tenancy/">
         Multi-Tenancy

         </a>
     </li>


       <li data-nav-id="/hono/docs/1.2/concepts/device-provisioning/" title="Device Provisioning" class="dd-item ">
         <a href="/hono/docs/1.2/concepts/device-provisioning/">
         Device Provisioning

         </a>
     </li>


       <li data-nav-id="/hono/docs/1.2/concepts/connecting-devices/" title="Connecting Devices" class="dd-item ">
         <a href="/hono/docs/1.2/concepts/connecting-devices/">
         Connecting Devices

         </a>
     </li>


       <li data-nav-id="/hono/docs/1.2/concepts/device-notifications/" title="Device Notifications" class="dd-item ">
         <a href="/hono/docs/1.2/concepts/device-notifications/">
         Device Notifications

         </a>
     </li>


       <li data-nav-id="/hono/docs/1.2/concepts/command-and-control/" title="Command &amp; Control" class="dd-item ">
         <a href="/hono/docs/1.2/concepts/command-and-control/">
         Command &amp; Control

         </a>
     </li>


       <li data-nav-id="/hono/docs/1.2/concepts/resource-limits/" title="Resource limits" class="dd-item ">
         <a href="/hono/docs/1.2/concepts/resource-limits/">
         Resource limits

         </a>
     </li>


       <li data-nav-id="/hono/docs/1.2/concepts/connection-events/" title="Connection Events" class="dd-item ">
         <a href="/hono/docs/1.2/concepts/connection-events/">
         Connection Events

         </a>
     </li>


         </ul>

     </li>


     <li data-nav-id="/hono/docs/1.2/user-guide/" title="User Guide" class="dd-item


         ">
       <a href="/hono/docs/1.2/user-guide/">
           <i class="fas fa-book-reader"></i> User Guide

       </a>


         <ul>


       <li data-nav-id="/hono/docs/1.2/user-guide/device-registry/" title="Device Registry" class="dd-item ">
         <a href="/hono/docs/1.2/user-guide/device-registry/">
         Device Registry

         </a>
     </li>


       <li data-nav-id="/hono/docs/1.2/user-guide/http-adapter/" title="HTTP Adapter" class="dd-item ">
         <a href="/hono/docs/1.2/user-guide/http-adapter/">
         HTTP Adapter

         </a>
     </li>


       <li data-nav-id="/hono/docs/1.2/user-guide/mqtt-adapter/" title="MQTT Adapter" class="dd-item ">
         <a href="/hono/docs/1.2/user-guide/mqtt-adapter/">
         MQTT Adapter

         </a>
     </li>


       <li data-nav-id="/hono/docs/1.2/user-guide/amqp-adapter/" title="AMQP Adapter" class="dd-item ">
         <a href="/hono/docs/1.2/user-guide/amqp-adapter/">
         AMQP Adapter

         </a>
     </li>


       <li data-nav-id="/hono/docs/1.2/user-guide/coap-adapter/" title="CoAP Adapter" class="dd-item ">
         <a href="/hono/docs/1.2/user-guide/coap-adapter/">
         CoAP Adapter

         </a>
     </li>


       <li data-nav-id="/hono/docs/1.2/user-guide/kura-adapter/" title="Kura Adapter" class="dd-item ">
         <a href="/hono/docs/1.2/user-guide/kura-adapter/">
         Kura Adapter

         </a>
     </li>


       <li data-nav-id="/hono/docs/1.2/user-guide/sigfox-adapter/" title="Sigfox Adapter" class="dd-item ">
         <a href="/hono/docs/1.2/user-guide/sigfox-adapter/">
         Sigfox Adapter

         </a>
     </li>


       <li data-nav-id="/hono/docs/1.2/user-guide/jmeter_load_tests/" title="Load Tests with JMeter" class="dd-item ">
         <a href="/hono/docs/1.2/user-guide/jmeter_load_tests/">
         Load Tests with JMeter

         </a>
     </li>


         </ul>

     </li>


     <li data-nav-id="/hono/docs/1.2/admin-guide/" title="Admin Guide" class="dd-item
         parent


         ">
       <a href="/hono/docs/1.2/admin-guide/">
           <i class="fas fa-sliders-h"></i> Admin Guide

       </a>


         <ul>


       <li data-nav-id="/hono/docs/1.2/admin-guide/common-config/" title="Common Configuration" class="dd-item ">
         <a href="/hono/docs/1.2/admin-guide/common-config/">
         Common Configuration

         </a>
     </li>


       <li data-nav-id="/hono/docs/1.2/admin-guide/auth-server-config/" title="Auth Server Configuration" class="dd-item ">
         <a href="/hono/docs/1.2/admin-guide/auth-server-config/">
         Auth Server Configuration

         </a>
     </li>


       <li data-nav-id="/hono/docs/1.2/admin-guide/device-registry-config/" title="Device Registry Configuration" class="dd-item ">
         <a href="/hono/docs/1.2/admin-guide/device-registry-config/">
         Device Registry Configuration

         </a>
     </li>


       <li data-nav-id="/hono/docs/1.2/admin-guide/device-connection-config/" title="Configuring the Device Connection Service" class="dd-item ">
         <a href="/hono/docs/1.2/admin-guide/device-connection-config/">
         Device Connection Service Configuration

         </a>
     </li>


       <li data-nav-id="/hono/docs/1.2/admin-guide/http-adapter-config/" title="HTTP Adapter Configuration" class="dd-item ">
         <a href="/hono/docs/1.2/admin-guide/http-adapter-config/">
         HTTP Adapter Configuration

         </a>
     </li>


       <li data-nav-id="/hono/docs/1.2/admin-guide/amqp-adapter-config/" title="AMQP Adapter Configuration" class="dd-item ">
         <a href="/hono/docs/1.2/admin-guide/amqp-adapter-config/">
         AMQP Adapter Configuration

         </a>
     </li>


       <li data-nav-id="/hono/docs/1.2/admin-guide/mqtt-adapter-config/" title="MQTT Adapter Configuration" class="dd-item ">
         <a href="/hono/docs/1.2/admin-guide/mqtt-adapter-config/">
         MQTT Adapter Configuration

         </a>
     </li>


       <li data-nav-id="/hono/docs/1.2/admin-guide/kura-adapter-config/" title="Kura Adapter Configuration" class="dd-item ">
         <a href="/hono/docs/1.2/admin-guide/kura-adapter-config/">
         Kura Adapter Configuration

         </a>
     </li>


       <li data-nav-id="/hono/docs/1.2/admin-guide/hono-client-configuration/" title="Hono Client Configuration" class="dd-item ">
         <a href="/hono/docs/1.2/admin-guide/hono-client-configuration/">
         Hono Client Configuration

         </a>
     </li>


       <li data-nav-id="/hono/docs/1.2/admin-guide/amqp-network-config/" title="AMQP 1.0 Messaging Network Configuration" class="dd-item ">
         <a href="/hono/docs/1.2/admin-guide/amqp-network-config/">
         AMQP 1.0 Messaging Network Configuration

         </a>
     </li>


       <li data-nav-id="/hono/docs/1.2/admin-guide/secure_communication/" title="Secure Communication" class="dd-item ">
         <a href="/hono/docs/1.2/admin-guide/secure_communication/">
         Secure Communication

         </a>
     </li>


       <li data-nav-id="/hono/docs/1.2/admin-guide/monitoring-tracing-config/" title="Monitoring &amp; Tracing" class="dd-item active">
         <a href="/hono/docs/1.2/admin-guide/monitoring-tracing-config/">
         Monitoring &amp; Tracing

         </a>
     </li>


         </ul>

     </li>


     <li data-nav-id="/hono/docs/1.2/dev-guide/" title="Developer Guide" class="dd-item


         ">
       <a href="/hono/docs/1.2/dev-guide/">
           <i class="fas fa-tools"></i> Developer Guide

       </a>


         <ul>


       <li data-nav-id="/hono/docs/1.2/dev-guide/building_hono/" title="Building from Source" class="dd-item ">
         <a href="/hono/docs/1.2/dev-guide/building_hono/">
         Building from Source

         </a>
     </li>


       <li data-nav-id="/hono/docs/1.2/dev-guide/amqp_adapter_client/" title="AMQP Adapter Client for Java" class="dd-item ">
         <a href="/hono/docs/1.2/dev-guide/amqp_adapter_client/">
         AMQP Adapter Client for Java

         </a>
     </li>


       <li data-nav-id="/hono/docs/1.2/dev-guide/java_client_consumer/" title="Consuming Messages from Java" class="dd-item ">
         <a href="/hono/docs/1.2/dev-guide/java_client_consumer/">
         Consuming Messages from Java

         </a>
     </li>


       <li data-nav-id="/hono/docs/1.2/dev-guide/custom_http_adapter/" title="Implement a Custom Hono HTTP Protocol Adapter" class="dd-item ">
         <a href="/hono/docs/1.2/dev-guide/custom_http_adapter/">
         Implement a Custom Hono HTTP Protocol Adapter

         </a>
     </li>


         </ul>

     </li>


     <li data-nav-id="/hono/docs/1.2/api/" title="API" class="dd-item


         ">
       <a href="/hono/docs/1.2/api/">
           &nbsp;<i class='fas fa-plug'></i>&nbsp;API

       </a>


         <ul>


       <li data-nav-id="/hono/docs/1.2/api/telemetry/" title="Telemetry API Specification" class="dd-item ">
         <a href="/hono/docs/1.2/api/telemetry/">
         Telemetry API

         </a>
     </li>


       <li data-nav-id="/hono/docs/1.2/api/event/" title="Event API Specification" class="dd-item ">
         <a href="/hono/docs/1.2/api/event/">
         Event API

         </a>
     </li>


       <li data-nav-id="/hono/docs/1.2/api/command-and-control/" title="Command &amp; Control API Specification" class="dd-item ">
         <a href="/hono/docs/1.2/api/command-and-control/">
         Command &amp; Control API

         </a>
     </li>


       <li data-nav-id="/hono/docs/1.2/api/tenant/" title="Tenant API Specification" class="dd-item ">
         <a href="/hono/docs/1.2/api/tenant/">
         Tenant API

         </a>
     </li>


       <li data-nav-id="/hono/docs/1.2/api/device-connection/" title="Device Connection API Specification" class="dd-item ">
         <a href="/hono/docs/1.2/api/device-connection/">
         Device Connection API

         </a>
     </li>


       <li data-nav-id="/hono/docs/1.2/api/device-registration/" title="Device Registration API Specification" class="dd-item ">
         <a href="/hono/docs/1.2/api/device-registration/">
         Device Registration API

         </a>
     </li>


       <li data-nav-id="/hono/docs/1.2/api/credentials/" title="Credentials API Specification" class="dd-item ">
         <a href="/hono/docs/1.2/api/credentials/">
         Credentials API

         </a>
     </li>


       <li data-nav-id="/hono/docs/1.2/api/authentication/" title="Authentication API Specification" class="dd-item ">
         <a href="/hono/docs/1.2/api/authentication/">
         Authentication API

         </a>
     </li>


       <li data-nav-id="/hono/docs/1.2/api/management/" title="Device Registry Management API Specification" class="dd-item ">
         <a href="/hono/docs/1.2/api/management/">
         Device Registry Management API

         </a>
     </li>


       <li data-nav-id="/hono/docs/1.2/api/metrics/" title="Metrics" class="dd-item ">
         <a href="/hono/docs/1.2/api/metrics/">
         Metrics

         </a>
     </li>


         </ul>

     </li>


     <li data-nav-id="/hono/docs/1.2/deployment/" title="Deployment" class="dd-item


         ">
       <a href="/hono/docs/1.2/deployment/">
           <i class="fas fa-shipping-fast"></i> Deployment

       </a>


         <ul>


       <li data-nav-id="/hono/docs/1.2/deployment/helm-based-deployment/" title="Helm based Deployment" class="dd-item ">
         <a href="/hono/docs/1.2/deployment/helm-based-deployment/">
         Helm based Deployment

         </a>
     </li>


       <li data-nav-id="/hono/docs/1.2/deployment/openshift/" title="OpenShift / OKD" class="dd-item ">
         <a href="/hono/docs/1.2/deployment/openshift/">
         OpenShift / OKD

         </a>
     </li>


       <li data-nav-id="/hono/docs/1.2/deployment/create-kubernetes-cluster/" title="Setting up a Kubernetes Cluster" class="dd-item ">
         <a href="/hono/docs/1.2/deployment/create-kubernetes-cluster/">
         Setting up a Kubernetes Cluster

         </a>
     </li>


       <li data-nav-id="/hono/docs/1.2/deployment/resource-limitation/" title="Limiting Resource Usage" class="dd-item ">
         <a href="/hono/docs/1.2/deployment/resource-limitation/">
         Limiting Resource Usage

         </a>
     </li>


         </ul>

     </li>


     <li data-nav-id="/hono/docs/1.2/architecture/" title="Architecture" class="dd-item


         ">
       <a href="/hono/docs/1.2/architecture/">
           <i class="fas fa-landmark"></i> Architecture

       </a>


         <ul>


       <li data-nav-id="/hono/docs/1.2/architecture/component-view/" title="Component View" class="dd-item ">
         <a href="/hono/docs/1.2/architecture/component-view/">
         Component View

         </a>
     </li>


       <li data-nav-id="/hono/docs/1.2/architecture/auth/" title="Authentication/Authorization" class="dd-item ">
         <a href="/hono/docs/1.2/architecture/auth/">
         Authentication/Authorization

         </a>
     </li>


         </ul>

     </li>


     </ul>


       <section id="shortcuts">
         <h3></h3>
         <ul>

               <li>
                   <a class="padding" href="https://www.eclipse.org/hono/" title="Hono&#39;s Homepage"><i class='fas fa-home'></i> Hono Home</a>
               </li>

               <li>
                   <a class="padding" href="https://www.eclipse.org/hono/getting-started/" title="Getting started with Eclipse Hono"><i class='fas fa-plane-departure'></i> Getting Started</a>
               </li>

         </ul>
       </section>


     <section id="prefooter">
       <hr/>
       <ul>

         <li>
           <div id="select-box-wrapper">
           <div id="select-box">
           <a class="padding">
             Version:&nbsp;
           <div class="select-style">
             <select id="select-language" onchange="location = this.value;">


                       <option id="stable" value="https://www.eclipse.org/hono/docs/admin-guide/monitoring-tracing-config/">stable (1.8)</option>


                       <option id="1.8" value="https://www.eclipse.org/hono/docs/1.8/admin-guide/monitoring-tracing-config/">1.8</option>


                       <option id="1.7" value="https://www.eclipse.org/hono/docs/1.7/admin-guide/monitoring-tracing-config/">1.7</option>


                       <option id="1.6" value="https://www.eclipse.org/hono/docs/1.6/admin-guide/monitoring-tracing-config/">1.6</option>


                       <option id="1.5" value="https://www.eclipse.org/hono/docs/1.5/admin-guide/monitoring-tracing-config/">1.5</option>


                       <option id="1.4" value="https://www.eclipse.org/hono/docs/1.4/admin-guide/monitoring-tracing-config/">1.4</option>


                       <option id="1.3" value="https://www.eclipse.org/hono/docs/1.3/admin-guide/monitoring-tracing-config/">1.3</option>


                       <option id="1.2" value="https://www.eclipse.org/hono/docs/1.2/admin-guide/monitoring-tracing-config/" selected>1.2</option>


                       <option id="1.1" value="https://www.eclipse.org/hono/docs/1.1/admin-guide/monitoring-tracing-config/">1.1</option>


                       <option id="1.0" value="https://www.eclipse.org/hono/docs/1.0/admin-guide/monitoring-tracing-config/">1.0</option>


                       <option id="dev" value="https://www.eclipse.org/hono/docs/dev/admin-guide/monitoring-tracing-config/">dev</option>


         </select>
         <svg version="1.1" id="Capa_1" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" x="0px" y="0px"
           width="255px" height="255px" viewBox="0 0 255 255" style="enable-background:new 0 0 255 255;" xml:space="preserve">
           <g>
             <g id="arrow-drop-down">
               <polygon points="0,63.75 127.5,191.25 255,63.75 		" />
             </g>
           </g>
         </svg>
         </div>
         </a>
         </div>
         </div>
         </li>


       </ul>
     </section>

     <section id="footer">


 <p>&copy; 2021 <a href="https://www.eclipse.org/hono/">The Eclipse Hono Project</a></p>

 <p>
     Documentation built with
     <a href="https://gohugo.io/" target="_blank">Hugo</a>
     using the
     <a href="https://github.com/matcornic/hugo-theme-learn" target="_blank">Learn</a> theme.
 </p>

 <div class="eclipse-logo">
     <a href="https://www.eclipse.org" target="_blank">
         <img src="https://www.eclipse.org/hono/docs/images/eclipse_foundation_logo.svg"/>
     </a>
 </div>

     </section>
   </div>
 </nav>


         <section id="body">
         <div id="overlay"></div>


     <div class="old-version-hint">
         <p>This page refers to version <em>1.2</em>.
             You might want to use the <a href="https://www.eclipse.org/hono/docs/">current stable</a> version.
         </p>
     </div>


         <div class="padding highlightable">

               <div>
                 <div id="top-bar">


                   <div id="top-github-link">
                     <a class="github-link" title='Edit this page' href="https://github.com/eclipse/hono/edit/master/site/documentation/content/admin-guide/monitoring-tracing-config.md" target="blank">
                       <i class="fas fa-code-branch"></i>
                       <span id="top-github-link-text">Edit this page</span>
                     </a>
                   </div>


                 <div id="breadcrumbs" itemscope="" itemtype="http://data-vocabulary.org/Breadcrumb">
                     <span id="sidebar-toggle-span">
                         <a href="#" id="sidebar-toggle" data-sidebar-toggle="">
                           <i class="fas fa-bars"></i>
                         </a>
                     </span>

                   <span id="toc-menu"><i class="fas fa-list-alt"></i></span>

                   <span class="links">


             <a href='/hono/docs/1.2/'>Documentation</a> > <a href='/hono/docs/1.2/admin-guide/'>Admin Guide</a> > Monitoring & Tracing


                   </span>
                 </div>

                     <div class="progress">
     <div class="wrapper">
 <nav id="TableOfContents">
   <ul>
     <li><a href="#monitoring">Monitoring</a>
       <ul>
         <li><a href="#configuring-a-metrics-back-end">Configuring a Metrics Back End</a></li>
         <li><a href="#using-prometheus">Using Prometheus</a></li>
       </ul>
     </li>
     <li><a href="#health-check-server-configuration">Health Check Server Configuration</a></li>
     <li><a href="#tracing">Tracing</a>
       <ul>
         <li><a href="#configuring-a-tracer">Configuring a Tracer</a></li>
       </ul>
     </li>
     <li><a href="#configuring-usage-of-jaeger-tracing-included-in-docker-images">Configuring usage of Jaeger tracing (included in Docker images)</a></li>
     <li><a href="#enforcing-the-recording-of-traces-for-a-tenant">Enforcing the recording of traces for a tenant</a></li>
   </ul>
 </nav>
     </div>
 </div>


               </div>
             </div>

         <div id="head-tags">

         </div>

         <div id="body-inner">

             <h1>

               Monitoring &amp; Tracing
             </h1>


 <p>The individual components of an Eclipse Hono™ installation need to work together in order to provide their functionality to devices and applications. Under normal circumstances these interactions work flawlessly. However, due to the nature of distributed systems, any one (or more) of the components may crash or become otherwise unavailable due to arbitrary reasons. This page describes how Hono supports operations teams by providing insights into the individual service components and their interactions with each other by means of reporting metrics and tracing the processing of individual messages through the system.</p>
 <p>When a device uploads telemetry data to the HTTP adapter, the adapter invokes operations on the Device Registration, Credentials and the Tenant services in order to authenticate and authorize the device before sending the telemetry data downstream to the AMQP 1.0 Messaging Network. The overall success of this process and the latency involved before the message reaches the consumer is determined by the individual interactions between the service components.</p>
 <h2 id="monitoring">Monitoring</h2>
 <p>In a production environment, an operations team will usually want to keep track of some <em>key performance indicators</em> (KPI) which allow the team to determine the overall <em>health</em> of the system, e.g. memory and CPU consumption etc. Hono supports the tracking of such KPIs by means of metrics it can be configured to report. The metrics are usually collected in a time series database like <em>InfluxDB</em> or <em>Prometheus</em> and then visualized on a monitoring dash-board built using frameworks like <em>Grafana</em>. Such a dash-board can usually also be configured to send alarms when certain thresholds are exceeded.</p>
 <p>Metrics usually provide insights into the past and current status of an individual component. The values can be aggregated to provide a picture of the overall system&rsquo;s status. As such, metrics provide a great way to <em>monitor</em> system health and, in particular, to anticipate resource shortages and use such knowledge to pro-actively prevent system failure.</p>
 <h3 id="configuring-a-metrics-back-end">Configuring a Metrics Back End</h3>
 <p>Hono uses <a href="http://micrometer.io/">Micrometer</a> for providing metrics. It is
 possible to drop in any Micrometer compatible back end. Hono also uses the
 Micrometer integration with Spring Boot and Vert.x.</p>
 <p>Please refer to the <a href="http://micrometer.io/docs">Micrometer documentation</a>
 for details regarding the configuration of a specific Micrometer back end.
 In most cases, you only need to add the back end specific jar files to the class path and
 add back end specific configuration to the <code>application.yml</code> file.</p>
 <p>The Hono build supports configuration of a specific metrics back end by means
 of Maven profiles. The following build profiles are currently supported:</p>
 <ul>
 <li><code>metrics-prometheus</code> – Enables the Prometheus backend.</li>
 <li><code>metrics-graphite</code> – Enables the Graphite backend.</li>
 <li><code>metrics-influxdb</code> – Enables the InfluxDB backend.</li>
 </ul>
 <p>Additionally to selecting a metrics back end, you may need to configure the
 back end using Spring configuration options. See the documentation mentioned
 above for more information.</p>
 <p>Note that none of the above profiles are active by default, i.e. you need to
 explicitly activate one of them when starting the build using Maven&rsquo;s <code>-p</code>
 command line parameter.</p>
 <h3 id="using-prometheus">Using Prometheus</h3>
 <p>Most of the metrics back ends have data being <em>pushed</em> to from the components
 reporting the metrics. However, Prometheus is different in that it <em>polls</em>
 (or <em>scrapes</em>) all components periodically for new metrics data.
 For this to work, the Prometheus server needs to be configured with the IP
 addresses of the components to monitor. In the example deployment that comes
 with Hono, the Prometheus server is configured with the names of the Kubernetes
 services corresponding to the Hono components that it should scrape.
 The components themselves need to expose a corresponding HTTP endpoint that
 the Prometheus server can connect to for scraping the meter data. All
 Hono components that report metrics can be configured to expose such an
 endpoint via their <a href="#health-check-server-configuration"><em>Health Check</em> server</a>
 which already exposes endpoints for determining the component&rsquo;s readiness and liveness status.</p>
 <h2 id="health-check-server-configuration">Health Check Server Configuration</h2>
 <p>All of Hono&rsquo;s service components and protocol adapters contain a <em>Health Check</em> server which can be configured to
 expose several HTTP endpoints for determining the component&rsquo;s status.
 In particular, the server exposes a <code>/readiness</code>, a <code>/liveness</code> and an optional <code>/prometheus</code> URI endpoint.</p>
 <p>The former two endpoints are supposed to be used by container orchestration platforms like Kubernetes to monitor the runtime status of the containers
 that it manages. These endpoints are <em>always</em> exposed when the health check server is started.</p>
 <p>The <code>/prometheus</code> endpoint can be used by a Prometheus server to retrieve collected meter data from the component. It is <em>only</em> exposed if Prometheus has
 been configured as the metrics back end as described <a href="#configuring-a-metrics-back-end">above</a>.</p>
 <p>The health check server can be configured by means of the following environment variables:</p>
 <table>
 <thead>
 <tr>
 <th style="text-align:left">Environment Variable<br>Command Line Option</th>
 <th style="text-align:left">Default Value</th>
 <th style="text-align:left">Description</th>
 </tr>
 </thead>
 <tbody>
 <tr>
 <td style="text-align:left"><code>HONO_HEALTHCHECK_BINDADDRESS</code><br><code>--hono.healthCheck.bindAddress</code></td>
 <td style="text-align:left"><code>127.0.0.1</code></td>
 <td style="text-align:left">The IP address of the network interface that the health check server&rsquo;s secure port should be bound to. The server will only be started if this property is set to some other than the default value and corresponding key material has been configured using the <code>HONO_HEALTHCHECK_KEYPATH</code> and <code>HONO_HEALTHCHECK_CERTPATH</code> variables.</td>
 </tr>
 <tr>
 <td style="text-align:left"><code>HONO_HEALTHCHECK_CERTPATH</code><br><code>--hono.healthCheck.certPath</code></td>
 <td style="text-align:left">-</td>
 <td style="text-align:left">The absolute path to the PEM file containing the certificate that the secure server should use for authenticating to clients. This option must be used in conjunction with <code>HONO_HEALTHCHECK_KEYPATH</code>.<br>Alternatively, the <code>HONO_HEALTHCHECK_KEYSTOREPATH</code> option can be used to configure a key store containing both the key as well as the certificate.</td>
 </tr>
 <tr>
 <td style="text-align:left"><code>HONO_HEALTHCHECK_INSECUREPORTBINDADDRESS</code><br><code>--hono.healthCheck.insecurePortBindAddress</code></td>
 <td style="text-align:left"><code>127.0.0.1</code></td>
 <td style="text-align:left">The IP address of the network interface that the health check server&rsquo;s insecure port should be bound to. The server will only be started if this property is set to some other than the default value.</td>
 </tr>
 <tr>
 <td style="text-align:left"><code>HONO_HEALTHCHECK_INSECUREPORT</code><br><code>--hono.healthCheck.insecurePort</code></td>
 <td style="text-align:left"><code>8088</code></td>
 <td style="text-align:left">The port that the insecure server should listen on.</td>
 </tr>
 <tr>
 <td style="text-align:left"><code>HONO_HEALTHCHECK_KEYPATH</code><br><code>--hono.healthCheck.keyPath</code></td>
 <td style="text-align:left">-</td>
 <td style="text-align:left">The absolute path to the (PKCS8) PEM file containing the private key that the secure server should use for authenticating to clients. This option must be used in conjunction with <code>HONO_HEALTHCHECK_CERTPATH</code>. Alternatively, the <code>HONO_HEALTHCHECK_KEYSTOREPATH</code> option can be used to configure a key store containing both the key as well as the certificate.</td>
 </tr>
 <tr>
 <td style="text-align:left"><code>HONO_HEALTHCHECK_PORT</code><br><code>--hono.healthCheck.port</code></td>
 <td style="text-align:left"><code>8088</code></td>
 <td style="text-align:left">The port that the secure server should listen on.</td>
 </tr>
 <tr>
 <td style="text-align:left"><code>HONO_HEALTHCHECK_KEYSTOREPASSWORD</code><br><code>--hono.healthCheck.keyStorePassword</code></td>
 <td style="text-align:left">-</td>
 <td style="text-align:left">The password required to read the contents of the key store.</td>
 </tr>
 <tr>
 <td style="text-align:left"><code>HONO_HEALTHCHECK_KEYSTOREPATH</code><br><code>--hono.healthCheck.keyStorePath</code></td>
 <td style="text-align:left">-</td>
 <td style="text-align:left">The absolute path to the Java key store containing the private key and certificate that the secure server should use for authenticating to clients. Either this option or the <code>HONO_HEALTHCHECK_KEYPATH</code> and <code>HONO_HEALTHCHECK_CERTPATH</code> options need to be set in order to enable TLS secured connections with clients. The key store format can be either <code>JKS</code> or <code>PKCS12</code> indicated by a <code>.jks</code> or <code>.p12</code> file suffix respectively. The <code>HONO_HEALTHCHECK_KEYSTOREPASSWORD</code> variable can be used to set the password required for reading the key store.</td>
 </tr>
 </tbody>
 </table>
 <div class="alert alert-warning">
     <h4 class="alert-heading"><i class="fas fa-exclamation-triangle"></i> Failure to start</h4>
     <div>The component/service will fail to start if neither the secure not the insecure server have been configured properly.</div>
 </div>
 <h2 id="tracing">Tracing</h2>
 <p>In normal operation the vast majority of messages should be flowing through the system without any noteworthy delays or problems. In fact, that is the whole purpose of Hono. However, that doesn&rsquo;t mean that nothing can go wrong. For example, when a tenant&rsquo;s device administrator changes the credentials of a device in the Credentials service but has not yet updated the credentials on the device yet, then the device will start to fail in uploading any data to the protocol adapter it connects to. After a while, a back end application&rsquo;s administrator might notice, that there hasn&rsquo;t been any data being received from that particular device for quite some time. The application administrator therefore calls up the Hono operations team and complains about the data <em>being lost somewhere</em>.</p>
 <p>The operations team will have a hard time determining what is happening, because it will need to figure out which components have been involved in the processing of the device and why the data hasn&rsquo;t been processed as usual. The metrics alone usually do not help much here because metrics are usually not scoped to individual devices. The logs written by the individual components, on the other hand, might contain enough information to correlate individual entries in the log with each other and thus <em>trace</em> the processing of the message throughout the system. However, this is usually a very tedious (and error prone) process and the relevant information is often only logged at a level (e.g. <em>DEBUG</em>) that is not used in production (often <em>INFO</em> or above).</p>
 <p>In order to address this problem, Hono&rsquo;s service components are instrumented using <a href="http://opentracing.io">OpenTracing</a>. OpenTracing provides <em>Vendor-neutral APIs and instrumentation for distributed tracing</em>. The OpenTracing web page provides a <a href="https://opentracing.io/docs/supported-tracers/">list of supported tracer implementations</a> from which users can choose in order to collect (and examine) the tracing information generated by Hono&rsquo;s individual components.</p>
 <h3 id="configuring-a-tracer">Configuring a Tracer</h3>
 <p><strong>Hint</strong>: The description in this chapter applies to any compatible OpenTracing implementation. For an easier approach to configure usage of <a href="https://www.jaegertracing.io/">Jaeger tracing</a>, see the next chapter.</p>
 <p>Hono&rsquo;s components use the <a href="https://github.com/opentracing-contrib/java-tracerresolver">OpenTracing Tracer Resolver</a> mechanism to find and initialize a concrete OpenTracing implementation during startup of the component. The discovery mechanism is using Java&rsquo;s <a href="https://docs.oracle.com/javase/9/docs/api/java/util/ServiceLoader.html">ServiceLoader</a> and as such relies on the required resources to be available on the class path.</p>
 <p>When starting up any of Hono&rsquo;s Docker images as a container, the JVM will look for additional jar files to include in its class path in the container&rsquo;s <code>/opt/hono/extensions</code> folder. Thus, using a specific implementation of OpenTracing is just a matter of configuring the container to mount a volume or binding a host folder at that location and putting the implementation&rsquo;s jar files and resources into the corresponding volume or host folder.</p>
 <div class="alert alert-notice">
     <h4 class="alert-heading"><i class="fas fa-info-circle"></i> Note</h4>
     <div>This also means that (currently) only Tracer implementations can be used with Hono that also implement the Tracer Resolver mechanism.</div>
 </div>
 <p>Assuming that the HTTP adapter should be configured to use <a href="https://www.jaegertracing.io/">Jaeger tracing</a>, the following steps are necessary:</p>
 <ol>
 <li>
 <p>Download <a href="https://github.com/jaegertracing/jaeger-client-java/tree/master/jaeger-tracerresolver">Jaeger&rsquo;s Java Tracer Resolver</a> implementation and its dependencies (see the hint at the end).</p>
 </li>
 <li>
 <p>Put the jars to a folder on the Docker host, e.g. <code>/tmp/jaeger</code>.</p>
 </li>
 <li>
 <p>Start the HTTP adapter Docker image mounting the host folder:</p>
 <div class="highlight"><pre style="color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4"><code class="language-sh" data-lang="sh">docker run --name hono-adapter-http-vertx <span style="color:#ae81ff">\
 </span><span style="color:#ae81ff"></span>--mount type<span style="color:#f92672">=</span>bind,src<span style="color:#f92672">=</span>/tmp/jaeger,dst<span style="color:#f92672">=</span>/opt/hono/extensions,ro <span style="color:#ae81ff">\
 </span><span style="color:#ae81ff"></span>... <span style="color:#ae81ff">\
 </span><span style="color:#ae81ff"></span>eclipse/hono-adapter-http-vertx
 </code></pre></div></li>
 </ol>
 <p><strong>Note</strong>: the command given above does not contain the environment variables and secrets that are required to configure the service properly. The environment variables for configuring the Jaeger client are also missing. Please refer to the <a href="https://github.com/jaegertracing/jaeger-client-java/blob/master/jaeger-core/README.md">Jaeger documentation</a> for details.</p>
 <p>When the HTTP adapter starts up, it will look for a working implementation of the Tracer Resolver on its classpath and (if found) initialize and use it for publishing traces. The adapter&rsquo;s log file will indicate the name of the Tracer implementation being used.</p>
 <p>Using a Docker <em>volume</em> instead of a <em>bind mount</em> works the same way but requires the use of <code>volume</code> as the <em>type</em> of the <code>--mount</code> parameter. Please refer to the <a href="https://docs.docker.com/edge/engine/reference/commandline/service_create/#add-bind-mounts-volumes-or-memory-filesystems">Docker reference documentation</a> for details.</p>
 <p><strong>Hint</strong>: to resolve all dependencies for <code>jaeger-tracerresolver</code> in order to provide them to <code>/opt/hono/extensions</code>, you may want to rely on Maven&rsquo;s dependency plugin. To obtain all jar files you can invoke the following command in a simple Maven project that contains only the dependency to <code>jaeger-tracerresolver</code>:</p>
 <div class="highlight"><pre style="color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4"><code class="language-sh" data-lang="sh">mvn dependency:copy-dependencies
 </code></pre></div><p>All jar files can then be found in the directory <code>target/dependency</code>.</p>
 <h2 id="configuring-usage-of-jaeger-tracing-included-in-docker-images">Configuring usage of Jaeger tracing (included in Docker images)</h2>
 <p>In case <a href="https://www.jaegertracing.io/">Jaeger tracing</a> shall be used, there is an alternative to putting the jar files in the container&rsquo;s <code>/opt/hono/extensions</code> folder as described above.
 This is to have the Jaeger tracing jar files be included in the Hono Docker images by using the <code>jaeger</code> Maven profile when building Hono.</p>
 <p>For example, building the HTTP adapter image with the Jaeger client included:</p>
 <div class="highlight"><pre style="color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4"><code class="language-sh" data-lang="sh"><span style="color:#75715e"># in directory: hono/adapters/http-vertx/</span>
 mvn clean install -Pbuild-docker-image,jaeger
 </code></pre></div><p>Note that when running the created docker image, the environment variables for configuring the Jaeger client still need to be set. Please refer to the <a href="https://github.com/jaegertracing/jaeger-client-java/blob/master/jaeger-core/README.md">Jaeger documentation</a> for details.</p>
 <h2 id="enforcing-the-recording-of-traces-for-a-tenant">Enforcing the recording of traces for a tenant</h2>
 <p>Typically, in production systems, the tracing components will be configured to not store <em>all</em> trace spans in the tracing backend, in order to reduce the performance impact. For debugging purposes it can however be beneficial to enforce the recording of certain traces. Hono allows this by providing a configuration option in the Tenant information with which all traces concerning the processing of telemetry, event and command messages for that specific tenant will be recorded. Furthermore, this enforced trace sampling can be restricted to only apply to messages sent in the context of a specific authentication identifier. Please refer to the <a href="/hono/docs/1.2/api/tenant/#tracing-format">description of the <code>tracing</code> object</a> in the Tenant Information for details.</p>

 <footer class="footline">

 </footer>


         </div>


       </div>

     <div id="navigation">


     </div>

     </section>

     <div style="left: -1000px; overflow: scroll; position: absolute; top: -1000px; border: none; box-sizing: content-box; height: 200px; margin: 0px; padding: 0px; width: 200px;">
       <div style="border: none; box-sizing: content-box; height: 200px; margin: 0px; padding: 0px; width: 200px;"></div>
     </div>
     <script src="/hono/docs/js/clipboard.min.js?1626138731"></script>
     <script src="/hono/docs/js/perfect-scrollbar.min.js?1626138731"></script>
     <script src="/hono/docs/js/perfect-scrollbar.jquery.min.js?1626138731"></script>
     <script src="/hono/docs/js/jquery.sticky.js?1626138731"></script>
     <script src="/hono/docs/js/featherlight.min.js?1626138731"></script>
     <script src="/hono/docs/js/highlight.pack.js?1626138731"></script>
     <script>hljs.initHighlightingOnLoad();</script>
     <script src="/hono/docs/js/modernizr.custom-3.6.0.js?1626138731"></script>
     <script src="/hono/docs/js/learn.js?1626138731"></script>
     <script src="/hono/docs/js/hugo-learn.js?1626138731"></script>

     <link href="/hono/docs/mermaid/mermaid.css?1626138731" rel="stylesheet" />
     <script src="/hono/docs/mermaid/mermaid.js?1626138731"></script>
     <script>
         mermaid.initialize({ startOnLoad: true });
     </script>


 <script>
     (function(w,d,s,l,i){w[l]=w[l]||[];w[l].push({'gtm.start':
             new Date().getTime(),event:'gtm.js'});var f=d.getElementsByTagName(s)[0],
         j=d.createElement(s),dl=l!='dataLayer'?'&l='+l:'';j.async=true;j.src=
         'https://www.googletagmanager.com/gtm.js?id='+i+dl;f.parentNode.insertBefore(j,f);
     })(window,document,'script','dataLayer','GTM-5WLCZXC');
 </script>


 <script src="https://www.eclipse.org/eclipse.org-common/themes/solstice/public/javascript/vendor/cookieconsent/default.min.js"></script>

   </body>
 </html>