Search Your Log Data

Search is a core capability of Graylog. The search function allows you to find specific data from within all your ingested logs and visualize the results using a wide range of widgets or other tools.

This topic explains the key concepts of search in Graylog and provides a foundations for further exploration of individual areas.

Search Workflow

The search function is how you find the specific, useful data among all the logs and information you ingest into your Graylog environment. You primarily perform searches from the Search page, which also displays results. You might also perform searches while responding to an immediate alert, as part of a formal investigation, or as routine maintenance and research in your environment.

Search is foundational to Graylog. As such, the search function is embedded in other features in the general workflow. For example, you can define an event to trigger an alert based on specific conditions in log data received, and you define that event with a search query string. Similarly, when you build dashboards to visualize your data, you construct dashboard widgets based on search queries.

Understanding how to use search and how to navigate search results is critical to your success with Graylog.

Hint: To receive valid, useful results from search, you must ensure that you have relevant log data flowing into Graylog and that the data is parsed and normalized in a predictable way. Graylog Illuminate handles parsing for supported log types, and you can also use pipeline rules to ensure clean, searchable data.

Search Query Language

Graylog search is performed using specific syntax based on Apache Lucene's query parser. This query language lets you construct searches as simple as a single keyword and as complex as multipart queries targeting specific log fields and combinations of data. This search syntax provides great control over the data you return, allowing you to focus your results on relevant issues.

Becoming familiar with the query language is essential to success in Graylog. For complete details, see Search Syntax Reference.

Search Controls

The Search page includes search controls that affect how searches are executed. Typically, search controls are UI elements you can set or apply that affect your search query results. Search controls include:

  • Time Frame Selection: The Time Frame Selector allows you to set the time range of the search. This control ensures your search includes the relevant data for any significant events you want to investigate.

  • Time Frame Scrolling: This control works with the Time Frame Selector, allowing you to move forward or backward from the current set time window so that you can review closely related data.

  • Search Filters: Search filters are reusable query snippets that you can save and apply whenever necessary to build modular searches. Use this feature for frequently repeated query segments as well as to make temporary modifications to an active query.

  • Filter by Stream and Stream Categories: You can limit queries by specific streams and stream categories. After you apply one of these filters, queries you perform search only the selected streams or categories until you clear the selection.

  • Undo/Redo: The Undo/Redo function lets you step backward or forward in your search modifications. This feature can be useful when building a search incrementally, but also helps when making modifications to the results view.

To learn more about these features, see Search Controls.

Search Results Enhancements

The search function provides search results enhancements that improve result interpretation and usability after a search is executed. After you set up these features, all relevant query results are displayed with the enhancements. Search results enhancements include:

  • Decorators: This feature allows you to transform how log data appears in search results, such as mapping numeric codes to human-readable labels or reformatting field values, while preserving the integrity of the indexed data.

  • Message Summary Templates: This feature surfaces relevant information in the initial search results without having to expand log messages for key details. You can optionally highlight the most important messages depending on your analysis.

To learn more about these features, see Search Results Enhancements.

Search Management Capabilities

Graylog provides a variety of search management capabilities that allow users to reuse, parameterize, and operationalize searches over time. Note that these features are separate from search execution and results interpretation. Search management features include:

  • Saved Searches: This feature allows you to save frequently repeated search queries. Saved searches can help you quickly start investigations or serve as building blocks for dashboards when shared.

  • Search Query History: This feature captures every search query you enter. You can load searches from you history to perform them again, including making updates to the query or other details such as the time frame.

  • Parameters: A parameter serves as placeholder value in a query, allowing you to substitute a specific value at runtime. Use parameters to make search queries more versatile and portable, particularly with saved searches and search filters.

  • Search Configuration: Graylog administrators can set search configuration options, such as setting a time range query limit and updating the time range presets list. Note that some configurations options can affect your Graylog performance.

  • Export Search Results: You can export search results for external analysis, reporting, and sharing with stakeholders. You can initiate exports from the Search page or directly from dashboard widgets.

  • Search Scripting API: Graylog provides a scripting API to allow easy access to search and aggregation functionality via API calls. This feature allows you to script or automate search functionality, if required.

To learn more about these features, see Search Management.