file_net_log_observer.h 6.7 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170
  1. // Copyright 2016 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. #ifndef NET_LOG_FILE_NET_LOG_OBSERVER_H_
  5. #define NET_LOG_FILE_NET_LOG_OBSERVER_H_
  6. #include <limits>
  7. #include <memory>
  8. #include "base/callback.h"
  9. #include "base/files/file.h"
  10. #include "base/memory/ref_counted.h"
  11. #include "net/base/net_export.h"
  12. #include "net/log/net_log.h"
  13. #include "third_party/abseil-cpp/absl/types/optional.h"
  14. namespace base {
  15. class Value;
  16. class FilePath;
  17. class SequencedTaskRunner;
  18. } // namespace base
  19. namespace net {
  20. // FileNetLogObserver watches the NetLog event stream and sends all entries to
  21. // a file.
  22. //
  23. // Consumers must call StartObserving before calling StopObserving, and must
  24. // call each method exactly once in the lifetime of the observer.
  25. //
  26. // The log will not be completely written until StopObserving is called.
  27. //
  28. // When a file size limit is given, FileNetLogObserver will create temporary
  29. // directory containing chunks of events. This is used to drop older events in
  30. // favor of newer ones.
  31. class NET_EXPORT FileNetLogObserver : public NetLog::ThreadSafeObserver {
  32. public:
  33. // Special value meaning "can use an unlimited number of bytes".
  34. static constexpr uint64_t kNoLimit = std::numeric_limits<uint64_t>::max();
  35. // Creates an instance of FileNetLogObserver that writes observed netlog
  36. // events to |log_path|.
  37. //
  38. // |log_path| is where the final log file will be written to. If a file
  39. // already exists at this path it will be overwritten. While logging is in
  40. // progress, events may be written to a like-named directory.
  41. //
  42. // |max_total_size| is the limit on how many bytes logging may consume on
  43. // disk. This is an approximate limit, and in practice FileNetLogObserver may
  44. // (slightly) exceed it. This may be set to kNoLimit to remove any size
  45. // restrictions.
  46. //
  47. // |constants| is an optional legend for decoding constant values used in
  48. // the log. It should generally be a modified version of GetNetConstants().
  49. // If not present, the output of GetNetConstants() will be used.
  50. static std::unique_ptr<FileNetLogObserver> CreateBounded(
  51. const base::FilePath& log_path,
  52. uint64_t max_total_size,
  53. NetLogCaptureMode capture_mode,
  54. std::unique_ptr<base::Value> constants);
  55. // Shortcut for calling CreateBounded() with kNoLimit.
  56. static std::unique_ptr<FileNetLogObserver> CreateUnbounded(
  57. const base::FilePath& log_path,
  58. NetLogCaptureMode capture_mode,
  59. std::unique_ptr<base::Value> constants);
  60. // Creates a bounded log that writes to a pre-existing file (truncating
  61. // it to start with, and closing it upon completion). |inprogress_dir_path|
  62. // will be used as a scratch directory, for temporary files (with predictable
  63. // names).
  64. static std::unique_ptr<FileNetLogObserver> CreateBoundedPreExisting(
  65. const base::FilePath& inprogress_dir_path,
  66. base::File output_file,
  67. uint64_t max_total_size,
  68. NetLogCaptureMode capture_mode,
  69. std::unique_ptr<base::Value> constants);
  70. // Creates an unbounded log that writes to a pre-existing file (truncating
  71. // it to start with, and closing it upon completion).
  72. static std::unique_ptr<FileNetLogObserver> CreateUnboundedPreExisting(
  73. base::File output_file,
  74. NetLogCaptureMode capture_mode,
  75. std::unique_ptr<base::Value> constants);
  76. FileNetLogObserver(const FileNetLogObserver&) = delete;
  77. FileNetLogObserver& operator=(const FileNetLogObserver&) = delete;
  78. ~FileNetLogObserver() override;
  79. // Attaches this observer to |net_log| and begins observing events.
  80. void StartObserving(NetLog* net_log);
  81. // Stops observing net_log() and closes the output file(s). Must be called
  82. // after StartObserving. Should be called before destruction of the
  83. // FileNetLogObserver and the NetLog, or the NetLog files (except for an
  84. // externally provided output_file) will be deleted when the observer is
  85. // destroyed. Note that it is OK to destroy |this| immediately after calling
  86. // StopObserving() - the callback will still be called once the file writing
  87. // has completed.
  88. //
  89. // |polled_data| is an optional argument used to add additional network stack
  90. // state to the log.
  91. //
  92. // If non-null, |optional_callback| will be run on whichever thread
  93. // StopObserving() was called on once all file writing is complete and the
  94. // netlog files can be accessed safely.
  95. void StopObserving(std::unique_ptr<base::Value> polled_data,
  96. base::OnceClosure optional_callback);
  97. // NetLog::ThreadSafeObserver
  98. void OnAddEntry(const NetLogEntry& entry) override;
  99. // Same as CreateBounded() but you can additionally specify
  100. // |total_num_event_files|.
  101. static std::unique_ptr<FileNetLogObserver> CreateBoundedForTests(
  102. const base::FilePath& log_path,
  103. uint64_t max_total_size,
  104. size_t total_num_event_files,
  105. NetLogCaptureMode capture_mode,
  106. std::unique_ptr<base::Value> constants);
  107. private:
  108. class WriteQueue;
  109. class FileWriter;
  110. static std::unique_ptr<FileNetLogObserver> CreateInternal(
  111. const base::FilePath& log_path,
  112. const base::FilePath& inprogress_dir_path,
  113. absl::optional<base::File> pre_existing_out_file,
  114. uint64_t max_total_size,
  115. size_t total_num_event_files,
  116. NetLogCaptureMode capture_mode,
  117. std::unique_ptr<base::Value> constants);
  118. FileNetLogObserver(scoped_refptr<base::SequencedTaskRunner> file_task_runner,
  119. std::unique_ptr<FileWriter> file_writer,
  120. scoped_refptr<WriteQueue> write_queue,
  121. NetLogCaptureMode capture_mode,
  122. std::unique_ptr<base::Value> constants);
  123. static std::string CaptureModeToString(NetLogCaptureMode mode);
  124. scoped_refptr<base::SequencedTaskRunner> file_task_runner_;
  125. // The |write_queue_| object is shared between the file task runner and the
  126. // main thread, and should be alive for the entirety of the observer's
  127. // lifetime. It should be destroyed once both the observer has been destroyed
  128. // and all tasks posted to the file task runner have completed.
  129. scoped_refptr<WriteQueue> write_queue_;
  130. // The FileNetLogObserver is shared between the main thread and
  131. // |file_task_runner_|.
  132. //
  133. // Conceptually FileNetLogObserver owns it, however on destruction its
  134. // deletion is deferred until outstanding tasks on |file_task_runner_| have
  135. // finished (since it is posted using base::Unretained()).
  136. std::unique_ptr<FileWriter> file_writer_;
  137. const NetLogCaptureMode capture_mode_;
  138. };
  139. // Serializes |value| to a JSON string used when writing to a file.
  140. NET_EXPORT_PRIVATE std::string SerializeNetLogValueToJson(
  141. const base::Value& value);
  142. } // namespace net
  143. #endif // NET_LOG_FILE_NET_LOG_OBSERVER_H_