// Copyright 2015 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. #ifndef BASE_TRACE_EVENT_TRACE_LOG_H_ #define BASE_TRACE_EVENT_TRACE_LOG_H_ #include <stddef.h> #include <stdint.h> #include <memory> #include <string> #include <vector> #include "base/atomicops.h" #include "base/containers/hash_tables.h" #include "base/gtest_prod_util.h" #include "base/macros.h" #include "base/memory/scoped_vector.h" #include "base/trace_event/memory_dump_provider.h" #include "base/trace_event/trace_config.h" #include "base/trace_event/trace_event_impl.h" #include "build/build_config.h" namespace base { template <typename Type> struct DefaultSingletonTraits; class MessageLoop; class RefCountedString; namespace trace_event { struct TraceCategory; class TraceBuffer; class TraceBufferChunk; class TraceEvent; class TraceEventFilter; class TraceEventMemoryOverhead; struct BASE_EXPORT TraceLogStatus { TraceLogStatus(); ~TraceLogStatus(); uint32_t event_capacity; uint32_t event_count; }; class BASE_EXPORT TraceLog : public MemoryDumpProvider { public: // Argument passed to TraceLog::SetEnabled. enum Mode : uint8_t { // Enables normal tracing (recording trace events in the trace buffer). RECORDING_MODE = 1 << 0, // Trace events are enabled just for filtering but not for recording. Only // event filters config of |trace_config| argument is used. FILTERING_MODE = 1 << 1 }; static TraceLog* GetInstance(); // Get set of known category groups. This can change as new code paths are // reached. The known category groups are inserted into |category_groups|. void GetKnownCategoryGroups(std::vector<std::string>* category_groups); // Retrieves a copy (for thread-safety) of the current TraceConfig. TraceConfig GetCurrentTraceConfig() const; // Initializes the thread-local event buffer, if not already initialized and // if the current thread supports that (has a message loop). void InitializeThreadLocalEventBufferIfSupported(); // See TraceConfig comments for details on how to control which categories // will be traced. SetDisabled must be called distinctly for each mode that is // enabled. If tracing has already been enabled for recording, category filter // (enabled and disabled categories) will be merged into the current category // filter. Enabling RECORDING_MODE does not enable filters. Trace event // filters will be used only if FILTERING_MODE is set on |modes_to_enable|. // Conversely to RECORDING_MODE, FILTERING_MODE doesn't support upgrading, // i.e. filters can only be enabled if not previously enabled. void SetEnabled(const TraceConfig& trace_config, uint8_t modes_to_enable); // TODO(ssid): Remove the default SetEnabled and IsEnabled. They should take // Mode as argument. // Disables tracing for all categories for the specified |modes_to_disable| // only. Only RECORDING_MODE is taken as default |modes_to_disable|. void SetDisabled(); void SetDisabled(uint8_t modes_to_disable); // Returns true if TraceLog is enabled on recording mode. // Note: Returns false even if FILTERING_MODE is enabled. bool IsEnabled() { return enabled_modes_ & RECORDING_MODE; } // Returns a bitmap of enabled modes from TraceLog::Mode. uint8_t enabled_modes() { return enabled_modes_; } // The number of times we have begun recording traces. If tracing is off, // returns -1. If tracing is on, then it returns the number of times we have // recorded a trace. By watching for this number to increment, you can // passively discover when a new trace has begun. This is then used to // implement the TRACE_EVENT_IS_NEW_TRACE() primitive. int GetNumTracesRecorded(); #if defined(OS_ANDROID) void StartATrace(); void StopATrace(); void AddClockSyncMetadataEvent(); #endif // Enabled state listeners give a callback when tracing is enabled or // disabled. This can be used to tie into other library's tracing systems // on-demand. class BASE_EXPORT EnabledStateObserver { public: virtual ~EnabledStateObserver() = default; // Called just after the tracing system becomes enabled, outside of the // |lock_|. TraceLog::IsEnabled() is true at this point. virtual void OnTraceLogEnabled() = 0; // Called just after the tracing system disables, outside of the |lock_|. // TraceLog::IsEnabled() is false at this point. virtual void OnTraceLogDisabled() = 0; }; void AddEnabledStateObserver(EnabledStateObserver* listener); void RemoveEnabledStateObserver(EnabledStateObserver* listener); bool HasEnabledStateObserver(EnabledStateObserver* listener) const; // Asynchronous enabled state listeners. When tracing is enabled or disabled, // for each observer, a task for invoking its appropriate callback is posted // to the thread from which AddAsyncEnabledStateObserver() was called. This // allows the observer to be safely destroyed, provided that it happens on the // same thread that invoked AddAsyncEnabledStateObserver(). class BASE_EXPORT AsyncEnabledStateObserver { public: virtual ~AsyncEnabledStateObserver() = default; // Posted just after the tracing system becomes enabled, outside |lock_|. // TraceLog::IsEnabled() is true at this point. virtual void OnTraceLogEnabled() = 0; // Posted just after the tracing system becomes disabled, outside |lock_|. // TraceLog::IsEnabled() is false at this point. virtual void OnTraceLogDisabled() = 0; }; void AddAsyncEnabledStateObserver( WeakPtr<AsyncEnabledStateObserver> listener); void RemoveAsyncEnabledStateObserver(AsyncEnabledStateObserver* listener); bool HasAsyncEnabledStateObserver(AsyncEnabledStateObserver* listener) const; TraceLogStatus GetStatus() const; bool BufferIsFull() const; // Computes an estimate of the size of the TraceLog including all the retained // objects. void EstimateTraceMemoryOverhead(TraceEventMemoryOverhead* overhead); void SetArgumentFilterPredicate( const ArgumentFilterPredicate& argument_filter_predicate); // Flush all collected events to the given output callback. The callback will // be called one or more times either synchronously or asynchronously from // the current thread with IPC-bite-size chunks. The string format is // undefined. Use TraceResultBuffer to convert one or more trace strings to // JSON. The callback can be null if the caller doesn't want any data. // Due to the implementation of thread-local buffers, flush can't be // done when tracing is enabled. If called when tracing is enabled, the // callback will be called directly with (empty_string, false) to indicate // the end of this unsuccessful flush. Flush does the serialization // on the same thread if the caller doesn't set use_worker_thread explicitly. typedef base::Callback<void(const scoped_refptr<base::RefCountedString>&, bool has_more_events)> OutputCallback; void Flush(const OutputCallback& cb, bool use_worker_thread = false); // Cancels tracing and discards collected data. void CancelTracing(const OutputCallback& cb); // Called by TRACE_EVENT* macros, don't call this directly. // The name parameter is a category group for example: // TRACE_EVENT0("renderer,webkit", "WebViewImpl::HandleInputEvent") static const unsigned char* GetCategoryGroupEnabled(const char* name); static const char* GetCategoryGroupName( const unsigned char* category_group_enabled); // Called by TRACE_EVENT* macros, don't call this directly. // If |copy| is set, |name|, |arg_name1| and |arg_name2| will be deep copied // into the event; see "Memory scoping note" and TRACE_EVENT_COPY_XXX above. TraceEventHandle AddTraceEvent( char phase, const unsigned char* category_group_enabled, const char* name, const char* scope, unsigned long long id, int num_args, const char** arg_names, const unsigned char* arg_types, const unsigned long long* arg_values, std::unique_ptr<ConvertableToTraceFormat>* convertable_values, unsigned int flags); TraceEventHandle AddTraceEventWithBindId( char phase, const unsigned char* category_group_enabled, const char* name, const char* scope, unsigned long long id, unsigned long long bind_id, int num_args, const char** arg_names, const unsigned char* arg_types, const unsigned long long* arg_values, std::unique_ptr<ConvertableToTraceFormat>* convertable_values, unsigned int flags); TraceEventHandle AddTraceEventWithProcessId( char phase, const unsigned char* category_group_enabled, const char* name, const char* scope, unsigned long long id, int process_id, int num_args, const char** arg_names, const unsigned char* arg_types, const unsigned long long* arg_values, std::unique_ptr<ConvertableToTraceFormat>* convertable_values, unsigned int flags); TraceEventHandle AddTraceEventWithThreadIdAndTimestamp( char phase, const unsigned char* category_group_enabled, const char* name, const char* scope, unsigned long long id, int thread_id, const TimeTicks& timestamp, int num_args, const char** arg_names, const unsigned char* arg_types, const unsigned long long* arg_values, std::unique_ptr<ConvertableToTraceFormat>* convertable_values, unsigned int flags); TraceEventHandle AddTraceEventWithThreadIdAndTimestamp( char phase, const unsigned char* category_group_enabled, const char* name, const char* scope, unsigned long long id, unsigned long long bind_id, int thread_id, const TimeTicks& timestamp, int num_args, const char** arg_names, const unsigned char* arg_types, const unsigned long long* arg_values, std::unique_ptr<ConvertableToTraceFormat>* convertable_values, unsigned int flags); // Adds a metadata event that will be written when the trace log is flushed. void AddMetadataEvent( const unsigned char* category_group_enabled, const char* name, int num_args, const char** arg_names, const unsigned char* arg_types, const unsigned long long* arg_values, std::unique_ptr<ConvertableToTraceFormat>* convertable_values, unsigned int flags); void UpdateTraceEventDuration(const unsigned char* category_group_enabled, const char* name, TraceEventHandle handle); void EndFilteredEvent(const unsigned char* category_group_enabled, const char* name, TraceEventHandle handle); int process_id() const { return process_id_; } uint64_t MangleEventId(uint64_t id); // Exposed for unittesting: // Testing factory for TraceEventFilter. typedef std::unique_ptr<TraceEventFilter> (*FilterFactoryForTesting)( const std::string& /* predicate_name */); void SetFilterFactoryForTesting(FilterFactoryForTesting factory) { filter_factory_for_testing_ = factory; } // Allows deleting our singleton instance. static void DeleteForTesting(); // Allow tests to inspect TraceEvents. TraceEvent* GetEventByHandle(TraceEventHandle handle); void SetProcessID(int process_id); // Process sort indices, if set, override the order of a process will appear // relative to other processes in the trace viewer. Processes are sorted first // on their sort index, ascending, then by their name, and then tid. void SetProcessSortIndex(int sort_index); // Sets the name of the process. |process_name| should be a string literal // since it is a whitelisted argument for background field trials. void SetProcessName(const char* process_name); // Processes can have labels in addition to their names. Use labels, for // instance, to list out the web page titles that a process is handling. void UpdateProcessLabel(int label_id, const std::string& current_label); void RemoveProcessLabel(int label_id); // Thread sort indices, if set, override the order of a thread will appear // within its process in the trace viewer. Threads are sorted first on their // sort index, ascending, then by their name, and then tid. void SetThreadSortIndex(PlatformThreadId thread_id, int sort_index); // Allow setting an offset between the current TimeTicks time and the time // that should be reported. void SetTimeOffset(TimeDelta offset); size_t GetObserverCountForTest() const; // Call this method if the current thread may block the message loop to // prevent the thread from using the thread-local buffer because the thread // may not handle the flush request in time causing lost of unflushed events. void SetCurrentThreadBlocksMessageLoop(); #if defined(OS_WIN) // This function is called by the ETW exporting module whenever the ETW // keyword (flags) changes. This keyword indicates which categories should be // exported, so whenever it changes, we adjust accordingly. void UpdateETWCategoryGroupEnabledFlags(); #endif private: typedef unsigned int InternalTraceOptions; FRIEND_TEST_ALL_PREFIXES(TraceEventTestFixture, TraceBufferRingBufferGetReturnChunk); FRIEND_TEST_ALL_PREFIXES(TraceEventTestFixture, TraceBufferRingBufferHalfIteration); FRIEND_TEST_ALL_PREFIXES(TraceEventTestFixture, TraceBufferRingBufferFullIteration); FRIEND_TEST_ALL_PREFIXES(TraceEventTestFixture, TraceBufferVectorReportFull); FRIEND_TEST_ALL_PREFIXES(TraceEventTestFixture, ConvertTraceConfigToInternalOptions); FRIEND_TEST_ALL_PREFIXES(TraceEventTestFixture, TraceRecordAsMuchAsPossibleMode); // This allows constructor and destructor to be private and usable only // by the Singleton class. friend struct DefaultSingletonTraits<TraceLog>; // MemoryDumpProvider implementation. bool OnMemoryDump(const MemoryDumpArgs& args, ProcessMemoryDump* pmd) override; // Enable/disable each category group based on the current mode_, // category_filter_ and event_filters_enabled_. // Enable the category group in the recording mode if category_filter_ matches // the category group, is not null. Enable category for filtering if any // filter in event_filters_enabled_ enables it. void UpdateCategoryRegistry(); void UpdateCategoryState(TraceCategory* category); void CreateFiltersForTraceConfig(); // Configure synthetic delays based on the values set in the current // trace config. void UpdateSyntheticDelaysFromTraceConfig(); InternalTraceOptions GetInternalOptionsFromTraceConfig( const TraceConfig& config); class ThreadLocalEventBuffer; class OptionalAutoLock; struct RegisteredAsyncObserver; TraceLog(); ~TraceLog() override; void AddMetadataEventsWhileLocked(); InternalTraceOptions trace_options() const { return static_cast<InternalTraceOptions>( subtle::NoBarrier_Load(&trace_options_)); } TraceBuffer* trace_buffer() const { return logged_events_.get(); } TraceBuffer* CreateTraceBuffer(); std::string EventToConsoleMessage(unsigned char phase, const TimeTicks& timestamp, TraceEvent* trace_event); TraceEvent* AddEventToThreadSharedChunkWhileLocked(TraceEventHandle* handle, bool check_buffer_is_full); void CheckIfBufferIsFullWhileLocked(); void SetDisabledWhileLocked(uint8_t modes); TraceEvent* GetEventByHandleInternal(TraceEventHandle handle, OptionalAutoLock* lock); void FlushInternal(const OutputCallback& cb, bool use_worker_thread, bool discard_events); // |generation| is used in the following callbacks to check if the callback // is called for the flush of the current |logged_events_|. void FlushCurrentThread(int generation, bool discard_events); // Usually it runs on a different thread. static void ConvertTraceEventsToTraceFormat( std::unique_ptr<TraceBuffer> logged_events, const TraceLog::OutputCallback& flush_output_callback, const ArgumentFilterPredicate& argument_filter_predicate); void FinishFlush(int generation, bool discard_events); void OnFlushTimeout(int generation, bool discard_events); int generation() const { return static_cast<int>(subtle::NoBarrier_Load(&generation_)); } bool CheckGeneration(int generation) const { return generation == this->generation(); } void UseNextTraceBuffer(); TimeTicks OffsetNow() const { return OffsetTimestamp(TimeTicks::Now()); } TimeTicks OffsetTimestamp(const TimeTicks& timestamp) const { return timestamp - time_offset_; } // Internal representation of trace options since we store the currently used // trace option as an AtomicWord. static const InternalTraceOptions kInternalNone; static const InternalTraceOptions kInternalRecordUntilFull; static const InternalTraceOptions kInternalRecordContinuously; static const InternalTraceOptions kInternalEchoToConsole; static const InternalTraceOptions kInternalRecordAsMuchAsPossible; static const InternalTraceOptions kInternalEnableArgumentFilter; // This lock protects TraceLog member accesses (except for members protected // by thread_info_lock_) from arbitrary threads. mutable Lock lock_; // This lock protects accesses to thread_names_, thread_event_start_times_ // and thread_colors_. Lock thread_info_lock_; uint8_t enabled_modes_; // See TraceLog::Mode. int num_traces_recorded_; std::unique_ptr<TraceBuffer> logged_events_; std::vector<std::unique_ptr<TraceEvent>> metadata_events_; bool dispatching_to_observer_list_; std::vector<EnabledStateObserver*> enabled_state_observer_list_; std::map<AsyncEnabledStateObserver*, RegisteredAsyncObserver> async_observers_; std::string process_name_; base::hash_map<int, std::string> process_labels_; int process_sort_index_; base::hash_map<int, int> thread_sort_indices_; base::hash_map<int, std::string> thread_names_; // The following two maps are used only when ECHO_TO_CONSOLE. base::hash_map<int, std::stack<TimeTicks>> thread_event_start_times_; base::hash_map<std::string, int> thread_colors_; TimeTicks buffer_limit_reached_timestamp_; // XORed with TraceID to make it unlikely to collide with other processes. unsigned long long process_id_hash_; int process_id_; TimeDelta time_offset_; subtle::AtomicWord /* Options */ trace_options_; TraceConfig trace_config_; TraceConfig::EventFilters enabled_event_filters_; ThreadLocalPointer<ThreadLocalEventBuffer> thread_local_event_buffer_; ThreadLocalBoolean thread_blocks_message_loop_; ThreadLocalBoolean thread_is_in_trace_event_; // Contains the message loops of threads that have had at least one event // added into the local event buffer. Not using SingleThreadTaskRunner // because we need to know the life time of the message loops. hash_set<MessageLoop*> thread_message_loops_; // For events which can't be added into the thread local buffer, e.g. events // from threads without a message loop. std::unique_ptr<TraceBufferChunk> thread_shared_chunk_; size_t thread_shared_chunk_index_; // Set when asynchronous Flush is in progress. OutputCallback flush_output_callback_; scoped_refptr<SingleThreadTaskRunner> flush_task_runner_; ArgumentFilterPredicate argument_filter_predicate_; subtle::AtomicWord generation_; bool use_worker_thread_; FilterFactoryForTesting filter_factory_for_testing_; DISALLOW_COPY_AND_ASSIGN(TraceLog); }; } // namespace trace_event } // namespace base #endif // BASE_TRACE_EVENT_TRACE_LOG_H_