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.
5 // Use trace_analyzer::Query and trace_analyzer::TraceAnalyzer to search for
6 // specific trace events that were generated by the trace_event.h API.
9 // - Get trace events JSON string from base::debug::TraceLog.
10 // - Create TraceAnalyzer with JSON string.
11 // - Call TraceAnalyzer::AssociateBeginEndEvents (optional).
12 // - Call TraceAnalyzer::AssociateEvents (zero or more times).
13 // - Call TraceAnalyzer::FindEvents with queries to find specific events.
15 // A Query is a boolean expression tree that evaluates to true or false for a
16 // given trace event. Queries can be combined into a tree using boolean,
17 // arithmetic and comparison operators that refer to data of an individual trace
20 // The events are returned as trace_analyzer::TraceEvent objects.
21 // TraceEvent contains a single trace event's data, as well as a pointer to
22 // a related trace event. The related trace event is typically the matching end
23 // of a begin event or the matching begin of an end event.
25 // The following examples use this basic setup code to construct TraceAnalyzer
26 // with the json trace string retrieved from TraceLog and construct an event
27 // vector for retrieving events:
29 // TraceAnalyzer analyzer(json_events);
30 // TraceEventVector events;
32 // EXAMPLE 1: Find events named "my_event".
34 // analyzer.FindEvents(Query(EVENT_NAME) == "my_event", &events);
36 // EXAMPLE 2: Find begin events named "my_event" with duration > 1 second.
38 // Query q = (Query(EVENT_NAME) == Query::String("my_event") &&
39 // Query(EVENT_PHASE) == Query::Phase(TRACE_EVENT_PHASE_BEGIN) &&
40 // Query(EVENT_DURATION) > Query::Double(1000000.0));
41 // analyzer.FindEvents(q, &events);
43 // EXAMPLE 3: Associating event pairs across threads.
45 // If the test needs to analyze something that starts and ends on different
46 // threads, the test needs to use INSTANT events. The typical procedure is to
47 // specify the same unique ID as a TRACE_EVENT argument on both the start and
48 // finish INSTANT events. Then use the following procedure to associate those
51 // Step 1: instrument code with custom begin/end trace events.
52 // [Thread 1 tracing code]
53 // TRACE_EVENT_INSTANT1("test_latency", "timing1_begin", "id", 3);
54 // [Thread 2 tracing code]
55 // TRACE_EVENT_INSTANT1("test_latency", "timing1_end", "id", 3);
57 // Step 2: associate these custom begin/end pairs.
58 // Query begin(Query(EVENT_NAME) == Query::String("timing1_begin"));
59 // Query end(Query(EVENT_NAME) == Query::String("timing1_end"));
60 // Query match(Query(EVENT_ARG, "id") == Query(OTHER_ARG, "id"));
61 // analyzer.AssociateEvents(begin, end, match);
63 // Step 3: search for "timing1_begin" events with existing other event.
64 // Query q = (Query(EVENT_NAME) == Query::String("timing1_begin") &&
65 // Query(EVENT_HAS_OTHER));
66 // analyzer.FindEvents(q, &events);
68 // Step 4: analyze events, such as checking durations.
69 // for (size_t i = 0; i < events.size(); ++i) {
71 // EXPECT_TRUE(events[i].GetAbsTimeToOtherEvent(&duration));
72 // EXPECT_LT(duration, 1000000.0/60.0); // expect less than 1/60 second.
76 #ifndef BASE_TEST_TRACE_EVENT_ANALYZER_H_
77 #define BASE_TEST_TRACE_EVENT_ANALYZER_H_
81 #include "base/debug/trace_event.h"
82 #include "base/memory/ref_counted.h"
88 namespace trace_analyzer
{
91 // trace_analyzer::TraceEvent is a more convenient form of the
92 // base::debug::TraceEvent class to make tracing-based tests easier to write.
94 // ProcessThreadID contains a Process ID and Thread ID.
95 struct ProcessThreadID
{
96 ProcessThreadID() : process_id(0), thread_id(0) {}
97 ProcessThreadID(int process_id
, int thread_id
)
98 : process_id(process_id
), thread_id(thread_id
) {}
99 bool operator< (const ProcessThreadID
& rhs
) const {
100 if (process_id
!= rhs
.process_id
)
101 return process_id
< rhs
.process_id
;
102 return thread_id
< rhs
.thread_id
;
111 bool SetFromJSON(const base::Value
* event_value
) WARN_UNUSED_RESULT
;
113 bool operator< (const TraceEvent
& rhs
) const {
114 return timestamp
< rhs
.timestamp
;
117 bool has_other_event() const { return other_event
; }
119 // Returns absolute duration in microseconds between this event and other
120 // event. Must have already verified that other_event exists by
121 // Query(EVENT_HAS_OTHER) or by calling has_other_event().
122 double GetAbsTimeToOtherEvent() const;
124 // Return the argument value if it exists and it is a string.
125 bool GetArgAsString(const std::string
& name
, std::string
* arg
) const;
126 // Return the argument value if it exists and it is a number.
127 bool GetArgAsNumber(const std::string
& name
, double* arg
) const;
129 // Check if argument exists and is string.
130 bool HasStringArg(const std::string
& name
) const;
131 // Check if argument exists and is number (double, int or bool).
132 bool HasNumberArg(const std::string
& name
) const;
134 // Get known existing arguments as specific types.
135 // Useful when you have already queried the argument with
136 // Query(HAS_NUMBER_ARG) or Query(HAS_STRING_ARG).
137 std::string
GetKnownArgAsString(const std::string
& name
) const;
138 double GetKnownArgAsDouble(const std::string
& name
) const;
139 int GetKnownArgAsInt(const std::string
& name
) const;
140 bool GetKnownArgAsBool(const std::string
& name
) const;
142 // Process ID and Thread ID.
143 ProcessThreadID thread
;
145 // Time since epoch in microseconds.
146 // Stored as double to match its JSON representation.
153 std::string category
;
159 // All numbers and bool values from TraceEvent args are cast to double.
160 // bool becomes 1.0 (true) or 0.0 (false).
161 std::map
<std::string
, double> arg_numbers
;
163 std::map
<std::string
, std::string
> arg_strings
;
165 // The other event associated with this event (or NULL).
166 const TraceEvent
* other_event
;
169 typedef std::vector
<const TraceEvent
*> TraceEventVector
;
173 Query(const Query
& query
);
177 ////////////////////////////////////////////////////////////////
178 // Query literal values
180 // Compare with the given string.
181 static Query
String(const std::string
& str
);
183 // Compare with the given number.
184 static Query
Double(double num
);
185 static Query
Int(int32 num
);
186 static Query
Uint(uint32 num
);
188 // Compare with the given bool.
189 static Query
Bool(bool boolean
);
191 // Compare with the given phase.
192 static Query
Phase(char phase
);
194 // Compare with the given string pattern. Only works with == and != operators.
195 // Example: Query(EVENT_NAME) == Query::Pattern("MyEvent*")
196 static Query
Pattern(const std::string
& pattern
);
198 ////////////////////////////////////////////////////////////////
199 // Query event members
201 static Query
EventPid() { return Query(EVENT_PID
); }
203 static Query
EventTid() { return Query(EVENT_TID
); }
205 // Return the timestamp of the event in microseconds since epoch.
206 static Query
EventTime() { return Query(EVENT_TIME
); }
208 // Return the absolute time between event and other event in microseconds.
209 // Only works if Query::EventHasOther() == true.
210 static Query
EventDuration() { return Query(EVENT_DURATION
); }
212 // Return the duration of a COMPLETE event.
213 static Query
EventCompleteDuration() {
214 return Query(EVENT_COMPLETE_DURATION
);
217 static Query
EventPhase() { return Query(EVENT_PHASE
); }
219 static Query
EventCategory() { return Query(EVENT_CATEGORY
); }
221 static Query
EventName() { return Query(EVENT_NAME
); }
223 static Query
EventId() { return Query(EVENT_ID
); }
225 static Query
EventPidIs(int process_id
) {
226 return Query(EVENT_PID
) == Query::Int(process_id
);
229 static Query
EventTidIs(int thread_id
) {
230 return Query(EVENT_TID
) == Query::Int(thread_id
);
233 static Query
EventThreadIs(const TraceEvent::ProcessThreadID
& thread
) {
234 return EventPidIs(thread
.process_id
) && EventTidIs(thread
.thread_id
);
237 static Query
EventTimeIs(double timestamp
) {
238 return Query(EVENT_TIME
) == Query::Double(timestamp
);
241 static Query
EventDurationIs(double duration
) {
242 return Query(EVENT_DURATION
) == Query::Double(duration
);
245 static Query
EventPhaseIs(char phase
) {
246 return Query(EVENT_PHASE
) == Query::Phase(phase
);
249 static Query
EventCategoryIs(const std::string
& category
) {
250 return Query(EVENT_CATEGORY
) == Query::String(category
);
253 static Query
EventNameIs(const std::string
& name
) {
254 return Query(EVENT_NAME
) == Query::String(name
);
257 static Query
EventIdIs(const std::string
& id
) {
258 return Query(EVENT_ID
) == Query::String(id
);
261 // Evaluates to true if arg exists and is a string.
262 static Query
EventHasStringArg(const std::string
& arg_name
) {
263 return Query(EVENT_HAS_STRING_ARG
, arg_name
);
266 // Evaluates to true if arg exists and is a number.
267 // Number arguments include types double, int and bool.
268 static Query
EventHasNumberArg(const std::string
& arg_name
) {
269 return Query(EVENT_HAS_NUMBER_ARG
, arg_name
);
272 // Evaluates to arg value (string or number).
273 static Query
EventArg(const std::string
& arg_name
) {
274 return Query(EVENT_ARG
, arg_name
);
277 // Return true if associated event exists.
278 static Query
EventHasOther() { return Query(EVENT_HAS_OTHER
); }
280 // Access the associated other_event's members:
282 static Query
OtherPid() { return Query(OTHER_PID
); }
284 static Query
OtherTid() { return Query(OTHER_TID
); }
286 static Query
OtherTime() { return Query(OTHER_TIME
); }
288 static Query
OtherPhase() { return Query(OTHER_PHASE
); }
290 static Query
OtherCategory() { return Query(OTHER_CATEGORY
); }
292 static Query
OtherName() { return Query(OTHER_NAME
); }
294 static Query
OtherId() { return Query(OTHER_ID
); }
296 static Query
OtherPidIs(int process_id
) {
297 return Query(OTHER_PID
) == Query::Int(process_id
);
300 static Query
OtherTidIs(int thread_id
) {
301 return Query(OTHER_TID
) == Query::Int(thread_id
);
304 static Query
OtherThreadIs(const TraceEvent::ProcessThreadID
& thread
) {
305 return OtherPidIs(thread
.process_id
) && OtherTidIs(thread
.thread_id
);
308 static Query
OtherTimeIs(double timestamp
) {
309 return Query(OTHER_TIME
) == Query::Double(timestamp
);
312 static Query
OtherPhaseIs(char phase
) {
313 return Query(OTHER_PHASE
) == Query::Phase(phase
);
316 static Query
OtherCategoryIs(const std::string
& category
) {
317 return Query(OTHER_CATEGORY
) == Query::String(category
);
320 static Query
OtherNameIs(const std::string
& name
) {
321 return Query(OTHER_NAME
) == Query::String(name
);
324 static Query
OtherIdIs(const std::string
& id
) {
325 return Query(OTHER_ID
) == Query::String(id
);
328 // Evaluates to true if arg exists and is a string.
329 static Query
OtherHasStringArg(const std::string
& arg_name
) {
330 return Query(OTHER_HAS_STRING_ARG
, arg_name
);
333 // Evaluates to true if arg exists and is a number.
334 // Number arguments include types double, int and bool.
335 static Query
OtherHasNumberArg(const std::string
& arg_name
) {
336 return Query(OTHER_HAS_NUMBER_ARG
, arg_name
);
339 // Evaluates to arg value (string or number).
340 static Query
OtherArg(const std::string
& arg_name
) {
341 return Query(OTHER_ARG
, arg_name
);
344 ////////////////////////////////////////////////////////////////
347 // Find BEGIN events that have a corresponding END event.
348 static Query
MatchBeginWithEnd() {
349 return (Query(EVENT_PHASE
) == Query::Phase(TRACE_EVENT_PHASE_BEGIN
)) &&
350 Query(EVENT_HAS_OTHER
);
353 // Find COMPLETE events.
354 static Query
MatchComplete() {
355 return (Query(EVENT_PHASE
) == Query::Phase(TRACE_EVENT_PHASE_COMPLETE
));
358 // Find ASYNC_BEGIN events that have a corresponding ASYNC_END event.
359 static Query
MatchAsyncBeginWithNext() {
360 return (Query(EVENT_PHASE
) ==
361 Query::Phase(TRACE_EVENT_PHASE_ASYNC_BEGIN
)) &&
362 Query(EVENT_HAS_OTHER
);
365 // Find BEGIN events of given |name| which also have associated END events.
366 static Query
MatchBeginName(const std::string
& name
) {
367 return (Query(EVENT_NAME
) == Query(name
)) && MatchBeginWithEnd();
370 // Find COMPLETE events of given |name|.
371 static Query
MatchCompleteName(const std::string
& name
) {
372 return (Query(EVENT_NAME
) == Query(name
)) && MatchComplete();
375 // Match given Process ID and Thread ID.
376 static Query
MatchThread(const TraceEvent::ProcessThreadID
& thread
) {
377 return (Query(EVENT_PID
) == Query::Int(thread
.process_id
)) &&
378 (Query(EVENT_TID
) == Query::Int(thread
.thread_id
));
381 // Match event pair that spans multiple threads.
382 static Query
MatchCrossThread() {
383 return (Query(EVENT_PID
) != Query(OTHER_PID
)) ||
384 (Query(EVENT_TID
) != Query(OTHER_TID
));
387 ////////////////////////////////////////////////////////////////
390 // Boolean operators:
391 Query
operator==(const Query
& rhs
) const;
392 Query
operator!=(const Query
& rhs
) const;
393 Query
operator< (const Query
& rhs
) const;
394 Query
operator<=(const Query
& rhs
) const;
395 Query
operator> (const Query
& rhs
) const;
396 Query
operator>=(const Query
& rhs
) const;
397 Query
operator&&(const Query
& rhs
) const;
398 Query
operator||(const Query
& rhs
) const;
399 Query
operator!() const;
401 // Arithmetic operators:
402 // Following operators are applied to double arguments:
403 Query
operator+(const Query
& rhs
) const;
404 Query
operator-(const Query
& rhs
) const;
405 Query
operator*(const Query
& rhs
) const;
406 Query
operator/(const Query
& rhs
) const;
407 Query
operator-() const;
408 // Mod operates on int64 args (doubles are casted to int64 beforehand):
409 Query
operator%(const Query
& rhs
) const;
411 // Return true if the given event matches this query tree.
412 // This is a recursive method that walks the query tree.
413 bool Evaluate(const TraceEvent
& event
) const;
416 enum TraceEventMember
{
422 EVENT_COMPLETE_DURATION
,
427 EVENT_HAS_STRING_ARG
,
428 EVENT_HAS_NUMBER_ARG
,
438 OTHER_HAS_STRING_ARG
,
439 OTHER_HAS_NUMBER_ARG
,
445 // Boolean operators:
455 // Arithmetic operators:
465 QUERY_BOOLEAN_OPERATOR
,
466 QUERY_ARITHMETIC_OPERATOR
,
472 // Compare with the given member.
473 explicit Query(TraceEventMember member
);
475 // Compare with the given member argument value.
476 Query(TraceEventMember member
, const std::string
& arg_name
);
478 // Compare with the given string.
479 explicit Query(const std::string
& str
);
481 // Compare with the given number.
482 explicit Query(double num
);
484 // Construct a boolean Query that returns (left <binary_op> right).
485 Query(const Query
& left
, const Query
& right
, Operator binary_op
);
487 // Construct a boolean Query that returns (<binary_op> left).
488 Query(const Query
& left
, Operator unary_op
);
490 // Try to compare left_ against right_ based on operator_.
491 // If either left or right does not convert to double, false is returned.
492 // Otherwise, true is returned and |result| is set to the comparison result.
493 bool CompareAsDouble(const TraceEvent
& event
, bool* result
) const;
495 // Try to compare left_ against right_ based on operator_.
496 // If either left or right does not convert to string, false is returned.
497 // Otherwise, true is returned and |result| is set to the comparison result.
498 bool CompareAsString(const TraceEvent
& event
, bool* result
) const;
500 // Attempt to convert this Query to a double. On success, true is returned
501 // and the double value is stored in |num|.
502 bool GetAsDouble(const TraceEvent
& event
, double* num
) const;
504 // Attempt to convert this Query to a string. On success, true is returned
505 // and the string value is stored in |str|.
506 bool GetAsString(const TraceEvent
& event
, std::string
* str
) const;
508 // Evaluate this Query as an arithmetic operator on left_ and right_.
509 bool EvaluateArithmeticOperator(const TraceEvent
& event
,
512 // For QUERY_EVENT_MEMBER Query: attempt to get the double value of the Query.
513 bool GetMemberValueAsDouble(const TraceEvent
& event
, double* num
) const;
515 // For QUERY_EVENT_MEMBER Query: attempt to get the string value of the Query.
516 bool GetMemberValueAsString(const TraceEvent
& event
, std::string
* num
) const;
518 // Does this Query represent a value?
519 bool is_value() const { return type_
!= QUERY_BOOLEAN_OPERATOR
; }
521 bool is_unary_operator() const {
522 return operator_
== OP_NOT
|| operator_
== OP_NEGATE
;
525 bool is_comparison_operator() const {
526 return operator_
!= OP_INVALID
&& operator_
< OP_AND
;
529 const Query
& left() const;
530 const Query
& right() const;
534 scoped_refptr
<QueryNode
> left_
;
535 scoped_refptr
<QueryNode
> right_
;
536 TraceEventMember member_
;
542 // Implementation detail:
543 // QueryNode allows Query to store a ref-counted query tree.
544 class QueryNode
: public base::RefCounted
<QueryNode
> {
546 explicit QueryNode(const Query
& query
);
547 const Query
& query() const { return query_
; }
550 friend class base::RefCounted
<QueryNode
>;
556 // TraceAnalyzer helps tests search for trace events.
557 class TraceAnalyzer
{
561 // Use trace events from JSON string generated by tracing API.
562 // Returns non-NULL if the JSON is successfully parsed.
563 static TraceAnalyzer
* Create(const std::string
& json_events
)
566 // Associate BEGIN and END events with each other. This allows Query(OTHER_*)
567 // to access the associated event and enables Query(EVENT_DURATION).
568 // An end event will match the most recent begin event with the same name,
569 // category, process ID and thread ID. This matches what is shown in
570 // about:tracing. After association, the BEGIN event will point to the
571 // matching END event, but the END event will not point to the BEGIN event.
572 void AssociateBeginEndEvents();
574 // Associate ASYNC_BEGIN, ASYNC_STEP and ASYNC_END events with each other.
575 // An ASYNC_END event will match the most recent ASYNC_BEGIN or ASYNC_STEP
576 // event with the same name, category, and ID. This creates a singly linked
577 // list of ASYNC_BEGIN->ASYNC_STEP...->ASYNC_END.
578 void AssociateAsyncBeginEndEvents();
580 // AssociateEvents can be used to customize event associations by setting the
581 // other_event member of TraceEvent. This should be used to associate two
584 // The assumptions are:
585 // - |first| events occur before |second| events.
586 // - the closest matching |second| event is the correct match.
588 // |first| - Eligible |first| events match this query.
589 // |second| - Eligible |second| events match this query.
590 // |match| - This query is run on the |first| event. The OTHER_* EventMember
591 // queries will point to an eligible |second| event. The query
592 // should evaluate to true if the |first|/|second| pair is a match.
594 // When a match is found, the pair will be associated by having the first
595 // event's other_event member point to the other. AssociateEvents does not
596 // clear previous associations, so it is possible to associate multiple pairs
597 // of events by calling AssociateEvents more than once with different queries.
599 // NOTE: AssociateEvents will overwrite existing other_event associations if
600 // the queries pass for events that already had a previous association.
602 // After calling any Find* method, it is not allowed to call AssociateEvents
604 void AssociateEvents(const Query
& first
,
608 // For each event, copy its arguments to the other_event argument map. If
609 // argument name already exists, it will not be overwritten.
610 void MergeAssociatedEventArgs();
612 // Find all events that match query and replace output vector.
613 size_t FindEvents(const Query
& query
, TraceEventVector
* output
);
615 // Find first event that matches query or NULL if not found.
616 const TraceEvent
* FindFirstOf(const Query
& query
);
618 // Find last event that matches query or NULL if not found.
619 const TraceEvent
* FindLastOf(const Query
& query
);
621 const std::string
& GetThreadName(const TraceEvent::ProcessThreadID
& thread
);
626 bool SetEvents(const std::string
& json_events
) WARN_UNUSED_RESULT
;
628 // Read metadata (thread names, etc) from events.
629 void ParseMetadata();
631 std::map
<TraceEvent::ProcessThreadID
, std::string
> thread_names_
;
632 std::vector
<TraceEvent
> raw_events_
;
633 bool allow_assocation_changes_
;
635 DISALLOW_COPY_AND_ASSIGN(TraceAnalyzer
);
638 // Utility functions for TraceEventVector.
644 double standard_deviation_us
;
647 struct RateStatsOptions
{
648 RateStatsOptions() : trim_min(0u), trim_max(0u) {}
649 // After the times between events are sorted, the number of specified elements
650 // will be trimmed before calculating the RateStats. This is useful in cases
651 // where extreme outliers are tolerable and should not skew the overall
653 size_t trim_min
; // Trim this many minimum times.
654 size_t trim_max
; // Trim this many maximum times.
657 // Calculate min/max/mean and standard deviation from the times between
659 bool GetRateStats(const TraceEventVector
& events
,
661 const RateStatsOptions
* options
);
663 // Starting from |position|, find the first event that matches |query|.
664 // Returns true if found, false otherwise.
665 bool FindFirstOf(const TraceEventVector
& events
,
668 size_t* return_index
);
670 // Starting from |position|, find the last event that matches |query|.
671 // Returns true if found, false otherwise.
672 bool FindLastOf(const TraceEventVector
& events
,
675 size_t* return_index
);
677 // Find the closest events to |position| in time that match |query|.
678 // return_second_closest may be NULL. Closeness is determined by comparing
679 // with the event timestamp.
680 // Returns true if found, false otherwise. If both return parameters are
681 // requested, both must be found for a successful result.
682 bool FindClosest(const TraceEventVector
& events
,
685 size_t* return_closest
,
686 size_t* return_second_closest
);
688 // Count matches, inclusive of |begin_position|, exclusive of |end_position|.
689 size_t CountMatches(const TraceEventVector
& events
,
691 size_t begin_position
,
692 size_t end_position
);
694 // Count all matches.
695 static inline size_t CountMatches(const TraceEventVector
& events
,
696 const Query
& query
) {
697 return CountMatches(events
, query
, 0u, events
.size());
700 } // namespace trace_analyzer
702 #endif // BASE_TEST_TRACE_EVENT_ANALYZER_H_