Telemetry

Collaboration diagram for Telemetry:

Logging telemetry

libMagAO-X implements telemetry based on the logs system ( see Logging an event or information and Steps to adding a new log type: ).

The telemetry system writes a log at a fixed frequency (every 10s by default), regardless of whether the telemetry data has changed.

It is also possible to log telemetry when certain changes or events take place (outside of the fixed frequency interval).

Steps to adding telemetry

1. To add a new log type that is not an empty log (assume it is called "telem_type") follow steps 2-5 from Steps to adding a new log type: :
   • Create a flatbuffer schema in logger/types/schemas
     
   • Create a new file "telem_type.hpp" in the logger/types directory (see template in Steps to adding a new log type:).
   • Add the new "types/telem_type.hpp" file to the libMagAOX Makefile INCLUDEDEPS list.
   • Add the log type to "logger/logCodes.dat" (see instructions and restrictions in Steps to adding a new log type:)
2. Add an entry in telem.cpp to initialize the telem_fsm::lastRecord member
3. Re-compile the logging system by typing make in the libMagAOX directory (above logger). This will generate a number of files based on the logCodes.dat entry you have made. Correct any errors from the flatc compiler or the flatlogs code generator.
4. Re-compile the logdump utility by running the following in the MagAOX/utils/logdump directory:

   make
   make install

5. A class that derives from MagAOX::app::MagAOXApp (assume it is called appCtrl) needs to inherit the telemeter template and implement the interface described in telemeter.hpp, e.g.:

   class appCtrl : public MagAOXApp<true>, public dev::telemeter<appCtrl>
   {
      ...
    
      friend class dev::telemeter<appCtrl>;
      typedef dev::telemeter<appCtrl> telemeterT;
    
      ....
    
      public:
         ....
    
         int checkRecordTimes();
    
         int recordTelem( const telem_type * ); // ASSUME A LOG TYPE CALLED telem_type AND UPDATE AS NECESSARY
    
         int recordApp( bool force = false ); // ASSUME A MEMBER recordApp THAT WRITES A TELEMETRY LOG OF TYPE telem_type
   }
    
   ...
    
   int appCtrl::checkRecordTimes() // DO NOT CHANGE NAME
   {
     return telemeterT::checkRecordTimes(telem_type());
   }
    
   int appCtrl::recordTelem(const telem_type *) // DO NOT CHANGE NAME
   {
     return recordApp(true);
   }
    
   int appCtrl::recordApp( bool force ) // UPDATE NAME AS NEEDED
   {
      static dataStruct lastTelem; ///< Structure holding previous telemetery data measurement.
      
      if(!(lastTelem == newTelem) || force)
      {
         telem<telem_type>({newTelem.data1, newTelem.data2, newTelem.data3, ...}); // OUTPUT TELEM LOG
         lastTelem = newTelem;
      }
      
      return 0;
   }

6. Calls to the corresponding dev::telemeter<appCtrl> classes should be placed in the setupConfig, loadConfig, appStartup, appLogic, and appShutdown functions of appCtrl, e.g.:

   void appCtrl::setupConfig()
   {
     config.add(...);
     ...
    
     telemeterT::setupConfig(config);
   }
    
   void appCtrl::loadConfig()
   {
     if( loadConfigImpl(config) < 0)
     {
       log<text_log>("Error during config", logPrio::LOG_CRITICAL);
       m_shutdown = true;
     }
    
     if(telemeterT::loadConfig(config) < 0)
     {
       log<text_log>("Error during telemeter config", logPrio::LOG_CRITICAL);
       m_shutdown = true;
     }
   }
    
   int appCtrl::appStartup()
   {
      ... performing startup ...
    
     if(telemeterT::appStartup() < 0)
     {
       return log<software_error,-1>({__FILE__,__LINE__});
     }
    
     return 0;
   }
    
   int appCtrl::appLogic()
   {
     ... app doing its thing ...
    
     if(telemeterT::appLogic() < 0)
     {
         log<software_error>({__FILE__, __LINE__});
         return 0;
     }
    
     return 0;
   }
    
   int fsmCtrl::appShutdown()
   {
     telemeterT::appShutdown();
    
     return 0;
   }

7. Include calls to recordApp at appropriate places throughout the appCtrl class, where things might have changed, to make sure that, in addition to the 0.1 Hz telemetry logging, changes are captured at the time they happen.
8. Compile the app

Reading telemetry files

The telemetry logs are saved by default in /opt/MagAOX/telem .

To read them, use the logdump utility (see the handbook for usage) with the command line args --dir=/opt/MagAOX/telem --ext=.bintel, e.g.:

logdump --dir=/opt/MagAOX/telem --ext=.bintel appCtrl

The alias teldump might also be available (depending on how MagAOX was installed):

teldump appCtrl