base/debug/crash_logging.h

   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_