From 70d3a915fa7b375e4b3c4198ae7c7c9687927942 Mon Sep 17 00:00:00 2001 From: Nikola Pajkovsky Date: Wed, 21 Jul 2010 09:40:12 +0200 Subject: rename and lower-case doc files Signed-off-by: Nikola Pajkovsky --- doc/plugins-howto | 155 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 155 insertions(+) create mode 100644 doc/plugins-howto (limited to 'doc/plugins-howto') diff --git a/doc/plugins-howto b/doc/plugins-howto new file mode 100644 index 00000000..81090f33 --- /dev/null +++ b/doc/plugins-howto @@ -0,0 +1,155 @@ +This document describes how to create your own plugin for abrt. + +Although a base abstract class CPlugin exists, you can't inherit +directly from it. You must use one of the four subclasses, +depending on what you want your plugin to do. + +The subclasses are: + * Action plugin (CAction) + * Analyzer plugin (CAnalyzer) + * Reporter plugin (CReporter) + * Database plugin (CDatabase) + +Each of them requires you to override a different set of methods. + +The pDebugDumpDir parameter is very common: it specifies the directory +that is created to gather information of this specific crash. +The files that were created when the application crashed (such as core dumps) +are all stored here. In addition, the plugins can write +their output files there, if any. + +Plugin types in detail: + + +Analyzer Plugin +--------------- +Crashes differ, depending on where they occur, for example crashes +in the kernel differ from crashes in userspace binaries, which differ +from crashes in python scripts. Therefore, there is a plugin +for each type of application that you want abrt to handle. + +You have to override these methods: + +virtual std::string GetLocalUUID(const char *pDebugDumpPath); +- This method is invoked immediately after crash is detected + and its data is saved by the corresponding hook. + It needs to compute an unique hash (UUID) of the crash. + When a crash occurs and abrt finds an earlier crash with the same + UUID, new crash is discarded as a duplicate, it doesn't show up + in abrt's crash list, but instead a crash count for the earlier + crash is incremented. + +virtual void CreateReport(const char *pDebugDumpDir, int force) +- This method is called when user wants to report a crash + ([Reoprt] button in GUI, etc). Analyzer can perform additional, + more CPU/disk intensive, or interactive processing at this point. + For example, CCpp plugin's CreateReport() processes coredump file, + produces a textual backtrace, and saves it to crash dump directory. + +virtual std::string GetGlobalUUID(const char *pDebugDumpPath); +- This method computes a "duplicate hash" which is used search for + duplicates in remote bug databases such as Bugzilla. They are + "less unique" than LocalUUIDs: ideally, the same crash + on different architecture or with slightly different backtrace + will still have the same GlobalUUID. + [TODO: renaming it to DUPHASH] + + +Action Plugin +------------- +This type of plugin is useful when you need some action to be performed. +Action plugins can be invoked in three ways: + +* Immediately when a crash is encountered (using ActionsAndReporters = ... + directive in abrt.conf). These action plugins are run on every crash + (regardless of crash type). + +* After Analyzer plugin processed a crash (by specifying plugin in + [AnalyzerActionsAndReporters] section, for example: "CCpp = AnActionPlugin"). + In this case, action plugin's Run() method will be run after analyzer + plugin's CreateReport() and GetGlobalUUID() methods have finished. + +* If you need some action to be performed periodically ([Cron] section + in the same file). + +You have to override one method: + +virtual void Run(const char *dir, const char *args); + +The first argument is a directory that contains the current debug +dump, or all debug dumps for periodic actions. +The second argument is a string with arguments (specified in config file). + + +Reporter Plugin +--------------- +This plugin receives the entire finished crash report and +posts/reports it somewhere (e.g. logs it, mails it, posts +it on some web tool...) + +You have to override this method: + +virtual void Report(const map_crash_data_t& pCrashData, + const char *pArgs); +- This method takes the report and presents it somewhere to the world. + The second argument is a string with arguments specified for the reporter. + + +Database Plugin +--------------- +This plugin is used to store the metadata about the crash. The metadata +has to be in a database, to distinguish whether the current crash is or +is not the same as some crash before. The database can be local, or in +some centralized location on the network. + +You have to override these methods: +virtual void Connect(); +virtual void DisConnect(); +- connect and disconnect from the database + +virtual void Insert(const std::string& pUUID, + const std::string& pUID, + const std::string& pDebugDumpPath, + const std::string& pTime); +- insert an entry into the database: you use both UID (user ID) and UUID + (ID of the crash) + +virtual void Delete(const std::string& pUUID, const std::string& pUID); +- delete an entry + +virtual void SetReported(const std::string& pUUID, const std::string& pUID); +- insert information into the database to say that this bug was already + reported (so for example the report plugins won't run several times + for the same bug) + +virtual const vector_database_rows_t GetUIDData(const std::string& pUID); +- get database rows for the specified user ID + +virtual const database_row_t GetUUIDData(const std::string& pUUID, const + std::string& pUID); +- get a database row for the specified user ID and UUID + + +The macro PLUGIN_INFO +--------------------- +Use the macro PLUGIN_INFO in the *.cpp file of your plugin so that your +subclass will be properly registered and treated as a plugin. +This sets up all the lower-level and administrative details to fit your +class into the plugin infrastructure. The syntax is: + +PLUGIN_INFO(type, plugin_class, name, version, description, email, www) +- "type" is one of ANALYZER, ACTION, REPORTER, or DATABASE +- "plugin_class" is the identifier of the class +- "name" is a string with the name of the plugin +- "version" is a string with the version of the plugin +- "description" is a string with the summary of what the plugin does +- "email" and "www" are strings with the contact info for the author + +For example: +PLUGIN_INFO(REPORTER, + CMailx, + "Mailx", + "0.0.1", + "Sends an email with a report via mailx command", + "zprikryl@redhat.com", + "https://fedorahosted.org/crash-catcher/wiki"); -- cgit