crash_logging.h 3.98 KB
Newer Older
gejun's avatar
gejun committed
1 2 3 4
// Copyright (c) 2012 The Chromium Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.

5 6
#ifndef BUTIL_DEBUG_CRASH_LOGGING_H_
#define BUTIL_DEBUG_CRASH_LOGGING_H_
gejun's avatar
gejun committed
7 8 9 10

#include <string>
#include <vector>

11 12 13
#include "butil/base_export.h"
#include "butil/basictypes.h"
#include "butil/strings/string_piece.h"
gejun's avatar
gejun committed
14 15 16 17 18 19 20

// These functions add metadata to the upload payload when sending crash reports
// to the crash server.
//
// IMPORTANT: On OS X and Linux, the key/value pairs are only sent as part of
// the upload and are not included in the minidump!

21
namespace butil {
gejun's avatar
gejun committed
22 23 24 25 26 27
namespace debug {

class StackTrace;

// Set or clear a specific key-value pair from the crash metadata. Keys and
// values are terminated at the null byte.
28
BUTIL_EXPORT void SetCrashKeyValue(const butil::StringPiece& key,
29
                                  const butil::StringPiece& value);
30
BUTIL_EXPORT void ClearCrashKey(const butil::StringPiece& key);
gejun's avatar
gejun committed
31 32

// Records the given StackTrace into a crash key.
33
BUTIL_EXPORT void SetCrashKeyToStackTrace(const butil::StringPiece& key,
gejun's avatar
gejun committed
34 35 36 37 38
                                         const StackTrace& trace);

// Formats |count| instruction pointers from |addresses| using %p and
// sets the resulting string as a value for crash key |key|. A maximum of 23
// items will be encoded, since breakpad limits values to 255 bytes.
39
BUTIL_EXPORT void SetCrashKeyFromAddresses(const butil::StringPiece& key,
gejun's avatar
gejun committed
40 41 42 43 44
                                          const void* const* addresses,
                                          size_t count);

// A scoper that sets the specified key to value for the lifetime of the
// object, and clears it on destruction.
45
class BUTIL_EXPORT ScopedCrashKey {
gejun's avatar
gejun committed
46
 public:
47
  ScopedCrashKey(const butil::StringPiece& key, const butil::StringPiece& value);
gejun's avatar
gejun committed
48 49 50 51 52 53 54 55 56
  ~ScopedCrashKey();

 private:
  std::string key_;

  DISALLOW_COPY_AND_ASSIGN(ScopedCrashKey);
};

// Before setting values for a key, all the keys must be registered.
57
struct BUTIL_EXPORT CrashKey {
gejun's avatar
gejun committed
58 59 60 61 62 63 64 65 66 67 68 69 70 71 72
  // The name of the crash key, used in the above functions.
  const char* key_name;

  // The maximum length for a value. If the value is longer than this, it will
  // be truncated. If the value is larger than the |chunk_max_length| passed to
  // InitCrashKeys() but less than this value, it will be split into multiple
  // numbered chunks.
  size_t max_length;
};

// Before the crash key logging mechanism can be used, all crash keys must be
// registered with this function. The function returns the amount of space
// the crash reporting implementation should allocate space for the registered
// crash keys. |chunk_max_length| is the maximum size that a value in a single
// chunk can be.
73
BUTIL_EXPORT size_t InitCrashKeys(const CrashKey* const keys, size_t count,
gejun's avatar
gejun committed
74 75 76
                                 size_t chunk_max_length);

// Returns the correspnding crash key object or NULL for a given key.
77
BUTIL_EXPORT const CrashKey* LookupCrashKey(const butil::StringPiece& key);
gejun's avatar
gejun committed
78 79 80

// In the platform crash reporting implementation, these functions set and
// clear the NUL-termianted key-value pairs.
81 82 83
typedef void (*SetCrashKeyValueFuncT)(const butil::StringPiece&,
                                      const butil::StringPiece&);
typedef void (*ClearCrashKeyValueFuncT)(const butil::StringPiece&);
gejun's avatar
gejun committed
84 85 86

// Sets the function pointers that are used to integrate with the platform-
// specific crash reporting libraries.
87
BUTIL_EXPORT void SetCrashKeyReportingFunctions(
gejun's avatar
gejun committed
88 89 90 91 92
    SetCrashKeyValueFuncT set_key_func,
    ClearCrashKeyValueFuncT clear_key_func);

// Helper function that breaks up a value according to the parameters
// specified by the crash key object.
93
BUTIL_EXPORT std::vector<std::string> ChunkCrashKeyValue(
gejun's avatar
gejun committed
94
    const CrashKey& crash_key,
95
    const butil::StringPiece& value,
gejun's avatar
gejun committed
96 97 98
    size_t chunk_max_length);

// Resets the crash key system so it can be reinitialized. For testing only.
99
BUTIL_EXPORT void ResetCrashLoggingForTesting();
gejun's avatar
gejun committed
100 101

}  // namespace debug
102
}  // namespace butil
gejun's avatar
gejun committed
103

104
#endif  // BUTIL_DEBUG_CRASH_LOGGING_H_