docs/userguide/keepalive.userguide.rst

   1 .. This work is licensed under a Creative Commons Attribution 4.0 International License.
   2 .. http://creativecommons.org/licenses/by/4.0
   3 .. (c) OPNFV, Intel Corporation and others.
   4
   5 DPDK Keep Alive description
   6 ===========================
   7 SFQM aims to enable fault detection within DPDK, the very first feature to
   8 meet this goal is the DPDK Keep Alive Sample app that is part of DPDK 2.2.
   9
  10 DPDK Keep Alive or KA is a sample application that acts as a heartbeat/watchdog
  11 for DPDK packet processing cores, to detect application thread failure. The
  12 application supports the detection of ‘failed’ DPDK cores and notification to a
  13 HA/SA middleware. The purpose is to detect Packet Processing Core fails (e.g.
  14 infinite loop) and ensure the failure of the core does not result in a fault
  15 that is not detectable by a management entity.
  16
  17 .. Figure:: dpdk_ka.png
  18
  19    DPDK Keep Alive Sample Application
  20
  21 Essentially the app demonstrates how to detect 'silent outages' on DPDK packet
  22 processing cores. The application can be decomposed into two specific parts:
  23 detection and notification.
  24
  25 * The detection period is programmable/configurable but defaults to 5ms if no
  26   timeout is specified.
  27 * The Notification support is enabled by simply having a hook function that where this
  28   can be 'call back support' for a fault management application with a compliant
  29   heartbeat mechanism.
  30
  31 DPDK Keep Alive Sample App Internals
  32 ------------------------------------
  33 This section provides some explanation of the The Keep-Alive/'Liveliness'
  34 conceptual scheme as well as the DPDK Keep Alive App. The initialization and
  35 run-time paths are very similar to those of the L2 forwarding application (see
  36 `L2 Forwarding Sample Application (in Real and Virtualized Environments)`_ for more
  37 information).
  38
  39 There are two types of cores: a Keep Alive Monitor Agent Core (master DPDK core)
  40 and Worker cores (Tx/Rx/Forwarding cores). The Keep Alive Monitor Agent Core
  41 will supervise worker cores and report any failure (2 successive missed pings).
  42 The Keep-Alive/'Liveliness' conceptual scheme is:
  43
  44 * DPDK worker cores mark their liveliness as they forward traffic.
  45 * A Keep Alive Monitor Agent Core runs a function every N Milliseconds to
  46   inspect worker core liveliness.
  47 * If keep-alive agent detects time-outs, it notifies the fault management
  48   entity through a call-back function.
  49
  50 **Note:**  Only the worker cores state is monitored. There is no mechanism or agent
  51 to monitor the Keep Alive Monitor Agent Core.
  52
  53 DPDK Keep Alive Sample App Code Internals
  54 -----------------------------------------
  55 The following section provides some explanation of the code aspects that are
  56 specific to the Keep Alive sample application.
  57
  58 The heartbeat functionality is initialized with a struct rte_heartbeat and the
  59 callback function to invoke in the case of a timeout.
  60
  61 .. code:: c
  62
  63     rte_global_keepalive_info = rte_keepalive_create(&dead_core, NULL);
  64     if (rte_global_hbeat_info == NULL)
  65         rte_exit(EXIT_FAILURE, "keepalive_create() failed");
  66
  67 The function that issues the pings hbeat_dispatch_pings() is configured to run
  68 every check_period milliseconds.
  69
  70 .. code:: c
  71
  72     if (rte_timer_reset(&hb_timer,
  73             (check_period * rte_get_timer_hz()) / 1000,
  74             PERIODICAL,
  75             rte_lcore_id(),
  76             &hbeat_dispatch_pings, rte_global_keepalive_info
  77             ) != 0 )
  78         rte_exit(EXIT_FAILURE, "Keepalive setup failure.\n");
  79
  80 The rest of the initialization and run-time path follows the same paths as the
  81 the L2 forwarding application. The only addition to the main processing loop is
  82 the mark alive functionality and the example random failures.
  83
  84 .. code:: c
  85
  86     rte_keepalive_mark_alive(&rte_global_hbeat_info);
  87     cur_tsc = rte_rdtsc();
  88
  89     /* Die randomly within 7 secs for demo purposes.. */
  90     if (cur_tsc - tsc_initial > tsc_lifetime)
  91     break;
  92
  93 The rte_keepalive_mark_alive() function simply sets the core state to alive.
  94
  95 .. code:: c
  96
  97     static inline void
  98     rte_keepalive_mark_alive(struct rte_heartbeat *keepcfg)
  99     {
 100         keepcfg->state_flags[rte_lcore_id()] = 1;
 101     }
 102
 103 Keep Alive Monitor Agent Core Monitoring Options
 104 The application can run on either a host or a guest. As such there are a number
 105 of options for monitoring the Keep Alive Monitor Agent Core through a Local
 106 Agent on the compute node:
 107
 108          ======================  ==========  =============
 109           Application Location     DPDK KA     LOCAL AGENT
 110          ======================  ==========  =============
 111                   HOST               X        HOST/GUEST
 112                   GUEST              X        HOST/GUEST
 113          ======================  ==========  =============
 114
 115
 116 For the first implementation of a Local Agent SFQM will enable:
 117
 118          ======================  ==========  =============
 119           Application Location     DPDK KA     LOCAL AGENT
 120          ======================  ==========  =============
 121                   HOST               X           HOST
 122          ======================  ==========  =============
 123
 124 Through extending the dpdkstat plugin for collectd with KA functionality, and
 125 integrating the extended plugin with Monasca for high performing, resilient,
 126 and scalable fault detection.
 127
 128 .. _L2 Forwarding Sample Application (in Real and Virtualized Environments): http://dpdk.org/doc/guides/sample_app_ug/l2_forward_real_virtual.html