Graylog search parameters: when reusable searches save your team time
Analysts often end up rewriting the same Graylog search for each host, service or customer they investigate, and dashboards become hard to use when every panel is fixed to one value. Search parameters let one saved search or dashboard accept values at run time, so the same query can be reused with a different host, service or customer each time it runs. Parameters are a Graylog Enterprise feature, so teams on Graylog Open need to plan for the license before they design around them.
A parameter is a named placeholder inside a search or dashboard. When someone opens the item, Graylog prompts for a value and substitutes it into the query, which keeps the logic in one place instead of in dozens of copies. Teams usually need parameters when several people investigate similar questions across many entities, or when a shared dashboard should be filtered by a team, region or environment. The Graylog docs describe three parameter types: generic free-form values, dropdowns with static or field-based options, and values populated from a lookup table. Each type suits a different level of control over what users can enter.
Graylog Open users can get part of the same result by saving queries for common cases, using separate dashboards per entity, or filtering on stream and field values by hand. These approaches work at small scale but grow harder to maintain as the number of entities rises. Before you commit to parameters, confirm the current edition requirements, the exact parameter behavior in your Graylog version, and how your team will manage default values and lookup table freshness, using the Graylog search parameters documentation as the reference.
Generic, dropdown and lookup table parameters compared
A generic parameter is a free-form input. The analyst types any value into the field when they run the search or dashboard, and Graylog substitutes that text into the query. This fits ad hoc investigations where the set of possible values is unknown in advance, such as a hostname or user name an analyst has just seen in an alert. It also suits experienced users who know the field values and want to avoid maintaining option lists.
- What the analyst does: types a value, which may be a host, IP address, user, or message fragment, and runs the search with it.
- Where it fits: investigations, one-off hunts and dashboards shared with people who already know the data.
- Main risk: mistyped values, different spellings of the same host, and case or format differences that return empty results without an obvious error.
- Mitigation: write a clear label and description, set a sensible default, and document the expected format next to the parameter.
- Operational note: free text gives no record of which values were common, so pair it with saved searches if the team needs repeatable inputs.
Before you rely on generic parameters for a team workflow, confirm with a test user that the expected value format returns results in your own data, and check how your search fields are indexed.
A dropdown parameter limits the analyst to a set of options. Graylog offers two sources for those options: a static list you type in when you configure the parameter, or values read from a field in the data. The analyst selects from the list, which keeps input consistent and makes dashboards easier to hand over to other teams.
- What the analyst does: selects one option from a list instead of typing.
- Static options: fit fixed sets such as environments, severity levels or known data centers that change rarely.
- Field-based options: fit values that change over time, such as application names, where the list is generated from the data the search covers.
- Main risk: a static list goes stale when a new environment or source appears, so the dashboard silently omits recent data.
- Mitigation: assign an owner to each static list, review it on a fixed schedule, and prefer field-based options when the field is reliably populated.
Before you deploy dropdowns, confirm how Graylog builds field-based options on your Graylog version and check whether the field returns values for the time range your users typically search.
A lookup table parameter fills its options from a Graylog lookup table, so the list of choices comes from the same data that enriches log messages. This is useful when a team already maintains a mapping, such as a list of owned asset names, business units or approved IP ranges, and wants every search and dashboard to use the same list. Changing the table updates the choices without editing each dashboard.
- What the analyst does: selects from values supplied by the lookup table.
- Where it fits: organizations with a maintained reference list shared between enrichment and search.
- Main risk: the parameter is only as current as the lookup table. An unmaintained table produces outdated choices and can hide new assets or owners.
- Ownership: name the team that updates the table, and record how and when it is refreshed.
- Dependency: the table's data source and refresh method determine the quality of the options, which is covered in the lookup table topic.
Before you choose this type, confirm that the lookup table exists in your Graylog version and edition, that the table is owned, and that someone will notice when it stops updating.
Parameter options and when each fits
This table compares the configuration choices a builder makes for a Graylog parameter: type, default, prompting behavior, scope and dropdown source. Read each row for the fit and the trade-off, then confirm exact field names in the Graylog version you run, since labels change between releases.
| Choice | Best fit | Trade-off | Confirm before building |
|---|---|---|---|
| Generic free-form parameter | Values that vary widely, such as a host name, user name or free-text term an analyst types at search time | Nothing stops a typo or an out-of-scope value, so results can be silently empty | Whether the search shows a clear message when a value matches no messages |
| Dropdown with static options | A short, stable list such as log severities, environments or application tiers that you maintain by hand | Every new value needs an edit to the parameter, so the list drifts from reality over time | Where the option list is stored and who on the team may edit it |
| Dropdown populated from a field | Options that should follow the data, such as the distinct values of a source or service field in recent messages | Options reflect only the time range and streams searched, and high-cardinality fields produce long lists | How the field-based source limits its range and how many options it returns |
| Dropdown or value from a lookup table | Mapping a friendly label to a stored value, or keeping options in one governed table that several dashboards share | The table must be maintained and kept current, and a missing key can break the expected result | Which lookup table and key the parameter reads, and who owns updates to that table |
| Default value | A sensible starting point such as the last hour of a common stream, so the first view shows data without edits | A default that is too narrow or too broad can hide events or flood the view for analysts | Whether a default is applied on open and how it interacts with the time range picker |
| Prompt on saved search open | Shared saved searches that analysts run often with different values, so each run asks for the value it needs | Each prompt adds a step, and a skipped prompt can run the search with an empty or default value | Whether the saved search is set to prompt and how skipped values are handled |
| Scope: single search or dashboard widget | A parameter used in one investigation search versus one that drives every widget on a shared dashboard | Dashboard-wide parameters change every widget at once, so a bad value affects the whole view | Whether the parameter is defined at search or dashboard level in your version |
How to build and test a parameterized search
This sequence takes a Graylog search from a one-off query to a reusable, parameterized search on a dashboard, tested against the streams and index sets your team actually uses. The result is a search that prompts for values, returns expected results on default settings, and performs acceptably on your storage layout.
Confirm the Enterprise license and version
Check that your Graylog deployment has an Enterprise license, because search parameters are an Enterprise feature and are not available on Graylog Open. Confirm the server version against the current Graylog documentation, which covers version 7.2, and check that the parameters documentation for that version matches what your administrators see in the interface. Record the license holder, the version and the node count in the change record. The step is done when an administrator can open the parameter options in the search editor without an upgrade prompt. If the option is missing, stop here and resolve the license or version question with Graylog before building anything.
Define parameter types and defaults per use case
Before writing any query, list each question analysts ask repeatedly, such as failed logins for a user, traffic from a host group, or events from one application. For each variable in those questions, choose the parameter type: a generic free-form value for unpredictable input, a dropdown with static or field-based options for a known set, or a lookup table when the values come from a maintained list. Set a default for each parameter that returns a useful result on a sample time range. The step is complete when each parameter has a name, a type, a default and a written owner for the list of values it draws from.
Build the query with parameter placeholders
In the search editor, write the query with placeholders in place of the fixed values, then save the query with its parameters defined. Keep the parameter names short and consistent across searches so that dashboards and saved searches read the same way for every team. Avoid placing a parameter in a leading position of a wildcard expression, since leading wildcards are off by default and will slow or break the query. The step is done when the saved search runs with the default values and returns the same messages as the equivalent hard-coded query you used for comparison.
Verify dropdown values and default results
Open the saved search and check each dropdown. For a field-based dropdown, confirm it lists the values you expect from the stream and index sets in scope, and that no sensitive or unexpected values appear. For a lookup table dropdown, confirm the table is current and that an empty or missing row is handled. Then run the search with the defaults over a sample time range and compare the message count with a manual check of the same range. The step closes when the dropdown values match the expected list and the default run returns results that match the comparison.
Attach the search to a dashboard
Add the parameterized search as a widget on the target dashboard, and set the dashboard-level parameter values or defaults that viewers will see when they open it. Confirm that widgets sharing a parameter name share one value on the page, so a change in one control updates every affected widget. Check the sharing and role settings so that only the intended teams can view the dashboard and change its parameters. The step is complete when a test user with the target role opens the dashboard, changes a parameter and sees every linked widget update.
Test against real stream and index data
Run the dashboard with several parameter combinations drawn from production-like traffic, including a value with no matches, a high-volume value and a value at the edge of the time range. Use the streams and index sets your analysts query, not a copy built for the test, so that routing and retention effects appear in the results. Note any search that returns no messages where you expected some, since this often points to a stream rule or index set mismatch. The step is done when each combination returns the expected result or a documented reason for an empty result.
Review query performance against the index sets
Check how long each parameterized search takes on the index sets it reads, and whether a wide time range or a broad parameter value makes the search slow. Compare the query runtime with and without parameters and confirm the search does not scan index sets that the analyst does not need, which is a common cause of slow dashboards. Confirm with your platform team how index rotation and retention affect the indices in scope, because retention that deletes the oldest indices changes what a historical search can return. The step is complete when the team has written performance notes, a default time range for each dashboard and a named owner for updating parameter lists.
What do teams ask before building Graylog parameters?
Do Graylog search parameters require an Enterprise license?
Yes. Search parameters are a Graylog Enterprise feature, with generic, dropdown and lookup table types. Graylog Open does not include them. Graylog's pricing page lists Graylog Enterprise from 15,000 US dollars per year, with a minimum of 10 GB per day or 100 Graylog Compute Units, licensed on processed data with no per-user or per-device fees. Confirm the current terms with Graylog before budgeting, since the license scope depends on your ingest volume and deployment size. The cost is recurring, so include it in your annual platform budget alongside infrastructure.
Can Graylog Open users build the same thing with saved searches?
Partly. On Graylog Open you can save searches and build dashboards, so analysts can reuse queries and widgets. What you lose is the prompt: a saved search with parameters asks the user for a value such as a host, customer or time-bound identifier each time it runs, so one definition serves many investigations. Without parameters, teams usually keep several near-identical searches with the value hard-coded, which multiplies maintenance. Weigh that duplication against the Enterprise cost before deciding.
How long does building a parameter set take?
Effort figures for this work were not supplied, so ask for a scoped quote rather than relying on a general estimate. The main drivers are the number of searches being converted, how consistent the field names and values are across log sources, and where each dropdown gets its options. A dropdown built from a static list is quick to define. A dropdown built from field values or a lookup table takes longer, because the source data has to be checked for gaps, duplicates and spelling variants first.
What does the team need to provide for parameters to work?
Three things carry most of the weight. First, a named query owner for each shared search or dashboard who decides what the parameter should match and signs off changes. Second, a field naming standard, so the same concept uses the same field name across sources and the dropdown options stay meaningful. Third, lookup table upkeep, including who updates the source file or data adapter, how often, and what happens when it goes stale. Agree these owners before the build starts, because a parameter that points at outdated values fails quietly.
Can our own engineers build parameters without a partner?
Yes, if your team already runs Graylog Enterprise and knows its search and dashboard model well. The work is configuration rather than code, but it depends on clean field names and a clear list of which searches should share parameters. Teams that lack that knowledge, or that have many inconsistent sources, often find that the data-cleanup and ownership steps take longer than the configuration itself. Many teams split the work: they keep ownership internal and bring in an implementation partner for the scoping and build. DeployOpen plans and implements self-hosted open-source platforms in your own infrastructure, and it provides a quote based on a written scope.
Which parts of parameter design are most likely to break?
The most common failures come from data rather than settings. Dropdowns built from field values can list noisy or unexpected entries when a log source changes format. Lookup table parameters stop being useful when the underlying file is not refreshed, and a single renamed field can make a saved search return no results without any error. Test each parameterized search with representative values from every source it covers, and schedule a review whenever a log source or lookup table changes.
What should we confirm before asking for a quote?
Confirm your Graylog edition and license tier, the Graylog version you run, and the list of searches and dashboards you want parameterized. Note which parameter types you need (generic, dropdown or lookup table) and where each dropdown or lookup source lives. Identify the query owners and the team that maintains each data source. A quote should follow from that written scope, so the more precisely these points are defined, the more useful the quote will be.
Access and data risks in shared parameterized searches
Parameters make one search or dashboard serve many teams, which also means one edit or one stale value can reach many people. The cards below pair each risk with the control to set and the check to run in your own Graylog version.
Who can edit shared queries
A shared search or dashboard runs the query its owner wrote, so anyone with edit rights can change the query text, the parameters it exposes or the widgets it shows. Limit edit rights to a small group of maintainers and give everyone else view or run rights only. Confirm how Graylog's sharing and role options apply to searches and dashboards in your version, since these settings have changed across releases.
Parameter values exposing streams
A parameter lets a user change what a search returns, but it does not change who is allowed to read the data. A user who receives a search shared with a broader stream scope may see messages their role would not allow if they ran the query directly. Test each shared search with an account that has only the entitlements of the intended audience, and compare results with a direct search.
Stale dropdown and lookup values
Dropdowns built from static options or field values, and lookup-table parameters, can drift from reality as hosts, services or owners change. Responders who pick a retired value may get empty results and wrongly conclude that nothing happened. Assign an owner to each option list, record when it was last reviewed and add a note to the dashboard stating what the list covers.
Injection-style query mistakes
When a parameter value is inserted into query text, a value containing Lucene operators, quotes or wildcards can change the meaning of the search. For example, an unescaped quote can end a phrase early and broaden results beyond what the owner intended. Restrict generic free-form values where a dropdown fits, escape values in templates and review each parameterized query with hostile test input before sharing it.
Auditing changes to shared dashboards
Without a record of who changed a shared dashboard or search, a widened query or a removed filter can go unnoticed until a responder relies on it. Decide where changes are recorded, who reviews them and how a previous version is restored. Confirm which audit events your Graylog edition and version write for dashboard and search changes, and whether they reach your central log store.
Consistent parameter definitions across environments
A search tested in a lab can behave differently in production when parameter names, default values or lookup tables differ between environments. Keep definitions in a change-controlled source, promote them through the same path as other configuration and compare parameter lists after each deployment. Check how your Graylog version exports and imports searches and dashboards before relying on that process.
Designing dashboards around parameters that analysts actually use
Decide which parameters a search or dashboard widget takes by asking who uses it and what question they bring to it. Host, environment, service and time window are the usual candidates because on-call engineers narrow an investigation along those axes, and a single dashboard can then serve several teams without being copied for each one. Keep fixed anything that serves as a reference point: a compliance evidence search that always covers the same retention scope, or a saved search that documents what an alert was built from. Those artifacts lose their value if an analyst can change them with a dropdown. Before building, list the parameters each widget needs, then confirm in your own Graylog version which parameter types and saved search behaviors your edition includes, since parameters are an Enterprise feature.
Naming is where most parameter sets become hard to use. Choose one convention for parameter names and the fields they bind to, such as a lowercase, environment-neutral pattern, and document it alongside the dashboards so that host means the same thing everywhere. Set defaults for on-call use: a default that matches the most common production view, with a time window short enough to load quickly during an incident, is usually more useful than an empty field that returns everything. Be cautious with broad wildcard defaults. Dashboards that default to all sources, all environments and a long window often hide the one event that matters, so a responder has to narrow the view before seeing anything useful.
Parameters and alerting are separate concerns. Interactive values exist so people can explore data, while event definitions should evaluate fixed searches that do not depend on what an analyst happened to select in the interface. If an alert needs a host or environment filter, write that filter into the event definition or the underlying query, and review it with the alerting design so the same rule behaves the same way for every responder. Treat this as a boundary to enforce in review: a dashboard may be changed by a user, but the detection logic it visualizes should not drift with it. The alerting and event definition topic covers how to build those rules.
How DeployOpen scopes and delivers Graylog search parameters
DeployOpen plans, implements, documents and supports self-hosted Graylog inside your own infrastructure. Most engagements are fixed-scope, with deliverables and timelines agreed in writing before work starts, and ongoing support is available as a retainer.
Search inventory and parameter candidates
Start by listing the searches analysts run most often and noting the values they retype: hostnames, source systems, users, environments or time windows. Each repeated value is a candidate for a parameter. Record which searches feed dashboards and which feed alerts, because a parameter that changes a dashboard panel may not behave the same way inside an event definition. The inventory sets the size and shape of the build.
Stream and index layout review
Parameter values only return useful results if the fields they filter on exist in the right streams and index sets. Confirm which streams hold each log type, which index sets they write to, and whether field names are consistent across sources. Inconsistent names are the most common reason a dropdown shows gaps. Agree on naming conventions before parameters are built so that fields are not renamed later.
Edition and license confirmation
Search parameters are a Graylog Enterprise feature, so the scope depends on whether your organization holds an Enterprise license or will buy one. Confirm the edition, the license term and the data volume it is licensed for before the design is fixed. Graylog Open can run the underlying searches and dashboards, but it cannot provide the parameter types, so a Open-only plan needs a different design.
Build, test and document
DeployOpen builds parameters, saved searches and dashboards in a non-production Graylog environment, then tests each generic, dropdown and lookup table parameter against real messages. Tests cover default values, empty inputs, values with special characters and dashboards that load with no selection. Each build produces documentation that names each parameter, its type, its source and the owner of the underlying lookup table.
Handover and ongoing support
The handover covers exported configuration, a short runbook for changing dropdown options and lookup table contents, and a walkthrough for the team that owns the dashboards. Clients receive the written deliverables agreed at scoping. Ongoing support, including changes after Graylog upgrades, is available as a retainer and is scoped separately from the fixed-scope build.
