src/docs/user/userguide/multimeter.diviner

   1 @title Multimeter User Guide
   2 @group userguide
   3
   4 Using Multimeter, a sampling profiler.
   5
   6 Overview
   7 ========
   8
   9 IMPORTANT: This document describes a prototype application.
  10
  11 Multimeter is a sampling profiler that can give you coarse information about
  12 Phabricator resource usage. In particular, it can help quickly identify sources
  13 of load, like bots or scripts which are making a very large number of requests.
  14
  15 Configuring and Using Multimeter
  16 ================================
  17
  18 To access Multimeter, go to {nav Applications > Multimeter}.
  19
  20 By default, Multimeter samples 0.1% of pages. This should be a reasonable rate
  21 for most installs, but you can increase or decrease the rate by adjusting
  22 `debug.sample-rate`. Increasing the rate (by setting the value to a lower
  23 number, like 100, to sample 1% of pages) will increase the granularity of the
  24 data, at a small performance cost.
  25
  26 Using Multimeter
  27 ================
  28
  29 Multimeter shows you what Phabricator has spent time doing recently. By
  30 looking at the samples it collects, you can identify major sources of load
  31 or resource use, whether they are specific users, pages, subprocesses, or
  32 other types of activity.
  33
  34 By identifying and understanding unexpected load, you can adjust usage patterns
  35 or configuration to make better use of resources (for example, rewrite bots
  36 that are making too many calls), or report specific, actionable issues to the
  37 upstream for resolution.
  38
  39 The main screen of Multimeter shows you everything Phabricator has spent
  40 resources on recently, broken down by action type. Categories are folded up
  41 by default, with "(All)" labels.
  42
  43 To filter by a dimension, click the link for it. For example, from the main
  44 page, you can click "Web Request" to filter by only web requests. To expand a
  45 grouped dimension, click the "(All)" link.
  46
  47 For example, suppose we suspect that someone is running a bot that is making
  48 a lot of requests and consuming a lot of resources. We can get a better idea
  49 about this by filtering the results like this:
  50
  51   - Click {nav Web Request}. This will show only web requests.
  52   - Click {nav (All)} under "Viewer". This will expand events by viewer.
  53
  54 Recent resource costs for web requests are now shown, grouped and sorted by
  55 user. The usernames in the "Viewer" column show who is using resources, in
  56 order from greatest use to least use (only administrators can see usernames).
  57
  58 The "Avg" column shows the average cost per event, while the "Cost" column
  59 shows the total cost.
  60
  61 If the top few users account for similar costs and are normal, active users,
  62 there may be nothing amiss and your problem might lie elsewhere. If a user like
  63 `slowbot` is in the top few users and has way higher usage than anyone else,
  64 there might be a script running under that account consuming a disproportionate
  65 amount of resources.
  66
  67 Assuming you find a user with unusual usage, you could dig into their usage
  68 like this:
  69
  70   - Click their name (like {nav slowbot}) to filter to just their requests.
  71   - Click {nav (All)} under "Label". This expands by request detail.
  72
  73 This will show exactly what they spent those resources doing, and can help
  74 identify if they're making a lot of API calls or scraping the site or whatever
  75 else.
  76
  77 This is just an example of a specific kind of problem that Multimeter could
  78 help resolve. In general, exploring Multimeter data by filtering and expanding
  79 resource uses can help you understand how resources are used and identify
  80 unexpected uses of resources. For example:
  81
  82   - Identify a problem with load balancing by filtering on {nav Web Request}
  83     and expanding on {nav Host}. If hosts aren't roughly even, DNS or a load
  84     balancer are misconfigured.
  85   - Identify which pages cost the most by filtering on {nav Web Request}
  86     and expanding on {nav Label}.
  87   - Find outlier pages by filtering on {nav Web Request} and expanding on
  88     {nav ID}.
  89   - Find where subprocess are invoked from by filtering on {nav Subprocesses},
  90     then expanding on {nav Context}.
  91
  92
  93 Next Steps
  94 ==========
  95
  96 Continue by:
  97
  98   - understanding and reporting performance issues with
  99     @{article:Troubleshooting Performance Problems}.