.. _acrnprobe_doc: acrnprobe ######### Description *********** The ``acrnprobe`` is a tool to detect all critical events on the platform and collect specific information for them. The collected information would be saved as logs. The log path would be delivered to `telemetrics-client`_ as a record if telemetrics-client exists on the system. In this case ``acrnprobe`` works as a *probe* of telemetrics-client. If telemetrics-client doesn't exist on the system, ``acrnprobe`` provides ``history_event`` (under ``/var/log/crashlog/`` by default) to manage the crash and events records on the platform instead of ``telem_journal``. But in this case, the records can't be delivered to the backend. Usage ***** The ``acrnprobe`` is launched as a service at boot. Also, it provides some basic options: Specify a configuration file for ``acrnprobe``. If this option is unused, ``acrnprobe`` will use the configuration file located in CUSTOM CONFIGURATION PATH or INSTALLATION PATH (see `CONFIGURATION FILES`_). .. code-block:: none $ acrnprobe -c [configuration_path] To see the version of ``acrnprobe``. .. code-block:: none $ acrnprobe -V Architecture ************ Terms ===== - channel : Channel represents a way of detecting the system's events. There are 3 channels: + oneshot: detect once while ``acrnprobe`` startup. + polling: run a detecting job with fixed time interval. + inotify: monitor the change of file or dir. - trigger : Essentially, trigger represents one section of content. It could be a file's content, a directory's content, or a memory's content which can be obtained. By monitoring it ``acrnprobe`` could detect certain events which happened in the system. - crash : A subtype of event. It often corresponds to a crash of programs, system, or hypervisor. ``acrnprobe`` detects it and reports it as ``CRASH``. - info : A subtype of event. ``acrnprobe`` detects it and reports it as ``INFO``. - event queue : There is a global queue to receive all events detected. Generally, events are enqueued in channel, and dequeued in event handler. - event handler : Event handler is a thread to handle events detected by channel. It's awakened by an enqueued event. - sender : The sender corresponds to an exit of event. There are two senders: + Crashlog is responsible for collecting logs and saving it locally. + Telemd is responsible for sending log records to telemetrics client. Description =========== As a log collection mechanism to record critical events on the platform, ``acrnprobe`` provides these functions: 1. detect event From experience, the occurrence of an system event is usually accompanied by some effects. The effects could be a generated file, an error message in kernel's log, or a system reboot. To get these effects, for some of them we can monitor a directory, for other of them we might need to do a detection in a time loop. *So we implement the channel, which represents a common method of detection.* 2. analyze event and determine the event type Generally, a specific effect correspond to a particular type of events. However, it is the icing on the cake for analyzing the detailed event types according to some phenomena. *Crash reclassify is implemented for this purpose.* 3. collect information for detected events This is for debug purpose. Events without information are meaningless, and developers need to use this information to improve their system. *Sender crashlog is implemented for this purpose.* 4. archive these information as logs, and generate records There must be a central place to tell user what happened in system. *Sender telemd is implemented for this purpose.* Diagram ======= :: +---------------------------------------------+ | channel: |oneshot| |polling| |inotify| | +--------------------------------------+------+ | +---------------------+ +-----+ | | event queue +<---+event+<----+ +-+-------------------+ +-----+ | v +-+---------------------------------------------------------------------------+ | event handler: | | | | event handler will handle internal event | | +----------+ +------------+ | | |heart beat+--->+fed watchdog| | | +----------+ +------------+ | | | | call sender for other types | | +--------+ +----------------+ +------------+ +------------------+ | | |crashlog+-->+crash reclassify+-->+collect logs+-->+generate crashfile| | | +--------+ +----------------+ +------------+ +------------------+ | | | | +------+ +------------------+ | | |telemd+--->+telemetrics client| | | +------+ +------------------+ | +-----------------------------------------------------------------------------+ Source files ************ - main.c Entry of ``acrnprobe``. - channel.c The implementation of *channel* (see `Terms`_). - crash_reclassify.c Analyzing the detailed types for crash event. - probeutils.c Provide some utils ``acrnprobe`` needs. - event_queue.c The implementation of *event queue* (see `Terms`_). - event_handler.c The implementation of *event handler* (see `Terms`_). - history.c There is a history_event file to manage all logs that ``acrnprobe`` archived. "history.c" provides the interfaces to modify the file in fixed format. - load_conf.c Parse and load the configuration file. - property.c The ``acrnprobe`` needs to know some HW/SW properties, such as board version, build version. These properties are managed centrally in this file. - sender.c The implementation of *sender* (see `Terms`_). - startupreason.c This file provides the function to get system reboot reason from kernel command line. - android_events.c Sync events detected by android crashlog. - loop.c This file provides interfaces to read from image. Configuration files ******************* * ``/usr/share/defaults/telemetrics/acrnprobe.xml`` If no custom configuration file is found, ``acrnprobe`` uses the settings in this file. * ``/etc/acrnprobe.xml`` Custom configuration file that ``acrnprobe`` reads. For details about configuration file, please refer to :ref:`acrnprobe-conf`. .. _`telemetrics-client`: https://github.com/clearlinux/telemetrics-client