Add ICU message format support
[chromium-blink-merge.git] / base / trace_event / trace_log.h
blob510113ae11fa6c9887a1ed050b235d2f4091bb31
1 // Copyright 2015 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.
5 #ifndef BASE_TRACE_EVENT_TRACE_LOG_H_
6 #define BASE_TRACE_EVENT_TRACE_LOG_H_
8 #include "base/trace_event/memory_dump_provider.h"
9 #include "base/trace_event/trace_config.h"
10 #include "base/trace_event/trace_event_impl.h"
12 // Older style trace macros with explicit id and extra data
13 // Only these macros result in publishing data to ETW as currently implemented.
14 // TODO(georgesak): Update/replace these with new ETW macros.
15 #define TRACE_EVENT_BEGIN_ETW(name, id, extra) \
16 base::trace_event::TraceLog::AddTraceEventEtw( \
17 TRACE_EVENT_PHASE_BEGIN, name, reinterpret_cast<const void*>(id), extra)
19 #define TRACE_EVENT_END_ETW(name, id, extra) \
20 base::trace_event::TraceLog::AddTraceEventEtw( \
21 TRACE_EVENT_PHASE_END, name, reinterpret_cast<const void*>(id), extra)
23 #define TRACE_EVENT_INSTANT_ETW(name, id, extra) \
24 base::trace_event::TraceLog::AddTraceEventEtw( \
25 TRACE_EVENT_PHASE_INSTANT, name, reinterpret_cast<const void*>(id), \
26 extra)
28 template <typename Type>
29 struct DefaultSingletonTraits;
31 namespace base {
33 class RefCountedString;
35 namespace trace_event {
37 class TraceBuffer;
38 class TraceBufferChunk;
39 class TraceEvent;
40 class TraceEventMemoryOverhead;
41 class TraceSamplingThread;
43 struct BASE_EXPORT TraceLogStatus {
44 TraceLogStatus();
45 ~TraceLogStatus();
46 size_t event_capacity;
47 size_t event_count;
50 class BASE_EXPORT TraceLog : public MemoryDumpProvider {
51 public:
52 enum Mode {
53 DISABLED = 0,
54 RECORDING_MODE,
55 MONITORING_MODE,
58 // The pointer returned from GetCategoryGroupEnabledInternal() points to a
59 // value with zero or more of the following bits. Used in this class only.
60 // The TRACE_EVENT macros should only use the value as a bool.
61 // These values must be in sync with macro values in TraceEvent.h in Blink.
62 enum CategoryGroupEnabledFlags {
63 // Category group enabled for the recording mode.
64 ENABLED_FOR_RECORDING = 1 << 0,
65 // Category group enabled for the monitoring mode.
66 ENABLED_FOR_MONITORING = 1 << 1,
67 // Category group enabled by SetEventCallbackEnabled().
68 ENABLED_FOR_EVENT_CALLBACK = 1 << 2,
69 // Category group enabled to export events to ETW.
70 ENABLED_FOR_ETW_EXPORT = 1 << 3
73 static TraceLog* GetInstance();
75 // Get set of known category groups. This can change as new code paths are
76 // reached. The known category groups are inserted into |category_groups|.
77 void GetKnownCategoryGroups(std::vector<std::string>* category_groups);
79 // Retrieves a copy (for thread-safety) of the current TraceConfig.
80 TraceConfig GetCurrentTraceConfig() const;
82 // Initializes the thread-local event buffer, if not already initialized and
83 // if the current thread supports that (has a message loop).
84 void InitializeThreadLocalEventBufferIfSupported();
86 // Enables normal tracing (recording trace events in the trace buffer).
87 // See TraceConfig comments for details on how to control what categories
88 // will be traced. If tracing has already been enabled, |category_filter| will
89 // be merged into the current category filter.
90 void SetEnabled(const TraceConfig& trace_config, Mode mode);
92 // Disables normal tracing for all categories.
93 void SetDisabled();
95 bool IsEnabled() { return mode_ != DISABLED; }
97 // The number of times we have begun recording traces. If tracing is off,
98 // returns -1. If tracing is on, then it returns the number of times we have
99 // recorded a trace. By watching for this number to increment, you can
100 // passively discover when a new trace has begun. This is then used to
101 // implement the TRACE_EVENT_IS_NEW_TRACE() primitive.
102 int GetNumTracesRecorded();
104 #if defined(OS_ANDROID)
105 void StartATrace();
106 void StopATrace();
107 void AddClockSyncMetadataEvent();
108 #endif
110 // Enabled state listeners give a callback when tracing is enabled or
111 // disabled. This can be used to tie into other library's tracing systems
112 // on-demand.
113 class BASE_EXPORT EnabledStateObserver {
114 public:
115 virtual ~EnabledStateObserver() = default;
117 // Called just after the tracing system becomes enabled, outside of the
118 // |lock_|. TraceLog::IsEnabled() is true at this point.
119 virtual void OnTraceLogEnabled() = 0;
121 // Called just after the tracing system disables, outside of the |lock_|.
122 // TraceLog::IsEnabled() is false at this point.
123 virtual void OnTraceLogDisabled() = 0;
125 void AddEnabledStateObserver(EnabledStateObserver* listener);
126 void RemoveEnabledStateObserver(EnabledStateObserver* listener);
127 bool HasEnabledStateObserver(EnabledStateObserver* listener) const;
129 TraceLogStatus GetStatus() const;
130 bool BufferIsFull() const;
132 // Computes an estimate of the size of the TraceLog including all the retained
133 // objects.
134 void EstimateTraceMemoryOverhead(TraceEventMemoryOverhead* overhead);
136 // Not using base::Callback because of its limited by 7 parameters.
137 // Also, using primitive type allows directly passing callback from WebCore.
138 // WARNING: It is possible for the previously set callback to be called
139 // after a call to SetEventCallbackEnabled() that replaces or a call to
140 // SetEventCallbackDisabled() that disables the callback.
141 // This callback may be invoked on any thread.
142 // For TRACE_EVENT_PHASE_COMPLETE events, the client will still receive pairs
143 // of TRACE_EVENT_PHASE_BEGIN and TRACE_EVENT_PHASE_END events to keep the
144 // interface simple.
145 typedef void (*EventCallback)(TraceTicks timestamp,
146 char phase,
147 const unsigned char* category_group_enabled,
148 const char* name,
149 unsigned long long id,
150 int num_args,
151 const char* const arg_names[],
152 const unsigned char arg_types[],
153 const unsigned long long arg_values[],
154 unsigned int flags);
156 // Enable tracing for EventCallback.
157 void SetEventCallbackEnabled(const TraceConfig& trace_config,
158 EventCallback cb);
159 void SetEventCallbackDisabled();
160 void SetArgumentFilterPredicate(
161 const ArgumentFilterPredicate& argument_filter_predicate);
163 // Flush all collected events to the given output callback. The callback will
164 // be called one or more times either synchronously or asynchronously from
165 // the current thread with IPC-bite-size chunks. The string format is
166 // undefined. Use TraceResultBuffer to convert one or more trace strings to
167 // JSON. The callback can be null if the caller doesn't want any data.
168 // Due to the implementation of thread-local buffers, flush can't be
169 // done when tracing is enabled. If called when tracing is enabled, the
170 // callback will be called directly with (empty_string, false) to indicate
171 // the end of this unsuccessful flush. Flush does the serialization
172 // on the same thread if the caller doesn't set use_worker_thread explicitly.
173 typedef base::Callback<void(const scoped_refptr<base::RefCountedString>&,
174 bool has_more_events)> OutputCallback;
175 void Flush(const OutputCallback& cb, bool use_worker_thread = false);
176 void FlushButLeaveBufferIntact(const OutputCallback& flush_output_callback);
178 // Cancels tracing and discards collected data.
179 void CancelTracing(const OutputCallback& cb);
181 // Called by TRACE_EVENT* macros, don't call this directly.
182 // The name parameter is a category group for example:
183 // TRACE_EVENT0("renderer,webkit", "WebViewImpl::HandleInputEvent")
184 static const unsigned char* GetCategoryGroupEnabled(const char* name);
185 static const char* GetCategoryGroupName(
186 const unsigned char* category_group_enabled);
188 // Called by TRACE_EVENT* macros, don't call this directly.
189 // If |copy| is set, |name|, |arg_name1| and |arg_name2| will be deep copied
190 // into the event; see "Memory scoping note" and TRACE_EVENT_COPY_XXX above.
191 TraceEventHandle AddTraceEvent(
192 char phase,
193 const unsigned char* category_group_enabled,
194 const char* name,
195 unsigned long long id,
196 int num_args,
197 const char** arg_names,
198 const unsigned char* arg_types,
199 const unsigned long long* arg_values,
200 const scoped_refptr<ConvertableToTraceFormat>* convertable_values,
201 unsigned int flags);
202 TraceEventHandle AddTraceEventWithContextId(
203 char phase,
204 const unsigned char* category_group_enabled,
205 const char* name,
206 unsigned long long id,
207 unsigned long long context_id,
208 int num_args,
209 const char** arg_names,
210 const unsigned char* arg_types,
211 const unsigned long long* arg_values,
212 const scoped_refptr<ConvertableToTraceFormat>* convertable_values,
213 unsigned int flags);
214 TraceEventHandle AddTraceEventWithThreadIdAndTimestamp(
215 char phase,
216 const unsigned char* category_group_enabled,
217 const char* name,
218 unsigned long long id,
219 unsigned long long context_id,
220 int thread_id,
221 const TraceTicks& timestamp,
222 int num_args,
223 const char** arg_names,
224 const unsigned char* arg_types,
225 const unsigned long long* arg_values,
226 const scoped_refptr<ConvertableToTraceFormat>* convertable_values,
227 unsigned int flags);
228 TraceEventHandle AddTraceEventWithThreadIdAndTimestamp(
229 char phase,
230 const unsigned char* category_group_enabled,
231 const char* name,
232 unsigned long long id,
233 unsigned long long context_id,
234 unsigned long long bind_id,
235 int thread_id,
236 const TraceTicks& timestamp,
237 int num_args,
238 const char** arg_names,
239 const unsigned char* arg_types,
240 const unsigned long long* arg_values,
241 const scoped_refptr<ConvertableToTraceFormat>* convertable_values,
242 unsigned int flags);
243 static void AddTraceEventEtw(char phase,
244 const char* category_group,
245 const void* id,
246 const char* extra);
247 static void AddTraceEventEtw(char phase,
248 const char* category_group,
249 const void* id,
250 const std::string& extra);
252 void UpdateTraceEventDuration(const unsigned char* category_group_enabled,
253 const char* name,
254 TraceEventHandle handle);
256 // For every matching event, the callback will be called.
257 typedef base::Callback<void()> WatchEventCallback;
258 void SetWatchEvent(const std::string& category_name,
259 const std::string& event_name,
260 const WatchEventCallback& callback);
261 // Cancel the watch event. If tracing is enabled, this may race with the
262 // watch event notification firing.
263 void CancelWatchEvent();
265 int process_id() const { return process_id_; }
267 uint64 MangleEventId(uint64 id);
269 // Exposed for unittesting:
271 void WaitSamplingEventForTesting();
273 // Allows deleting our singleton instance.
274 static void DeleteForTesting();
276 // Allow tests to inspect TraceEvents.
277 TraceEvent* GetEventByHandle(TraceEventHandle handle);
279 void SetProcessID(int process_id);
281 // Process sort indices, if set, override the order of a process will appear
282 // relative to other processes in the trace viewer. Processes are sorted first
283 // on their sort index, ascending, then by their name, and then tid.
284 void SetProcessSortIndex(int sort_index);
286 // Sets the name of the process.
287 void SetProcessName(const std::string& process_name);
289 // Processes can have labels in addition to their names. Use labels, for
290 // instance, to list out the web page titles that a process is handling.
291 void UpdateProcessLabel(int label_id, const std::string& current_label);
292 void RemoveProcessLabel(int label_id);
294 // Thread sort indices, if set, override the order of a thread will appear
295 // within its process in the trace viewer. Threads are sorted first on their
296 // sort index, ascending, then by their name, and then tid.
297 void SetThreadSortIndex(PlatformThreadId thread_id, int sort_index);
299 // Allow setting an offset between the current TraceTicks time and the time
300 // that should be reported.
301 void SetTimeOffset(TimeDelta offset);
303 size_t GetObserverCountForTest() const;
305 // Call this method if the current thread may block the message loop to
306 // prevent the thread from using the thread-local buffer because the thread
307 // may not handle the flush request in time causing lost of unflushed events.
308 void SetCurrentThreadBlocksMessageLoop();
310 private:
311 typedef unsigned int InternalTraceOptions;
313 FRIEND_TEST_ALL_PREFIXES(TraceEventTestFixture,
314 TraceBufferRingBufferGetReturnChunk);
315 FRIEND_TEST_ALL_PREFIXES(TraceEventTestFixture,
316 TraceBufferRingBufferHalfIteration);
317 FRIEND_TEST_ALL_PREFIXES(TraceEventTestFixture,
318 TraceBufferRingBufferFullIteration);
319 FRIEND_TEST_ALL_PREFIXES(TraceEventTestFixture, TraceBufferVectorReportFull);
320 FRIEND_TEST_ALL_PREFIXES(TraceEventTestFixture,
321 ConvertTraceConfigToInternalOptions);
322 FRIEND_TEST_ALL_PREFIXES(TraceEventTestFixture,
323 TraceRecordAsMuchAsPossibleMode);
325 // This allows constructor and destructor to be private and usable only
326 // by the Singleton class.
327 friend struct DefaultSingletonTraits<TraceLog>;
329 // MemoryDumpProvider implementation.
330 bool OnMemoryDump(const MemoryDumpArgs& args,
331 ProcessMemoryDump* pmd) override;
333 // Enable/disable each category group based on the current mode_,
334 // category_filter_, event_callback_ and event_callback_category_filter_.
335 // Enable the category group in the enabled mode if category_filter_ matches
336 // the category group, or event_callback_ is not null and
337 // event_callback_category_filter_ matches the category group.
338 void UpdateCategoryGroupEnabledFlags();
339 void UpdateCategoryGroupEnabledFlag(size_t category_index);
341 // Configure synthetic delays based on the values set in the current
342 // trace config.
343 void UpdateSyntheticDelaysFromTraceConfig();
345 InternalTraceOptions GetInternalOptionsFromTraceConfig(
346 const TraceConfig& config);
348 class ThreadLocalEventBuffer;
349 class OptionalAutoLock;
351 TraceLog();
352 ~TraceLog() override;
353 const unsigned char* GetCategoryGroupEnabledInternal(const char* name);
354 void AddMetadataEventsWhileLocked();
356 InternalTraceOptions trace_options() const {
357 return static_cast<InternalTraceOptions>(
358 subtle::NoBarrier_Load(&trace_options_));
361 TraceBuffer* trace_buffer() const { return logged_events_.get(); }
362 TraceBuffer* CreateTraceBuffer();
364 std::string EventToConsoleMessage(unsigned char phase,
365 const TraceTicks& timestamp,
366 TraceEvent* trace_event);
368 TraceEvent* AddEventToThreadSharedChunkWhileLocked(TraceEventHandle* handle,
369 bool check_buffer_is_full);
370 void CheckIfBufferIsFullWhileLocked();
371 void SetDisabledWhileLocked();
373 TraceEvent* GetEventByHandleInternal(TraceEventHandle handle,
374 OptionalAutoLock* lock);
376 void FlushInternal(const OutputCallback& cb,
377 bool use_worker_thread,
378 bool discard_events);
380 // |generation| is used in the following callbacks to check if the callback
381 // is called for the flush of the current |logged_events_|.
382 void FlushCurrentThread(int generation, bool discard_events);
383 // Usually it runs on a different thread.
384 static void ConvertTraceEventsToTraceFormat(
385 scoped_ptr<TraceBuffer> logged_events,
386 const TraceLog::OutputCallback& flush_output_callback,
387 const ArgumentFilterPredicate& argument_filter_predicate);
388 void FinishFlush(int generation, bool discard_events);
389 void OnFlushTimeout(int generation, bool discard_events);
391 int generation() const {
392 return static_cast<int>(subtle::NoBarrier_Load(&generation_));
394 bool CheckGeneration(int generation) const {
395 return generation == this->generation();
397 void UseNextTraceBuffer();
399 TraceTicks OffsetNow() const { return OffsetTimestamp(TraceTicks::Now()); }
400 TraceTicks OffsetTimestamp(const TraceTicks& timestamp) const {
401 return timestamp - time_offset_;
404 // Internal representation of trace options since we store the currently used
405 // trace option as an AtomicWord.
406 static const InternalTraceOptions kInternalNone;
407 static const InternalTraceOptions kInternalRecordUntilFull;
408 static const InternalTraceOptions kInternalRecordContinuously;
409 static const InternalTraceOptions kInternalEchoToConsole;
410 static const InternalTraceOptions kInternalEnableSampling;
411 static const InternalTraceOptions kInternalRecordAsMuchAsPossible;
412 static const InternalTraceOptions kInternalEnableArgumentFilter;
414 // This lock protects TraceLog member accesses (except for members protected
415 // by thread_info_lock_) from arbitrary threads.
416 mutable Lock lock_;
417 // This lock protects accesses to thread_names_, thread_event_start_times_
418 // and thread_colors_.
419 Lock thread_info_lock_;
420 Mode mode_;
421 int num_traces_recorded_;
422 scoped_ptr<TraceBuffer> logged_events_;
423 subtle::AtomicWord /* EventCallback */ event_callback_;
424 bool dispatching_to_observer_list_;
425 std::vector<EnabledStateObserver*> enabled_state_observer_list_;
427 std::string process_name_;
428 base::hash_map<int, std::string> process_labels_;
429 int process_sort_index_;
430 base::hash_map<int, int> thread_sort_indices_;
431 base::hash_map<int, std::string> thread_names_;
433 // The following two maps are used only when ECHO_TO_CONSOLE.
434 base::hash_map<int, std::stack<TraceTicks>> thread_event_start_times_;
435 base::hash_map<std::string, int> thread_colors_;
437 TraceTicks buffer_limit_reached_timestamp_;
439 // XORed with TraceID to make it unlikely to collide with other processes.
440 unsigned long long process_id_hash_;
442 int process_id_;
444 TimeDelta time_offset_;
446 // Allow tests to wake up when certain events occur.
447 WatchEventCallback watch_event_callback_;
448 subtle::AtomicWord /* const unsigned char* */ watch_category_;
449 std::string watch_event_name_;
451 subtle::AtomicWord /* Options */ trace_options_;
453 // Sampling thread handles.
454 scoped_ptr<TraceSamplingThread> sampling_thread_;
455 PlatformThreadHandle sampling_thread_handle_;
457 TraceConfig trace_config_;
458 TraceConfig event_callback_trace_config_;
460 ThreadLocalPointer<ThreadLocalEventBuffer> thread_local_event_buffer_;
461 ThreadLocalBoolean thread_blocks_message_loop_;
462 ThreadLocalBoolean thread_is_in_trace_event_;
464 // Contains the message loops of threads that have had at least one event
465 // added into the local event buffer. Not using SingleThreadTaskRunner
466 // because we need to know the life time of the message loops.
467 hash_set<MessageLoop*> thread_message_loops_;
469 // For events which can't be added into the thread local buffer, e.g. events
470 // from threads without a message loop.
471 scoped_ptr<TraceBufferChunk> thread_shared_chunk_;
472 size_t thread_shared_chunk_index_;
474 // Set when asynchronous Flush is in progress.
475 OutputCallback flush_output_callback_;
476 scoped_refptr<SingleThreadTaskRunner> flush_task_runner_;
477 ArgumentFilterPredicate argument_filter_predicate_;
478 subtle::AtomicWord generation_;
479 bool use_worker_thread_;
481 DISALLOW_COPY_AND_ASSIGN(TraceLog);
484 } // namespace trace_event
485 } // namespace base
487 #endif // BASE_TRACE_EVENT_TRACE_LOG_H_