1 // Copyright (c) 2012 The Chromium Authors. All rights reserved. 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_CRASH_LOGGING_H_ 6 #define BASE_DEBUG_CRASH_LOGGING_H_ 7 8 #include <string> 9 #include <vector> 10 11 #include "base/base_export.h" 12 #include "base/basictypes.h" 13 #include "base/strings/string_piece.h" 14 15 // These functions add metadata to the upload payload when sending crash reports 16 // to the crash server. 17 // 18 // IMPORTANT: On OS X and Linux, the key/value pairs are only sent as part of 19 // the upload and are not included in the minidump! 20 21 namespace base { 22 namespace debug { 23 24 class StackTrace; 25 26 // Set or clear a specific key-value pair from the crash metadata. Keys and 27 // values are terminated at the null byte. 28 BASE_EXPORT void SetCrashKeyValue(const base::StringPiece& key, 29 const base::StringPiece& value); 30 BASE_EXPORT void ClearCrashKey(const base::StringPiece& key); 31 32 // Records the given StackTrace into a crash key. 33 BASE_EXPORT void SetCrashKeyToStackTrace(const base::StringPiece& key, 34 const StackTrace& trace); 35 36 // Formats |count| instruction pointers from |addresses| using %p and 37 // sets the resulting string as a value for crash key |key|. A maximum of 23 38 // items will be encoded, since breakpad limits values to 255 bytes. 39 BASE_EXPORT void SetCrashKeyFromAddresses(const base::StringPiece& key, 40 const void* const* addresses, 41 size_t count); 42 43 // A scoper that sets the specified key to value for the lifetime of the 44 // object, and clears it on destruction. 45 class BASE_EXPORT ScopedCrashKey { 46 public: 47 ScopedCrashKey(const base::StringPiece& key, const base::StringPiece& value); 48 ~ScopedCrashKey(); 49 50 private: 51 std::string key_; 52 53 DISALLOW_COPY_AND_ASSIGN(ScopedCrashKey); 54 }; 55 56 // Before setting values for a key, all the keys must be registered. 57 struct BASE_EXPORT CrashKey { 58 // The name of the crash key, used in the above functions. 59 const char* key_name; 60 61 // The maximum length for a value. If the value is longer than this, it will 62 // be truncated. If the value is larger than the |chunk_max_length| passed to 63 // InitCrashKeys() but less than this value, it will be split into multiple 64 // numbered chunks. 65 size_t max_length; 66 }; 67 68 // Before the crash key logging mechanism can be used, all crash keys must be 69 // registered with this function. The function returns the amount of space 70 // the crash reporting implementation should allocate space for the registered 71 // crash keys. |chunk_max_length| is the maximum size that a value in a single 72 // chunk can be. 73 BASE_EXPORT size_t InitCrashKeys(const CrashKey* const keys, size_t count, 74 size_t chunk_max_length); 75 76 // Returns the correspnding crash key object or NULL for a given key. 77 BASE_EXPORT const CrashKey* LookupCrashKey(const base::StringPiece& key); 78 79 // In the platform crash reporting implementation, these functions set and 80 // clear the NUL-termianted key-value pairs. 81 typedef void (*SetCrashKeyValueFuncT)(const base::StringPiece&, 82 const base::StringPiece&); 83 typedef void (*ClearCrashKeyValueFuncT)(const base::StringPiece&); 84 85 // Sets the function pointers that are used to integrate with the platform- 86 // specific crash reporting libraries. 87 BASE_EXPORT void SetCrashKeyReportingFunctions( 88 SetCrashKeyValueFuncT set_key_func, 89 ClearCrashKeyValueFuncT clear_key_func); 90 91 // Helper function that breaks up a value according to the parameters 92 // specified by the crash key object. 93 BASE_EXPORT std::vector<std::string> ChunkCrashKeyValue( 94 const CrashKey& crash_key, 95 const base::StringPiece& value, 96 size_t chunk_max_length); 97 98 // Resets the crash key system so it can be reinitialized. For testing only. 99 BASE_EXPORT void ResetCrashLoggingForTesting(); 100 101 } // namespace debug 102 } // namespace base 103 104 #endif // BASE_DEBUG_CRASH_LOGGING_H_ 105