145779228f8c9e40851cfd23f727e2bd8ffdd4714Alex Vakulenko// Copyright 2014 The Chromium Authors. All rights reserved. 245779228f8c9e40851cfd23f727e2bd8ffdd4714Alex Vakulenko// Use of this source code is governed by a BSD-style license that can be 345779228f8c9e40851cfd23f727e2bd8ffdd4714Alex Vakulenko// found in the LICENSE file. 445779228f8c9e40851cfd23f727e2bd8ffdd4714Alex Vakulenko 545779228f8c9e40851cfd23f727e2bd8ffdd4714Alex Vakulenko#ifndef BASE_METRICS_USER_METRICS_H_ 645779228f8c9e40851cfd23f727e2bd8ffdd4714Alex Vakulenko#define BASE_METRICS_USER_METRICS_H_ 745779228f8c9e40851cfd23f727e2bd8ffdd4714Alex Vakulenko 845779228f8c9e40851cfd23f727e2bd8ffdd4714Alex Vakulenko#include <string> 945779228f8c9e40851cfd23f727e2bd8ffdd4714Alex Vakulenko 1045779228f8c9e40851cfd23f727e2bd8ffdd4714Alex Vakulenko#include "base/base_export.h" 1145779228f8c9e40851cfd23f727e2bd8ffdd4714Alex Vakulenko#include "base/callback.h" 1245779228f8c9e40851cfd23f727e2bd8ffdd4714Alex Vakulenko#include "base/metrics/user_metrics_action.h" 1394ffa55491333f3dcc701befd0d2652922916d99Luis Hector Chavez#include "base/single_thread_task_runner.h" 1445779228f8c9e40851cfd23f727e2bd8ffdd4714Alex Vakulenko 1545779228f8c9e40851cfd23f727e2bd8ffdd4714Alex Vakulenkonamespace base { 1645779228f8c9e40851cfd23f727e2bd8ffdd4714Alex Vakulenko 1745779228f8c9e40851cfd23f727e2bd8ffdd4714Alex Vakulenko// This module provides some helper functions for logging actions tracked by 1845779228f8c9e40851cfd23f727e2bd8ffdd4714Alex Vakulenko// the user metrics system. 1945779228f8c9e40851cfd23f727e2bd8ffdd4714Alex Vakulenko 203a83cddbf6d8fe9c9d70d01e008ff8e86a823cb6Jay Civelli// For best practices on deciding when to emit a user action, see 213a83cddbf6d8fe9c9d70d01e008ff8e86a823cb6Jay Civelli// https://chromium.googlesource.com/chromium/src.git/+/HEAD/tools/metrics/actions/README.md 223a83cddbf6d8fe9c9d70d01e008ff8e86a823cb6Jay Civelli 2345779228f8c9e40851cfd23f727e2bd8ffdd4714Alex Vakulenko// Record that the user performed an action. 2494ffa55491333f3dcc701befd0d2652922916d99Luis Hector Chavez// This function must be called after the task runner has been set with 2594ffa55491333f3dcc701befd0d2652922916d99Luis Hector Chavez// SetRecordActionTaskRunner(). 2645779228f8c9e40851cfd23f727e2bd8ffdd4714Alex Vakulenko// 2745779228f8c9e40851cfd23f727e2bd8ffdd4714Alex Vakulenko// "Action" here means a user-generated event: 2845779228f8c9e40851cfd23f727e2bd8ffdd4714Alex Vakulenko// good: "Reload", "CloseTab", and "IMEInvoked" 2945779228f8c9e40851cfd23f727e2bd8ffdd4714Alex Vakulenko// not good: "SSLDialogShown", "PageLoaded", "DiskFull" 3045779228f8c9e40851cfd23f727e2bd8ffdd4714Alex Vakulenko// We use this to gather anonymized information about how users are 3145779228f8c9e40851cfd23f727e2bd8ffdd4714Alex Vakulenko// interacting with the browser. 320c4f26a46430b8c503c65f5cae1d2b6876d53e30Luis Hector Chavez// WARNING: In calls to this function, UserMetricsAction should be followed by a 330c4f26a46430b8c503c65f5cae1d2b6876d53e30Luis Hector Chavez// string literal parameter and not a variable e.g. 340c4f26a46430b8c503c65f5cae1d2b6876d53e30Luis Hector Chavez// RecordAction(UserMetricsAction("my action name")); 3545779228f8c9e40851cfd23f727e2bd8ffdd4714Alex Vakulenko// This ensures that our processing scripts can associate this action's hash 3645779228f8c9e40851cfd23f727e2bd8ffdd4714Alex Vakulenko// with its metric name. Therefore, it will be possible to retrieve the metric 3745779228f8c9e40851cfd23f727e2bd8ffdd4714Alex Vakulenko// name from the hash later on. 3845779228f8c9e40851cfd23f727e2bd8ffdd4714Alex Vakulenko// 3945779228f8c9e40851cfd23f727e2bd8ffdd4714Alex Vakulenko// Once a new recorded action is added, run 4045779228f8c9e40851cfd23f727e2bd8ffdd4714Alex Vakulenko// tools/metrics/actions/extract_actions.py 4145779228f8c9e40851cfd23f727e2bd8ffdd4714Alex Vakulenko// to add the metric to actions.xml, then update the <owner>s and <description> 4245779228f8c9e40851cfd23f727e2bd8ffdd4714Alex Vakulenko// sections. Make sure to include the actions.xml file when you upload your code 4345779228f8c9e40851cfd23f727e2bd8ffdd4714Alex Vakulenko// for review! 4445779228f8c9e40851cfd23f727e2bd8ffdd4714Alex Vakulenko// 4545779228f8c9e40851cfd23f727e2bd8ffdd4714Alex Vakulenko// For more complicated situations (like when there are many different 4694ffa55491333f3dcc701befd0d2652922916d99Luis Hector Chavez// possible actions), see RecordComputedAction(). 4745779228f8c9e40851cfd23f727e2bd8ffdd4714Alex VakulenkoBASE_EXPORT void RecordAction(const UserMetricsAction& action); 4845779228f8c9e40851cfd23f727e2bd8ffdd4714Alex Vakulenko 4994ffa55491333f3dcc701befd0d2652922916d99Luis Hector Chavez// This function has identical input and behavior to RecordAction(), but is 5045779228f8c9e40851cfd23f727e2bd8ffdd4714Alex Vakulenko// not automatically found by the action-processing scripts. It can be used 5145779228f8c9e40851cfd23f727e2bd8ffdd4714Alex Vakulenko// when it's a pain to enumerate all possible actions, but if you use this 5245779228f8c9e40851cfd23f727e2bd8ffdd4714Alex Vakulenko// you need to also update the rules for extracting known actions in 5345779228f8c9e40851cfd23f727e2bd8ffdd4714Alex Vakulenko// tools/metrics/actions/extract_actions.py. 5494ffa55491333f3dcc701befd0d2652922916d99Luis Hector Chavez// This function must be called after the task runner has been set with 5594ffa55491333f3dcc701befd0d2652922916d99Luis Hector Chavez// SetRecordActionTaskRunner(). 5645779228f8c9e40851cfd23f727e2bd8ffdd4714Alex VakulenkoBASE_EXPORT void RecordComputedAction(const std::string& action); 5745779228f8c9e40851cfd23f727e2bd8ffdd4714Alex Vakulenko 5845779228f8c9e40851cfd23f727e2bd8ffdd4714Alex Vakulenko// Called with the action string. 5994ffa55491333f3dcc701befd0d2652922916d99Luis Hector Chaveztypedef Callback<void(const std::string&)> ActionCallback; 6045779228f8c9e40851cfd23f727e2bd8ffdd4714Alex Vakulenko 6145779228f8c9e40851cfd23f727e2bd8ffdd4714Alex Vakulenko// Add/remove action callbacks (see above). 6294ffa55491333f3dcc701befd0d2652922916d99Luis Hector Chavez// These functions must be called after the task runner has been set with 6394ffa55491333f3dcc701befd0d2652922916d99Luis Hector Chavez// SetRecordActionTaskRunner(). 6445779228f8c9e40851cfd23f727e2bd8ffdd4714Alex VakulenkoBASE_EXPORT void AddActionCallback(const ActionCallback& callback); 6545779228f8c9e40851cfd23f727e2bd8ffdd4714Alex VakulenkoBASE_EXPORT void RemoveActionCallback(const ActionCallback& callback); 6645779228f8c9e40851cfd23f727e2bd8ffdd4714Alex Vakulenko 6794ffa55491333f3dcc701befd0d2652922916d99Luis Hector Chavez// Set the task runner on which to record actions. 6894ffa55491333f3dcc701befd0d2652922916d99Luis Hector ChavezBASE_EXPORT void SetRecordActionTaskRunner( 6994ffa55491333f3dcc701befd0d2652922916d99Luis Hector Chavez scoped_refptr<SingleThreadTaskRunner> task_runner); 7094ffa55491333f3dcc701befd0d2652922916d99Luis Hector Chavez 7145779228f8c9e40851cfd23f727e2bd8ffdd4714Alex Vakulenko} // namespace base 7245779228f8c9e40851cfd23f727e2bd8ffdd4714Alex Vakulenko 7345779228f8c9e40851cfd23f727e2bd8ffdd4714Alex Vakulenko#endif // BASE_METRICS_USER_METRICS_H_ 74