1 // Copyright 2013 The Chromium Authors 2 // Use of this source code is governed by a BSD-style license that can be 3 // found in the LICENSE file. 4 5 #ifndef BASE_DEBUG_DUMP_WITHOUT_CRASHING_H_ 6 #define BASE_DEBUG_DUMP_WITHOUT_CRASHING_H_ 7 8 #include "base/base_export.h" 9 #include "base/compiler_specific.h" 10 #include "base/location.h" 11 #include "base/time/time.h" 12 #include "build/build_config.h" 13 14 // These values are persisted to logs. Entries should not be renumbered and 15 // numeric values should never be reused. 16 enum class DumpWithoutCrashingStatus { 17 kThrottled, 18 kUploaded, 19 kMaxValue = kUploaded 20 }; 21 22 namespace base { 23 24 namespace debug { 25 26 // Handler to silently dump the current process without crashing. 27 // Before calling this function, call SetDumpWithoutCrashingFunction to pass a 28 // function pointer. 29 // Windows: 30 // This must be done for each instance of base (i.e. module) and is normally 31 // chrome_elf!DumpProcessWithoutCrash. See example code in chrome_main.cc that 32 // does this for chrome.dll and chrome_child.dll. Note: Crashpad sets this up 33 // for main chrome.exe as part of calling crash_reporter::InitializeCrashpad. 34 // Mac/Linux: 35 // Crashpad does this as part of crash_reporter::InitializeCrashpad. 36 // Returns false if called before SetDumpWithoutCrashingFunction. 37 // 38 // This function must not be called with a tail call because that would cause 39 // the caller to be omitted from the call stack in the crash dump, and that is 40 // confusing and omits what is likely the most important context. 41 // 42 // Note: Calls to this function will not be throttled. To avoid performance 43 // problems if this is called many times in quick succession, prefer using one 44 // of the below variants. 45 NOT_TAIL_CALLED BASE_EXPORT bool DumpWithoutCrashingUnthrottled(); 46 47 // Handler to silently dump the current process without crashing, that keeps 48 // track of call location so some throttling can be applied to avoid very 49 // frequent dump captures, which can have side-effects. 50 // `location` Location of the file from where the function is called. 51 // `time_between_dumps` Time until the next dump should be captured. 52 NOT_TAIL_CALLED BASE_EXPORT bool DumpWithoutCrashing( 53 const base::Location& location = base::Location::Current(), 54 base::TimeDelta time_between_dumps = base::Minutes(5)); 55 56 // Handler to silently dump the current process without crashing that takes a 57 // location and unique id to keep a track and apply throttling. This function 58 // should be used when a domain wishes to capture dumps for multiple, unique 59 // reasons from a single location. An example would be unique bad mojo 60 // messages, or a value outside an expected range and the value should be 61 // considered interesting in the dump. The goal is to allow a single call to 62 // generate multiple dumps as needed and throttle future instances of the same 63 // identifiers for a short period of time. 64 // `unique_identifier` Hash to uniquely identify the function call. Consider 65 // using base::FastHash to generate the hash. 66 // `location` Location of the file from where the function is called. 67 // `time_between_dumps` Time until the next dump should be captured. 68 // Note: 69 // - The unique identifier, as of now, is not comparable across different 70 // runs or builds and is stable only for a process lifetime. 71 // - The unique identifier is not recorded in the crash report. See 72 // crash_logging.h for such a purpose. 73 NOT_TAIL_CALLED BASE_EXPORT bool DumpWithoutCrashingWithUniqueId( 74 size_t unique_identifier, 75 const base::Location& location = base::Location::Current(), 76 base::TimeDelta time_between_dumps = base::Minutes(5)); 77 78 // Sets a function that'll be invoked to dump the current process when 79 // DumpWithoutCrashing* is called. May be called with null to remove a 80 // previously set function. 81 BASE_EXPORT void SetDumpWithoutCrashingFunction(void (CDECL *function)()); 82 83 // Clear both maps used to throttle calls to DumpWithoutCrashing for testing. 84 BASE_EXPORT void ClearMapsForTesting(); 85 86 } // namespace debug 87 } // namespace base 88 89 #endif // BASE_DEBUG_DUMP_WITHOUT_CRASHING_H_ 90