1 // Copyright 2012 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_CRASH_LOGGING_H_ 6 #define BASE_DEBUG_CRASH_LOGGING_H_ 7 8 #include <stddef.h> 9 10 #include <iosfwd> 11 #include <memory> 12 #include <type_traits> 13 14 #include "base/base_export.h" 15 #include "base/memory/raw_ptr.h" 16 #include "base/strings/string_number_conversions.h" 17 #include "base/strings/string_piece.h" 18 19 namespace base { 20 namespace debug { 21 22 // A crash key is an annotation that is carried along with a crash report, to 23 // provide additional debugging information beyond a stack trace. Crash keys 24 // have a name and a string value. 25 // 26 // The preferred API is //components/crash/core/common:crash_key, however not 27 // all clients can hold a direct dependency on that target. The API provided 28 // in this file indirects the dependency and adds some convenience helpers that 29 // make the API a bit less clunky. 30 // 31 // TODO(dcheng): Some of the nicer APIs should probably be upstreamed into 32 // //components/crash. 33 // 34 // Preferred usage when a crash key value only needs to be set within a scope: 35 // 36 // SCOPED_CRASH_KEY_STRING32("category", "name", "value"); 37 // base::debug::DumpWithoutCrashing(); 38 // 39 // If the crash key is pre-allocated elsewhere, but the value only needs to be 40 // set within a scope: 41 // 42 // base::debug::ScopedCrashKeyString scoper( 43 // GetCrashKeyForComponent(), 44 // "value"); 45 // 46 // Otherwise, if the crash key needs to persist (e.g. the actual crash dump is 47 // triggered some time later asynchronously): 48 // 49 // static auto* const crash_key = base::debug::AllocateCrashKeyString( 50 // "name", base::debug::CrashKeySize::Size32); 51 // base::debug::SetCrashKeyString(crash_key, "value"); 52 // 53 // // Do other work before calling `base::debug::DumpWithoutCrashing()` later. 54 // 55 // ***WARNING*** 56 // 57 // Do *not* write this: 58 // 59 // base::debug::SetCrashKeyString( 60 // base::debug::AllocateCrashKeyString( 61 // "name", base::debug::CrashKeySize::Size32), 62 // "value"); 63 // 64 // As this will leak a heap allocation every time the crash key is set! 65 66 // The maximum length for a crash key's value must be one of the following 67 // pre-determined values. 68 enum class CrashKeySize { 69 Size32 = 32, 70 Size64 = 64, 71 Size256 = 256, 72 Size1024 = 1024, 73 }; 74 75 struct CrashKeyString; 76 77 // Allocates a new crash key with the specified |name| with storage for a 78 // value up to length |size|. This will return null if the crash key system is 79 // not initialized. 80 // 81 // Note: this internally allocates, so the returned pointer should always 82 // be cached in a variable with static storage duration, e.g.: 83 // static auto* const crash_key = base::debug::AllocateCrashKeyString(...); 84 BASE_EXPORT CrashKeyString* AllocateCrashKeyString(const char name[], 85 CrashKeySize size); 86 87 // Stores |value| into the specified |crash_key|. The |crash_key| may be null 88 // if AllocateCrashKeyString() returned null. If |value| is longer than the 89 // size with which the key was allocated, it will be truncated. 90 BASE_EXPORT void SetCrashKeyString(CrashKeyString* crash_key, 91 base::StringPiece value); 92 93 // Clears any value that was stored in |crash_key|. The |crash_key| may be 94 // null. 95 BASE_EXPORT void ClearCrashKeyString(CrashKeyString* crash_key); 96 97 // Outputs current (i.e. allocated and non-empty) crash keys to `out`. 98 BASE_EXPORT void OutputCrashKeysToStream(std::ostream& out); 99 100 // A scoper that sets the specified key to value for the lifetime of the 101 // object, and clears it on destruction. 102 class BASE_EXPORT ScopedCrashKeyString { 103 public: 104 ScopedCrashKeyString(CrashKeyString* crash_key, base::StringPiece value); 105 ScopedCrashKeyString(ScopedCrashKeyString&& other); 106 ~ScopedCrashKeyString(); 107 108 // Disallow copy and assign. 109 ScopedCrashKeyString(const ScopedCrashKeyString&) = delete; 110 ScopedCrashKeyString& operator=(const ScopedCrashKeyString&) = delete; 111 112 // Disallow move assign to keep the time at which the crash key is cleared 113 // easy to reason about. Assigning over an existing instance would 114 // automatically clear the key instead of at the destruction of the object. 115 ScopedCrashKeyString& operator=(ScopedCrashKeyString&&) = delete; 116 117 private: 118 raw_ptr<CrashKeyString> crash_key_; 119 }; 120 121 // Internal helpers for the SCOPED_CRASH_KEY_... helper macros defined below. 122 // 123 // The static_assert that checks the length of |key_name| is a compile-time 124 // equivalent of the DCHECK in crash_reporter::internal::CrashKeyStringImpl::Set 125 // that restricts the name of a crash key to 40 characters. 126 #define SCOPED_CRASH_KEY_STRING_INTERNAL2(category, name, nonce, data, \ 127 key_size) \ 128 static_assert(::std::size(category "-" name) < 40, \ 129 "Crash key names must be shorter than 40 characters."); \ 130 ::base::debug::ScopedCrashKeyString scoped_crash_key_helper##nonce( \ 131 [] { \ 132 static auto* const key = ::base::debug::AllocateCrashKeyString( \ 133 category "-" name, key_size); \ 134 return key; \ 135 }(), \ 136 (data)) 137 138 // This indirection is needed to expand __COUNTER__. 139 #define SCOPED_CRASH_KEY_STRING_INTERNAL(category, name, nonce, data, \ 140 key_size) \ 141 SCOPED_CRASH_KEY_STRING_INTERNAL2(category, name, nonce, data, key_size) 142 143 // Helper macros for putting a local variable crash key on the stack before 144 // causing a crash or calling CrashWithoutDumping(). `category` and `name` 145 // should be string literals. 146 // 147 // SCOPED_CRASH_KEY_STRING32("MyCategory", "key_name", "value"); 148 // 149 // will set the crash key annotation named "MyCategory-key_name" to "value" 150 // while in scope. 151 #define SCOPED_CRASH_KEY_STRING32(category, name, data) \ 152 SCOPED_CRASH_KEY_STRING_INTERNAL(category, name, __COUNTER__, (data), \ 153 ::base::debug::CrashKeySize::Size32) 154 155 #define SCOPED_CRASH_KEY_STRING64(category, name, data) \ 156 SCOPED_CRASH_KEY_STRING_INTERNAL(category, name, __COUNTER__, (data), \ 157 ::base::debug::CrashKeySize::Size64) 158 159 #define SCOPED_CRASH_KEY_STRING256(category, name, data) \ 160 SCOPED_CRASH_KEY_STRING_INTERNAL(category, name, __COUNTER__, (data), \ 161 ::base::debug::CrashKeySize::Size256) 162 163 #define SCOPED_CRASH_KEY_STRING1024(category, name, data) \ 164 SCOPED_CRASH_KEY_STRING_INTERNAL(category, name, __COUNTER__, (data), \ 165 ::base::debug::CrashKeySize::Size1024) 166 167 #define SCOPED_CRASH_KEY_BOOL(category, name, data) \ 168 static_assert(std::is_same<std::decay_t<decltype(data)>, bool>::value, \ 169 "SCOPED_CRASH_KEY_BOOL must be passed a boolean value."); \ 170 SCOPED_CRASH_KEY_STRING32(category, name, (data) ? "true" : "false") 171 172 #define SCOPED_CRASH_KEY_NUMBER(category, name, data) \ 173 SCOPED_CRASH_KEY_STRING32(category, name, ::base::NumberToString(data)) 174 175 //////////////////////////////////////////////////////////////////////////////// 176 // The following declarations are used to initialize the crash key system 177 // in //base by providing implementations for the above functions. 178 179 // The virtual interface that provides the implementation for the crash key 180 // API. This is implemented by a higher-layer component, and the instance is 181 // set using the function below. 182 class CrashKeyImplementation { 183 public: 184 virtual ~CrashKeyImplementation() = default; 185 186 virtual CrashKeyString* Allocate(const char name[], CrashKeySize size) = 0; 187 virtual void Set(CrashKeyString* crash_key, base::StringPiece value) = 0; 188 virtual void Clear(CrashKeyString* crash_key) = 0; 189 virtual void OutputCrashKeysToStream(std::ostream& out) = 0; 190 }; 191 192 // Initializes the crash key system in base by replacing the existing 193 // implementation, if it exists, with |impl|. The |impl| is copied into base. 194 BASE_EXPORT void SetCrashKeyImplementation( 195 std::unique_ptr<CrashKeyImplementation> impl); 196 197 // The base structure for a crash key, storing the allocation metadata. 198 struct CrashKeyString { CrashKeyStringCrashKeyString199 constexpr CrashKeyString(const char name[], CrashKeySize size) 200 : name(name), size(size) {} 201 const char* const name; 202 const CrashKeySize size; 203 }; 204 205 } // namespace debug 206 } // namespace base 207 208 #endif // BASE_DEBUG_CRASH_LOGGING_H_ 209