From f50ecffe0f1853947c0a56cb89882cbdbf82265b Mon Sep 17 00:00:00 2001 From: Zdenek Prikryl Date: Wed, 13 May 2009 11:13:12 +0200 Subject: plugins how-to (dnovotny) --- doc/PLUGINS-HOWTO | 136 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 136 insertions(+) create mode 100644 doc/PLUGINS-HOWTO (limited to 'doc') diff --git a/doc/PLUGINS-HOWTO b/doc/PLUGINS-HOWTO new file mode 100644 index 00000000..bb315f99 --- /dev/null +++ b/doc/PLUGINS-HOWTO @@ -0,0 +1,136 @@ +This document describes how to create your own plugin for abrt. + +There is a base abstract class CPlugin, but you can't inherit +directly from that: you have to use one of the four subclasses, +depending on what is your plugin supposed to do. + +These are the subclasses: + * Action plugin (CAction) + * Analyzer plugin (CAnalyzer) + * Reporter plugin (CReporter) + * Database plugin (CDatabase) + +Each of them requires you to override different set of methods. + +One very common parameter of the methods is called +pDebugDumpDir: it specifies the directory, +which is created to gather information of this specific crash: +the files (such as core dumps) that were created when the application +crashed are all stored here. In addition, the plugins can write +their output files there, if any. + +Let's discuss the plugin types in detail: + +Action Plugin +------------- +This type of plugin is used, when you need some action to be +performed in the case the crash is encountered. +you have to override one method: + +virtual void Run(const std::string& pActiveDir, + const std::string& pArgs) = 0; +-This method runs the specified action. + The first argument is an directory name. It can be either current debug + dump dir or directory which contains all debug dumps. + The second argument is a string with arguments specified for the action. + +Analyzer Plugin +--------------- +This plugin has to compute the UUID of the crash: crashes in kernel, +in userspace binary, in python script etc. differ, so you have to have +plugin for each type of application, that you want "abrt" to handle. + +you have to override these methods: + +virtual std::string GetLocalUUID(const std::string& pDebugDumpPath) = 0; +- This method computes the local UUID of the crash. + +virtual std::string GetGlobalUUID(const std::string& pDebugDumpPath) = 0; +- This method computes the global UUID of the crash. + +NOTE:The difference between local and global UUID is, that the local UUID +is specific for the machine architecture, on which the crash is encountered. +When the crash is reported, abrt has to use the "-debuginfo" packages +to render a global UUID, which should be independent of the specific +system (the same crash on different architectures/configurations can +yield different local UUIDs but has to have the same global UUID). + +virtual void CreateReport(const std::string& pDebugDumpPath) = 0; +- This method creates the report about the crash and stores it + in the crash's directory. + +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 crash_report_t& pCrashReport, + const std::string& pArgs) = 0; +-It's self-explanatory, that this method takes the report + and presents it somewhere to the world. + The second argument is a string with arguments specified for the retorter. + + +Database Plugin +--------------- +This plugin is used to store the metadata about the crash: +they have to be in the database in order 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() = 0; +virtual void DisConnect() = 0; +- 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) = 0; +- insert an entry to 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) = 0; +- delete an entry + +virtual void SetReported(const std::string& pUUID, const std::string& pUID) = 0; +- insert to the database the information, 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) = 0; +- get database rows for the specified user ID + +virtual const database_row_t GetUUIDData(const std::string& pUUID, const + std::string& pUID) = 0; +- get a database row for the specified user ID and UUID + + +The macro PLUGIN_INFO +--------------------- +It is required, in order for your subclass to be properly registered +and treated as a plugin, to use the macro PLUGIN_INFO in your plugin's +header file. +This sets up all the lower-level and administrative details to fit your +class into the plugin infrastructure. The syntax is this: + +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