Skip to main content
Sumo Logic

Search Templates

Search templates can help you simplify searches for your users by giving them a few easy input choices. You can have search templates replace any text in a query, including fields, keywords, and arguments to operators. You can also determine what type of information is valid such as text, strings, and keywords.

image1.gif

Behind the scenes, selecting the parts of your query to use in the template is also pretty easy.  You can select which parts of your search should be available and click Create Parameter.

Create a general Search Template

From any query you create, or an existing one you manage, you can create a search template and specify parameters.

  1. Open your query.
  2. Highlight the field, argument, or operator you want to replace and click Create a parameter or alt+v if you want to use the keyboard shortcut.
    image8.png
  3. From the Manage Parameter Settings dialog, provide the name, available values separated by commas, data type, and a brief description.

There are four data types to choose, based on how you want to define a valid parameter:

Number

Numbers only.

String

Considers as a single phrase and will wrap in double-quotes. For example “system errors”.

Any

All characters. Best for substituting texts in paths.

Keyword

Any Sumo Logic keyword. There are some performance benefits to using Sumo Logic keywords so this is a great option to choose if you can.

Optional. You can set autocomplete values for your parameter by selecting Set Values for Parameter.

Select a format:

  1. Optional. Select the available values.
    1. For text entries, enter each value on a separate line.
    2. For Label-Value pairs, copy paste the label-value pairs as comma-delimited lines. If you are using a Lookup make sure that you are using a valid lookup file because the system will reject any lookup file path that it can’t validate.
      image21.png
      1. Select the appropriate values for the field, such as user ID. 
      2. Select values for the corresponding label, such as name.
    3. For a lookup file, you must enter a valid lookup file, saved with the save operator. 
      1. Under Select a format, select Lookup.
      2.  Enter in a valid lookup file or select a shared lookup file from the dropdown. 
      3. Select values for the corresponding label, such as name.
        image27.png
  2. Click Save.

  3. Share your search with any new users by clicking Share underneath your query window.

  4. Grant Edit access to the users and roles that should use this search template.

Create a Search Template for customer IDs

If you want to simplify a user search with a template, you can use label-value pairs to associate human-readable labels such as customer names with machine understandable values, customer IDs. This association allows the user to search by a known category (customer name) instead of a more abstract and harder to memorize value such as a customer ID.

For example, if we use the following sample query on how to locate users by IP addresses:

_sourceCategory=service "Successful login from UI" | parse "[auth=User:*:*:*] [remote_ip=*]" as user,user_id,g,remote_ip
| where user_id matches joeX
| lookup city, region, country_name ,latitude, longitude from geo://location on ip=remote_ip
| where region matches CA
| count by latitude, longitude, user

Fairly simple, but let’s say your team uses this query to locate “time-travelers”, suspicious users who log in from two different geographical areas in an impossibly short amount of time, say New York and California within a timerange of the last 15 minutes. These users do not want to modify the query or look up user ids to user names.  With parameters we can make a search template that will give your users the drop-downs they need quickly.

First let’s create parameters for user_name and state to eliminate the manual entries joeX and CA:

_sourceCategory=service "Successful login from UI"
| parse "[auth=User:*:*:*] [remote_ip=*]" as user,user_id,g,remote_ip
| where user_id matches {{user_name}}
| lookup city, region, country_name ,latitude, longitude from geo://location on ip=remote_ip
| where region matches {{state}}
| count by latitude, longitude, user

Next, let’s specify the user_name parameter as a lookup that already has the association between our user names and our user IDs, in this case /shared/angad/user_info_lookup:

  1. Enter in a valid lookup file that you have saved with the save operator.
    image7.png

  2. Select the appropriate values for the field, such as user ID.

  3. Select values for the corresponding label, such as name.

  4. Click Save.

  5. Share your search with any new users as needed.

Create a Search Template for timeslice

You can create a Search Template parameter for timeslice and allow dashboard viewers to adjust the timeslice to the granularity they want in their dashboard.

For example, let’s take a simple query:

_sourceCategory=apache_error
| timeslice 1m
| count by _timeslice

Yet even this simple query requires users to know about the query language, the use of pipes and fields in Sumo.
You can specify the argument to timeslice as a parameter:

_sourceCategory=apache_error
| timeslice {{parameter}}m
| count by _timeslice 

Make sure you specify the right data type for timeslice, Number. You don't want users to input a string.

The parameter is now available for your users to modify as they want, with any input value for the timeslice. Given that our search is a 15 minute time range, values over 5 are probably not useful. If you want to be more restrictive:

Optional. To give your users even more flexibility letting them append seconds or minutes at the end of the time slice, make the timeslice parameter type Any. Users can then add values such as 15s or 5m, or even longer values of 1h, 1d, or 1w .

_sourceCategory=apache_error
| timeslice {{timeslice}}
| count by _timeslice

SearchTemplates.png

Save. You now have a parameter for your search that allows users to just pick the timeslice from a list of values you feel is appropriate for the query.

Rename a parameter

If you need to rename a parameter, you can do that from the Manage Parameters Settings dialog.

  1. Click the details icon for the parameter setting and select Manage Parameter Settings.
  2. From the Manage Parameter Settings dialog, edit the Parameter Name field.
  3. Click Save.

Delete a Search Template

If you want to delete a search template, delete the existing parameters. When you delete the last remaining parameter, you will no longer see the template view.

  1. Select the details icon of your last parameter.

  2. Select Delete Parameter.

Best Practices

The important thing to remember when using search templates is to carefully consider which parameters in your queries users need to change most.

Here are some of the best candidates for parameters in your search templates.

Parameters

  • Keyword. Let your users supply keywords in the query. In the example below we have created a parameter to specify the keyword for a given query. The parameter data type should be string or keyword.
  • Value for Built in fields or FER fields. Specify value for built-in fields or FER fields. For example, let your users specify a _sourceCategory dynamically.
  • Arguments to an operator. Parameter can be used to specify an argument to an operator. For example, you can use a parameter to specify an argument to timeslice operator.

Data types

There are some best practices for working with data types.

  • If you have a parameter in the search expression, then you should choose Keywords because it makes the queries run faster.
  • If you want to parameterize arguments to an operator then you should use the data types Any or Number, depending on what arguments the user needs to supply in the search.
  • If you want to parameterize numeric arguments to an operator such as timeslice then you should always use the Number data type because there is a check to validate the right data type is being used. The Any data type doesn’t support any validation so people can use it in unsupported values.
  • If you want to parameterize a part of a path,  for example
    /mysearch/{{parameter}}/k8s/api 
    you must use the Any Input type.

Create Dashboards from Search Templates

You can use Search Templates to create convenient filters for your dashboards.

To create a dashboard from a Search Template:

  1. Run your search template and wait for results.

  2. Click Add to Dashboard.
  3. Choose an existing dashboard for this panel, or create a new one.

image13.png

  1. The parameters will automatically become available as dashboard-wide filters.

image10.png


Troubleshooting with Preview mode

When you build search templates you can encounter error messages for a variety of reasons. The most common reason for these errors is parameter-type mismatch. For example, if you enter a string where you should enter a number you're going to get an error. You can use Preview mode to learn more about what might be causing the error in your query.

ErrorMessage.png

Preview mode shows the query with the parameter values applied. For example, there are double quotes around 1, which doesn't look correct. This because my parameter type is set to String when it should be a Number data type. When updated, the query is correct and the error message is gone.