Search Management

Graylog provides a variety of search management capabilities that let you reuse, parameterize, and operationalize searches over time. You can also adjust configuration options to customize the search experience for users. These features are separate from search execution and results interpretation.

This article describes the search management features available in Graylog and provides guidance for their use.

Prerequisites

Before proceeding, ensure that the following prerequisites are met:

Search parameters require a Graylog Enterprise license.
You must be a Graylog administrator to change search configuration settings.

Highlights

The following highlights provide a summary of the key takeaways from this article:

Graylog's search management features let you reuse and parameterize searches over time, separate from search execution itself.
Saved searches capture full search configurations, including queries, time ranges, and stream selections, for reuse, sharing, and use as dashboard widget building blocks.
Search parameters let a single saved search accept dynamic input values at runtime, enabling reuse across different environments or investigations without rewriting queries.
Search configuration gives administrators control over system-wide search behavior, including time range limits, auto-refresh intervals, and field-level analysis settings.

Search Parameters Explained

This is a Graylog Enterprise feature. A valid Graylog Enterprise license is required.

Search parameters in Graylog are placeholders embedded in a query string that let a single search accept different input values at runtime without rewriting the query. Rather than hardcoding a specific value, define a named parameter, then reference it throughout the query.

Parameters let you reuse the same search across different environments, investigations, or contexts. Parameters operate within the query itself, injecting dynamic values into the search logic without affecting either the query language or the broader settings that govern search execution.

For complete information about using this feature, see Search Parameters.

Parameters Example

Raj, a tier 2 security analyst at a mid-sized company, investigates failed login attempts across multiple environments — development, staging, and production. Rather than writing a separate query for each environment, Raj writes one search query with an embedded parameter called $environment$.

When Raj defines the parameter, he uses the following values:

Name: Environment
Type: Dropdown
Source: Static Values
Values: List of connection information (IP addresses) for each environment

Each time he loads the saved search, he is prompted to select the target environment from a dropdown. Graylog injects the value he selects into the query in place of the $environment$ parameter. Now Raj can run the same investigation across all three environments without duplicating or editing queries, saving time and reducing the risk of introducing errors.

Saved Searches Explained

Saved searches let you save the searches you define on the Search page so that you can reuse the same search criteria again and in other contexts. A saved search captures the full search configuration, including query strings, time ranges, and stream selections. You can also include parameters in saved searches, either with a default value or a value that you manually select when you load the search.

Saved searches can be loaded at any time, and they can be shared as part of Graylog's collaboration model, letting other users or teams access them. You can use saved searches as building blocks for dashboard widgets, making them a foundational element for ongoing monitoring and reporting workflows.

For complete information about using saved searches and search history, see Saved Searches.

Saved Searches Example

Sally, a security analyst at a mid-sized company, needs to perform routine maintenance and monitoring of her systems. Because she knows she needs to repeat these queries every week, she creates a series of saved searches to investigate activity in the relevant logs. She sets the time frame for these searches to the past seven days, so each time she runs them, she sees the most recent seven days of data. Then, she begins each Monday morning by loading each query and reviews the results for any anomalies.

Sally could also use these saved searches to create a dashboard and create visualizations of the data, which would always show current data for the previous seven days.

Search Query History Explained

Graylog automatically captures every search query you enter, including those you run but do not explicitly save. Query history is saved and stored on a per-user basis, making your history searchable and accessible across sessions.

You access query history by clicking the counterclockwise arrow icon at the right of the search bar. The dropdown displays recent queries in descending order. When you select a query from history, it replaces your current query string so you can execute it immediately or modify it — for example, by changing the time range or adding a search filter — before running. You can also add it to your saved searches, which makes it an entity you can share with other users or teams for collaboration.

For complete information about using search query history, see Saved Searches.

Search Configuration Explained

The Search Configuration page (System > Configurations > Search) includes a list of options that Graylog administrators can set to manage Graylog performance and the user experience when using search.

Query Time Range Limit: Sets the maximum time into the past that users can query data.
Cancellation Timeout: Sets the time in seconds per widget after which search execution is automatically canceled.
Search Time Range Presets: Configures the available search time range presets. Graylog comes with a list of preset values, but you can customize this list to suit your needs.
Surrounding Time Range Options: Configures the available options for the surrounding time range selector.
Surrounding search filter fields: Creates a comma-separated list of message fields to use as filters for the Show surrounding messages query.
Disabled analysis fields: Creates a comma-separated list of message fields for which interface-based analysis features (such as quick values and charts) are disabled in the interface.
Auto-Refresh Interval Options: Configures the available options for the auto-refresh interval selector. Graylog comes with a list of preset values, but you can customize this list to suit your needs.
Default Auto-Refresh Option: Sets the default value for the auto-refresh interval.

Some configuration options can affect Graylog performance, so verify that any changes you make meet the needs of your environment.

For complete information about configuring these settings, see Search Configuration.

Search Configuration Example

Marcus, an IT administrator, notices that analysts on his team are running Graylog queries spanning multiple years of log data, causing performance slowdowns for everyone. To address this issue, Marcus navigates to System > Configurations > Search and sets the Query Time Range Limit to P30D, restricting all searches to a maximum of 30 days.

Marcus also removes several rarely used presets from the time range list and sets the default auto-refresh interval to one minute to reduce unnecessary load. With these changes in place, the team's searches run faster and the system remains stable during peak hours.

Export Search Results

You can export search results for external analysis, reporting, and sharing with stakeholders who do not have Graylog access. Export functionality works with all widget types, including message tables, aggregations, and other widgets, although export formats vary by license level and widget type.

You can customize exports by selecting specific fields, setting message limits, and including decorated fields. You can initiate exports from the Search page or directly from dashboard widgets. Dashboard exports respect applied filters and display currently visible values.

For complete information about this feature, see Export Search Results.

Search Scripting API Explained

The search scripting API provides programmatic access to search and aggregation functionality, designed for automation, integration, and scripted workflows. This tool is not intended for interactive, end-user search through the web interface, but rather for developers and engineers who need to extract log data or compute aggregations as part of external workflows, scheduled scripts, or third-party system integrations.

Use the API instead of the web interface when data retrieval must be automated, repeatable, or embedded in a larger workflow. The API supports two core operations: retrieving messages (individual log records) and executing aggregations (grouped statistical computations). Responses can be retrieved in plain text, CSV, or JSON formats. JSON provides the richest output, including schema metadata and effective time range context.

For complete information about using this feature, see Search Scripting API.

Search Scripting API Example

Dana, a SecOps Engineer at a mid-sized company, needs to pull a daily count of failed authentication attempts from Graylog into her team's external reporting dashboard.

Rather than exporting results manually each morning, Dana writes a scheduled script that calls the search scripting API aggregation endpoint, grouping results by source IP and counting occurrences over the past 24 hours. The script retrieves the response in JSON format and feeds it directly into the dashboard.

This automated workflow gives her team up-to-date threat data every morning without any manual effort.