Update readme with more guidelines for writing queries

Covers a few new things and expands on some existing notes
in further detail.

Co-authored-by: Sean Dague <sean@dague.net>
Change-Id: I9383783bf67411cebfaef6b82b5e08b3afe70afe
This commit is contained in:
Matt Riedemann 2014-06-18 08:07:50 -07:00
parent 931b4a888b
commit 24af0e0c1c

View File

@ -30,11 +30,35 @@ at the top of the elastic-recheck code base. The format of these files
is ######.yaml (where ###### is the launchpad bug number), the yaml should have
a ``query`` keyword which is the query text for elastic search.
Guidelines for good queries
Guidelines for good queries:
- Queries should get as close as possible to fingerprinting the root cause. A
filename query is typically better than a console one, as that's matching a
deep failure versus a surface symptom.
- Queries should get as close as possible to fingerprinting the root cause
- Queries should not return any hits for successful jobs, this is a
sign the query isn't specific enough
sign the query isn't specific enough. A rule of thumb is > 10% success hits
probably means this isn't good enough.
- If it's impossible to build a query to target a bug, consider patching the
upstream program to be explicit when it fails in a particular way.
- Use the 'tags' field rather than the 'filename' field for filtering. This is
primarily because of grenade jobs where the same log file shows up in the
'old' and 'new' side of the grenade job. For example, tags:"screen-n-cpu.txt"
will query in logs/old/screen-n-cpu.txt and logs/new/screen-n-cpu.txt. The
tags:"console" filter is also used to query in console.html as well as
tempest and devstack logs.
- Avoid the use of wildcards in queries since they can put an undue burden on
the query engine. A common case where wildcards would be useful are in
querying against a specific set of build_name fields, e.g. gate-nova-python26
and gate-nova-python27. Rather than use build_name:gate-nova-python*, list
the jobs with an OR, e.g.:
::
(build_name:"gate-nova-python26" OR build_name:"gate-nova-python27")
In order to support rapidly added queries, it's considered socially
acceptable to +A changes that only add 1 new bug query, and to even