From: Tim Pepper Date: Wed, 3 Oct 2012 18:40:02 +0000 (-0700) Subject: Add README skipped in prior commit X-Git-Tag: 2.1b_release~15 X-Git-Url: http://review.tizen.org/git/?a=commitdiff_plain;h=3886bcf7edcb344f517f163764d0f2b608365d9b;p=external%2Fcorewatcher.git Add README skipped in prior commit We finally have a general README describing the software at a high level, how to configure, build, and run, and giving some basic internal design information. Signed-off-by: Tim Pepper --- diff --git a/Makefile.am b/Makefile.am index 4531c66..e0ffeb3 100644 --- a/Makefile.am +++ b/Makefile.am @@ -14,4 +14,5 @@ dist_systemdunit_DATA = src/corewatcher.service EXTRA_DIST = \ COPYING \ + README \ $(man_MANS) diff --git a/README b/README new file mode 100644 index 0000000..01fcb1f --- /dev/null +++ b/README @@ -0,0 +1,107 @@ + README for corewatcher + + +The corewatcher package provides a daemon for monitoring a system for +crashes. Crashes are analyzed and summary crash report information is +sent to a crashdb server. + +The daemon is managed by a systemd unit file, corewatcher.service. + +Configuration is stored in /etc/corewatcher. + +Corefiles are assumed to be written to /var/lib/corewatcher by the +kernel with /proc/sys/kernel settings of: + core_pattern=/var/lib/corewatcher/core_%e_%t + core_uses_pid=1 + +To build and run, use the standard autotools workflow like: + ./configure + make + sudo make install + + +=========================================================================== + + +The corewatcher daemon can be considered to be a state machine with the +following 5 possible states and the listed major functions called for +state transitions: + +S1: core_folder has no core_* + | + | crash happens leading to inotification + | +S2: core_folder has core_* present + | + | scan_core_folder() + | get_appfile() + | move_core(fullpath, "to-process") + | +S3: processed_folder has some core_*.to-process + | + | scan_processed_folders() + | process_corefile() + | process_new() + | (calls gdb, creates report summary *.txt) + | queue_backtrace() + | +S4: processed_folder has some core_*.processed + | + | scan_processed_folder() + | reprocess_corefile() + | process_old() + | queue_backtrace() + . + . + . +unqueueing + | + | submit_loop(): a sleepy thread whose work condition is set in + | queue_backtrace() and in the period timer + | "cleanup" thread + | +S5: processed_folder has only core_*.submitted and *.txt + + +NOTES: +o at daemon start any of the states in the filesystem could exist, so we + need to do all of get_appfile()/move_core(), process_new(), process_old() + and submit_loop() +o during submission, crash reports are removed from the in-memory pending + work list for submission, then if curl POST fails, the associated cores + stay in the filesystem as "processed" files, and re-added to the in-memory + work list + - if client network is down and comes back up, an event notifier + could trigger resubmit via reprocess_corefile() and submit_loop() + - if server or intermediate connectivity was the problem, only a + periodic timer can attempt to resubmit via reprocess_corefile() and + setting the work condition for submit_loop() + - failed submissions should hang out at the end of the work queue in + case there is something truly wrong with them so new reports have a + better chance of getting through + + +=========================================================================== + + +Internals: locking & global state + + o core_status is a global struct + o ordering: + "processing_mtx -> gdb_mtx ->processing_queue_mtx" + o core_status.processing_mtx: + - protects: core_status.processing_oops GHashTable + o processing_queue_mtx: (coredump.c) + - protects: processing_queue array of corefile fullpath strings + o gdb_mtx: (coredump.c) + - intent was to insure gdb doesn't run concurrently, under an assumption + that simultaneously processing multiple cores is too resource intensive + and system-unfriendly + o bt_mtx: (submit.c) + - protects: + o bt_list struct oops linked list + o bt_work GCond condition variable + o bt_hash GHashTable of core file names + o A struct oops may exist off of bt_list and still referenced by name + in be in bt_hash. Such a struct oops must exist if the core name + is in the bt_hash.