Red Hat Training
A Red Hat training course is available for Red Hat JBoss Operations Network
2. Dynamic Searches for Resources and Groups
The inventory area has a dynamic search to look for resources and groups.
The dynamic search is an additional tool that can help manage your JBoss ON resources. Dynamic searches in JBoss ON can be saved to provide fast and reproducible snapshots of your JBoss ON deployment that match criteria that are relevant to your infrastructure, a kind of quick report.
A dynamic search checks both resources and groups (recursively into group members, as well) much more effectively than either a subsystem views search or a quick search. A search can begin against a specific identifying attribute of a resource (such as its name, parent, type, or JBoss ON category) and then has rules that can set how the search handles the string. Multiple search parameters can be strung together to make precise and complex searches. Dynamic searches can be saved and reused later so their results are reliably reproducible. (Section 2.2, “About the Dynamic Search Syntax” covers the details more.)
There are other aspects of dynamic searches like the autocomplete, hints, and highlight search strings that make it easier to use effectively than the limited substring and quick searches. These are covered in Section 2.1, “About Search Suggestions”.
2.1. About Search Suggestions
Dynamic searches are extremely powerful, past simply finding resources. Dynamic searches can run through values in a number of different resource traits, not only the resource name. Dynamic searches can even be saved, so they're repeatable and can be used as ad hoc reporting.
Dynamic searches are easy to use because of search suggestions. A drop-down menu for every search provides three different types of suggestions:
- Saved searches, which contain previous custom search strings and a count of resources which match that search
- Query searches, which provide prompts for available resource traits
- Text searches, which provide a list of resources based on some property in the resource which matches the text prompt
Figure 22. Types of Search Suggestions
When search terms are entered in the field, the matching substrings in possible matching resources are highlighted. By default, the suggestions can match any substring in the resource or in resource configuration traits. The suggestions can be limited to match the string at the beginning or end of the matching attribute using different operators (covered in Section 2.2, “About the Dynamic Search Syntax”).
Figure 23. Highlighting Search Terms
2.2. About the Dynamic Search Syntax
JBoss ON has its own search syntax for dynamic searches. The syntax is supposed to be relatively simple while covering a wide array of search-able items and allowing different phrases to be coupled together.
The basic dynamic search matched whatever text is entered in the search box in a general substring search. The search can allow a more detailed and targeted syntax, in this form:
[search_area].[search_property] operator value operator additional_search
The search_area identifies what type of entry — resource or group — is being searched for. This is an optional value because the search area is implied by the location of the search; i.e., searching in the Resources area implies a resource search, so it's not necessary to include the
resource. part of the search.
Figure 24. Searching by Resources Traits
2.2.1. Basic String Searches
The simplest search with the dynamic search is a substring search. The given search term can match any part or all of the returned value. For example, the
Figure 25. Matching the Search Term
The search term
agen has search suggestions that match (case-insensitive) every resource that has that string anywhere in its name, at the beginning (Agent Plugin Container), middle (RHQ Agent Launcher Script), or end (rhq_agent). Likewise, the results include every resource with that string, regardless of where it appears in the resource entry or attribute.
When multiple words or terms are used together, the search treats them each as individual search terms in an implied AND search. (These complex searches are covered more in Section 2.2.3, “Complex AND and OR Searches”.) However, there can be instances when a multi-word search term should be treated as a single search term, and, for that, the dynamic search allows quotation marks.
Important
Dynamic searches do not support wildcard characters like asterisks (
*) or regular expressions.
The search syntax can use either single (') or double (") quotation marks to enclose a search term that includes whitespace. (Obviously, search terms without whitespaces do not require quotes.) If a search term has a series of space-separated words, then each word is treated as a separate search term in an AND search. For example:
postgres table myexampletable
Using quotation marks tells the search to treat that as a literal phrase rather than individual search terms. As with other search terms, phrases can be strung together in a space-separated list:
"My Compatible Group" 'test box' plugin=jboss 123.4.5.6 trait[partitionName]='my example group' server.example.com
If a search term contains double or single quotation marks in the name, then the other type of boundary character must be used. For example, this group name contains a single quotation mark (apostrophe) character:
name="Production's Main Group"
Make sure to use the same opening and closing term character (you cannot mix single and double quotation marks.) Also, a single quotation mark is only treated as a search definition character when it occurs at the beginning of a search term.
'Hello world requires a closing single quote; Production's does not.
A search can also look for a string where it occurs within a result. For this, the search allows boundary characters that set whether a string occurs at the beginning or end of a value or if it must be an exact match to the value.
The caret (
^) character sets that a search term must appear at the beginning of the result string. For example:
resource.id=^100
This means that only resources with an ID which starts with 100 will be returned in the search.
Likewise, a string may occur only at the end of a value. The boundary character for an end value is a dollar sign (
$). For example:
script$
This returns any resource with any value that ends in script.
Using both a caret and a dollar sign, together, means that the matching result must exactly match the search term, with no additional characters.
The search characters in Table 1, “String Operators” limit the search string by setting where in the result value the string appears.
Table 1. String Operators
| Operator | Description |
|---|---|
| string | The string can occur anywhere in the result string. |
| ^string | The given string must appear at the beginning of the result value. |
| string$ | The given string must appear at the end of the result value. |
| ^string$ | The result must be an exact match of the given string, with no leading or trailing characters. |
Note
The dynamic search syntax treats null as an acceptable value for a search. Running a search which passes null will look for any resource or group with a null value for that property:
resource.trait[Database.startTime] = null
However, putting quotation marks around the term
null will look for a resource or group with a value of the string null:
name = "null"
2.2.2. Property Searches
The search can be narrowed by looking for a specific value or type of attribute in the entry by using a search property. For example, looking for a resource with a CPU usage of 80% (
trait) is different than looking for an entry with an ID that includes 80 (id). The available properties are listed in Table 2, “Resource Search Contexts” and Table 3, “Group Search Contexts”.
Note
It's possible to search using group criteria in the resource search, and the reverse, by specifying the search area and the appropriate properties. For example, it's possible to do a search in the groups area to return the list of groups that a specific resource belongs to. This is done by explicitly passing the search context and search property. For example, in the Groups page, to list any group which contains a resource managed by the Postgres plug-in:
resource.type.plugin = Postgres
Important
The parameter suggestions for
connection, configuration, and trait use the internal property names for the property names (connection[property_name]) rather than the names used in the JBoss ON GUI.
Table 2. Resource Search Contexts
| Property | Description |
|---|---|
| resource.id | The resource ID number assigned by JBoss ON. |
| resource.name | The resource name, which is displayed in the UI. |
| resource.version | The version number of the resource. |
| resource.type.plugin | The resource type, defined by the plug-in used to manage the resource. |
| resource.type.name | The resource type, by name. |
| resource.type.category | The resource type category (platform, server, or service). |
| resource.availability | The resource availability, either UP or DOWN. |
| resource.pluginConfiguration[property-name] | The value of any possible configuration entry in a plug-in. |
| resource.resourceConfiguration[property-name] | The value of any possible configuration entry in a resource. |
| resource.trait[property-name] | The value of any possible measurement trait for a resource. |
There are slightly fewer search properties for groups, since groups have simpler entries than resources.
Table 3. Group Search Contexts
| Property | Description |
|---|---|
| group.name | The name of the group. |
| group.plug-in | For a compatible group, the plug-in which defines the resource type for this group. |
| group.type | For a compatible group, the resource type for this group. |
| group.category | The resource type category (platform, server, or service). |
| group.kind | The type of group, either mixed or compatible. |
| group.availability | The availability of resource in the group, either UP or DOWN. |
The operator first refers to how the results should match the search string (value). This can require an exact match, every value but the one given in the search string. The operator then refers to how multiple search strings relate to each other (AND or OR); both explicit AND and OR statements and parenthetical statements are allowed. Complex searches are covered in Section 2.2.3, “Complex AND and OR Searches”.
Table 4. Search String Operators
| Operator | Description |
|---|---|
| = | Case-insensitive match. |
| == | Case-exact match. |
| != | Case-insensitive negative match (meaning, the value is not the string). |
| !== | Case-exact negative match (meaning, the value is not the string). |
2.2.3. Complex AND and OR Searches
The dynamic search bar assumes that each individual word is a search term (unless terms are defined using quotation marks). Implicitly, multi-word searches are treated as AND searches. For example:
postgres server myserver
This is treated as a series of AND terms:
postgres AND server AND myserver
The dynamic search also allows OR searches, with terms separated by a pipe (
|). For example:
postgres | jbossas
Both AND and OR searches can be entered, and complex searches can be written by stringing multiple search strings together. When there are both AND and OR search criteria, the AND terms are processed first. For example, this search term searches for both B and C, and then either A or B/C.
a | b c
Note
When there are both AND and OR terms used in a complex search, AND terms are given preference. However, terms in parenthesis are evaluated even before AND expressions, so parentheses can be used to override the natural search preference.
Search phrases can be nested to multiple levels using parentheses to group search terms. These parentheses can also be used to override the preferences for AND matches, forcing at least some OR expressions to be processed first. For example, this expression searches for the OR terms first, matching a OR b and c OR d, and then running an AND search on the results of the two OR searches:
(a | b) (c | d)
The results will contain several combinations of values: a c, a d, b c, and b d.
Multiple levels of nesting are allows. For example, this expression requires a AND either b OR c AND d:
(a) (b | (c d))
The matching resources, then, can contain values matching a c d or a b.
2.3. Saving, Reusing, and Deleting Dynamic Searches
Dynamic searches can be saved, which makes it much easier to reuse complex or common searches. To save a search:
- Run the search.
- Click the star in the right of the search bar. When the field comes up, enter the name for the new search.
The search name is then displayed in green.
Saved searches are listed with other search results whenever the dynamic search criteria match any part of the saved search string and immediately whenever the dynamic search field is active, before search parameters are entered. The name of the search is shown in bright green. The drop-down option shows the string used in the saved search in black text beneath the name, to make it clear what the parameters for the search are.
To edit a saved search, select the search from the list of suggestions and then click the gold star. This deletes the search, but leaves the previous search settings in the search box. This allows the search parameters to be edited and then re-saved.
To delete a search, simply click the gold star or the trashcan icon by the search name when it is highlighted in the list. It is immediately removed from the saved searches list.
