1 # Copyright 2013 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 """Scans the Chromium source for histograms that are absent from histograms.xml.
7 This is a heuristic scan, so a clean run of this script does not guarantee that
8 all histograms in the Chromium source are properly mapped. Notably, field
9 trials are entirely ignored by this script.
14 import extract_histograms
23 ADJACENT_C_STRING_REGEX = re.compile(r"""
24 (" # Opening quotation mark
25 [^"]*) # Literal string contents
26 " # Closing quotation mark
27 \s* # Any number of spaces
28 " # Another opening quotation mark
30 CONSTANT_REGEX = re.compile(r"""
31 (\w*::)? # Optional namespace
32 k[A-Z] # Match a constant identifier: 'k' followed by an uppercase letter
33 \w* # Match the rest of the constant identifier
34 $ # Make sure there's only the identifier, nothing else
36 HISTOGRAM_REGEX = re.compile(r"""
37 UMA_HISTOGRAM # Match the shared prefix for standard UMA histogram macros
38 \w* # Match the rest of the macro name, e.g. '_ENUMERATION'
39 \( # Match the opening parenthesis for the macro
40 \s* # Match any whitespace -- especially, any newlines
41 ([^,)]*) # Capture the first parameter to the macro
42 [,)] # Match the comma/paren that delineates the first parameter
46 class DirectoryNotFoundException(Exception):
47 """Base class to distinguish locally defined exceptions from standard ones."""
48 def __init__(self, msg):
55 def findDefaultRoot():
56 """Find the root of the chromium repo, in case the script is run from the
60 string: path to the src dir of the repo.
63 DirectoryNotFoundException if the target directory cannot be found.
67 head, tail = os.path.split(path)
73 raise DirectoryNotFoundException('Could not find src/ dir')
76 def collapseAdjacentCStrings(string):
77 """Collapses any adjacent C strings into a single string.
79 Useful to re-combine strings that were split across multiple lines to satisfy
80 the 80-col restriction.
83 string: The string to recombine, e.g. '"Foo"\n "bar"'
86 The collapsed string, e.g. "Foobar" for an input of '"Foo"\n "bar"'
89 collapsed = ADJACENT_C_STRING_REGEX.sub(r'\1', string, count=1)
90 if collapsed == string:
96 def logNonLiteralHistogram(filename, histogram):
97 """Logs a statement warning about a non-literal histogram name found in the
100 Filters out known acceptable exceptions.
103 filename: The filename for the file containing the histogram, e.g.
104 'chrome/browser/memory_details.cc'
105 histogram: The expression that evaluates to the name of the histogram, e.g.
106 '"FakeHistogram" + variant'
111 # Ignore histogram macros, which typically contain backslashes so that they
112 # can be formatted across lines.
113 if '\\' in histogram:
116 # Ignore histogram names that have been pulled out into C++ constants.
117 if CONSTANT_REGEX.match(histogram):
120 # TODO(isherman): This is still a little noisy... needs further filtering to
122 logging.warning('%s contains non-literal histogram name <%s>', filename,
126 def readChromiumHistograms():
127 """Searches the Chromium source for all histogram names.
129 Also prints warnings for any invocations of the UMA_HISTOGRAM_* macros with
130 names that might vary during a single run of the app.
133 A set cotaining any found literal histogram names.
135 logging.info('Scanning Chromium source for histograms...')
137 # Use git grep to find all invocations of the UMA_HISTOGRAM_* macros.
139 # 'path/to/foo.cc:420: UMA_HISTOGRAM_COUNTS_100("FooGroup.FooName",'
140 # 'path/to/bar.cc:632: UMA_HISTOGRAM_ENUMERATION('
141 locations = commands.getoutput('git gs UMA_HISTOGRAM').split('\n')
142 filenames = set([location.split(':')[0] for location in locations])
145 for filename in filenames:
147 with open(filename, 'r') as f:
150 matches = set(HISTOGRAM_REGEX.findall(contents))
151 for histogram in matches:
152 histogram = collapseAdjacentCStrings(histogram)
154 # Must begin and end with a quotation mark.
155 if histogram[0] != '"' or histogram[-1] != '"':
156 logNonLiteralHistogram(filename, histogram)
159 # Must not include any quotation marks other than at the beginning or end.
160 histogram_stripped = histogram.strip('"')
161 if '"' in histogram_stripped:
162 logNonLiteralHistogram(filename, histogram)
165 histograms.add(histogram_stripped)
170 def readXmlHistograms(histograms_file_location):
171 """Parses all histogram names from histograms.xml.
174 A set cotaining the parsed histogram names.
176 logging.info('Reading histograms from %s...' % histograms_file_location)
177 histograms = extract_histograms.ExtractHistograms(histograms_file_location)
178 return set(extract_histograms.ExtractNames(histograms))
181 def hashHistogramName(name):
182 """Computes the hash of a histogram name.
185 name: The string to hash (a histogram name).
188 Histogram hash as a string representing a hex number (with leading 0x).
190 return '0x' + hashlib.md5(name).hexdigest()[:16]
194 # Find default paths.
195 default_root = findDefaultRoot()
196 default_histograms_path = os.path.join(
197 default_root, 'tools/metrics/histograms/histograms.xml')
198 default_extra_histograms_path = os.path.join(
199 default_root, 'tools/histograms/histograms.xml')
201 # Parse command line options
202 parser = optparse.OptionParser()
204 '--root-directory', dest='root_directory', default=default_root,
205 help='scan within DIRECTORY for histograms [optional, defaults to "%s"]' %
209 '--histograms-file', dest='histograms_file_location',
210 default=default_histograms_path,
211 help='read histogram definitions from FILE (relative to --root-directory) '
212 '[optional, defaults to "%s"]' % default_histograms_path,
215 '--exrta_histograms-file', dest='extra_histograms_file_location',
216 default=default_extra_histograms_path,
217 help='read additional histogram definitions from FILE (relative to '
218 '--root-directory) [optional, defaults to "%s"]' %
219 default_extra_histograms_path,
222 (options, args) = parser.parse_args()
227 logging.basicConfig(format='%(levelname)s: %(message)s', level=logging.INFO)
230 os.chdir(options.root_directory)
231 except EnvironmentError as e:
232 logging.error("Could not change to root directory: %s", e)
234 chromium_histograms = readChromiumHistograms()
235 xml_histograms = readXmlHistograms(options.histograms_file_location)
236 unmapped_histograms = chromium_histograms - xml_histograms
238 if os.path.isfile(options.extra_histograms_file_location):
239 xml_histograms2 = readXmlHistograms(options.extra_histograms_file_location)
240 unmapped_histograms -= xml_histograms2
242 logging.warning('No such file: %s', options.extra_histograms_file_location)
244 if len(unmapped_histograms):
247 logging.info('Histograms in Chromium but not in XML files:')
248 logging.info('-------------------------------------------------')
249 for histogram in sorted(unmapped_histograms):
250 logging.info(' %s - %s', histogram, hashHistogramName(histogram))
252 logging.info('Success! No unmapped histograms found.')
255 if __name__ == '__main__':