user_metrics.h revision 868fa2fe829687343ffae624259930155e16dbd8 
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.
4
5#ifndef CONTENT_PUBLIC_BROWSER_USER_METRICS_H_
6#define CONTENT_PUBLIC_BROWSER_USER_METRICS_H_
7
8#include <string>
9
10#include "base/callback.h"
11#include "content/common/content_export.h"
12
13namespace content {
14
15// This module provides some helper functions for logging actions tracked by
16// the user metrics system.
17
18
19// UserMetricsAction exist purely to standardize on the paramters passed to
20// UserMetrics. That way, our toolset can scan the sourcecode reliable for
21// constructors and extract the associated string constants
22struct UserMetricsAction {
23  const char* str_;
24  explicit UserMetricsAction(const char* str) : str_(str) {}
25};
26
27// Record that the user performed an action.
28// "Action" here means a user-generated event:
29//   good: "Reload", "CloseTab", and "IMEInvoked"
30//   not good: "SSLDialogShown", "PageLoaded", "DiskFull"
31// We use this to gather anonymized information about how users are
32// interacting with the browser.
33// WARNING: In calls to this function, UserMetricsAction and a
34// string literal parameter must be on the same line, e.g.
35//   content::RecordAction(
36//       content::UserMetricsAction("my extremely long action name"));
37// because otherwise our processing scripts won't pick up on new actions.
38//
39// Once a new recorded action is added, run
40// tools/metrics/actions/extract_actions.py --hash
41// to generate a new mapping of [action hashes -> metric names] and send it
42// out for review to be updated.
43//
44// For more complicated situations (like when there are many different
45// possible actions), see RecordComputedAction.
46CONTENT_EXPORT void RecordAction(const UserMetricsAction& action);
47
48// This function has identical input and behavior to RecordAction, but is
49// not automatically found by the action-processing scripts.  It can be used
50// when it's a pain to enumerate all possible actions, but if you use this
51// you need to also update the rules for extracting known actions in
52// chrome/tools/extract_actions.py.
53CONTENT_EXPORT void RecordComputedAction(const std::string& action);
54
55// Called with the action string.
56typedef base::Callback<void(const std::string&)> ActionCallback;
57
58// Add/remove action callbacks (see above).
59CONTENT_EXPORT void AddActionCallback(const ActionCallback& callback);
60CONTENT_EXPORT void RemoveActionCallback(const ActionCallback& callback);
61
62}  // namespace content
63
64#endif  // CONTENT_PUBLIC_BROWSER_USER_METRICS_H_
65