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. 27 BASE_EXPORT void SetCrashKeyValue(const base::StringPiece& key, 28 const base::StringPiece& value); 29 BASE_EXPORT void ClearCrashKey(const base::StringPiece& key); 30 31 // Records the given StackTrace into a crash key. 32 BASE_EXPORT void SetCrashKeyToStackTrace(const base::StringPiece& key, 33 const StackTrace& trace); 34 35 // Formats |count| instruction pointers from |addresses| using %p and 36 // sets the resulting string as a value for crash key |key|. A maximum of 23 37 // items will be encoded, since breakpad limits values to 255 bytes. 38 BASE_EXPORT void SetCrashKeyFromAddresses(const base::StringPiece& key, 39 const void* const* addresses, 40 size_t count); 41 42 // A scoper that sets the specified key to value for the lifetime of the 43 // object, and clears it on destruction. 44 class BASE_EXPORT ScopedCrashKey { 45 public: 46 ScopedCrashKey(const base::StringPiece& key, const base::StringPiece& value); 47 ~ScopedCrashKey(); 48 49 private: 50 std::string key_; 51 52 DISALLOW_COPY_AND_ASSIGN(ScopedCrashKey); 53 }; 54 55 // Before setting values for a key, all the keys must be registered. 56 struct BASE_EXPORT CrashKey { 57 // The name of the crash key, used in the above functions. 58 const char* const key_name; 59 60 // The maximum length for a value. If the value is longer than this, it will 61 // be truncated. If the value is larger than the |chunk_max_length| passed to 62 // InitCrashKeys() but less than this value, it will be split into multiple 63 // numbered chunks. 64 size_t max_length; 65 }; 66 67 // Before the crash key logging mechanism can be used, all crash keys must be 68 // registered with this function. The function returns the amount of space 69 // the crash reporting implementation should allocate space for the registered 70 // crash keys. |chunk_max_length| is the maximum size that a value in a single 71 // chunk can be. 72 BASE_EXPORT size_t InitCrashKeys(const CrashKey* const keys, size_t count, 73 size_t chunk_max_length); 74 75 // Returns the correspnding crash key object or NULL for a given key. 76 BASE_EXPORT const CrashKey* LookupCrashKey(const base::StringPiece& key); 77 78 typedef void (*SetCrashKeyValueFuncT)(const base::StringPiece&, 79 const base::StringPiece&); 80 typedef void (*ClearCrashKeyValueFuncT)(const base::StringPiece&); 81 82 // Sets the function pointers that are used to integrate with the platform- 83 // specific crash reporting libraries. 84 BASE_EXPORT void SetCrashKeyReportingFunctions( 85 SetCrashKeyValueFuncT set_key_func, 86 ClearCrashKeyValueFuncT clear_key_func); 87 88 // Helper function that breaks up a value according to the parameters 89 // specified by the crash key object. 90 BASE_EXPORT std::vector<std::string> ChunkCrashKeyValue( 91 const CrashKey& crash_key, 92 const base::StringPiece& value, 93 size_t chunk_max_length); 94 95 // Resets the crash key system so it can be reinitialized. For testing only. 96 BASE_EXPORT void ResetCrashLoggingForTesting(); 97 98 } // namespace debug 99 } // namespace base 100 101 #endif // BASE_DEBUG_CRASH_LOGGING_H_ 102