Manage Variables in SigNoz

Prerequisites

• This section assumes that your application is already instrumented. For details about how you can instrument your application, see the Instrument Your Application section.
• This section assumes that you are familiar with the basics of monitoring applications.

Variables

Variables allow you to build dynamic dashboards where multiple panels can instantly update their content based on dashboard input values. Variables support several key use cases:

• Replace hard-coded query values with flexible parameters
• Apply a single dashboard template across different services and infrastructure components
• Allow viewers to modify displayed data without altering underlying queries

How to add a Variable to a Dashboard?

To add a variable to a dashboard, follow the steps below:

1. Access Dashboards from the navigation menu.
2. Open the dashboard you want to modify.
3. Enter configuration mode by selecting Configure.
4. Switch to the Variables tab and select Add variable.
5. Complete the configuration:
   1. Name: Define the variable identifier for use in queries. For Dynamic variables, the name auto-populates from the selected attribute key until you edit it manually.
   2. Description: Enter a brief and meaningful description of your variable.
   3. Variable Type: Pick the variable type from the tabs (Dynamic, Textbox, Custom, or Query). The fields below update based on your selection.
   4. (Optional) Sort Values: Choose how values are ordered in the dropdown. See Sort options.
   5. (Optional) Enable multiple values to be checked: Make the dropdown multi-select. See Multi-select variable behavior.
   6. (Optional) Include an option for ALL values: Show the ALL option which includes all options from the multi-select dropdown.
   7. (Optional) Default Value: Pick the value the variable falls back to when no selection is active. The dropdown is populated from the variable's current preview values, or you can enter a custom value. Available for Dynamic, Custom, and Query variables.
6. When you've finished, select the Save button.

Sort options

The Sort Values dropdown controls the order of values in the variable's dropdown. Available options:

• Disabled: Keep values in the order they are returned.
• Alphabetical ascending / Alphabetical descending: Sort case-sensitively (uppercase before lowercase).
• Numerical ascending / Numerical descending: Sort values as numbers.
• Case-insensitive alphabetical ascending / Case-insensitive alphabetical descending: Sort alphabetically, ignoring letter case.

Reorder variables

Variables render in the variables bar in the order they appear in the settings list. To change the order, drag a variable row by its grip handle and drop it in the new position. The change applies as soon as you drop the row.

Validation errors

Some configurations are blocked with an inline error, and the variable cannot be saved until you resolve them:

• Circular dependency: Saving a Query variable whose query references another variable that (directly or indirectly) references it back displays an inline error and blocks the save. Break the cycle before saving.
• Duplicate attribute key: Saving a Dynamic variable whose attribute key is already used by another variable displays "A variable with this attribute key already exists" and blocks the save. Choose a different attribute or edit the existing variable.

Supported Variable types:

SigNoz supports four ways of creating variables: dynamic, query, custom, and textbox.

Two of the type tabs carry a badge in the variable editor:

• Dynamic is marked Beta. It is the recommended way to filter on an attribute, and its behavior may still change.
• Query is marked Not Recommended, because ClickHouse query variables can be slow and brittle. Prefer a Dynamic variable where one fits. See Why avoid ClickHouse query variables.

Dynamic variable

Dynamic variables automatically retrieve attribute values without requiring manual queries. They are configured using two parameters.

1. Field - either an OTEL telemetry intrinsic field (like span name or log severity_text) or a custom attribute from logs, traces, or metrics

2. Source: Pick where to search for values. The field reads <attribute> from <source>, and the options are All telemetry, Logs, Traces, and Metrics. All telemetry searches logs, traces, and metrics simultaneously. A tooltip next to the source warns that this is slower: when a field has identical values across signals (for example, k8s.pod.name is the same whether it comes from logs or traces), choose a single source instead. Use All telemetry only when the same field holds distinct values across different signal types.

Dynamic variable dropdowns display values in two sections:

1. Related values: Filtered based on other variables' current selections
2. All values: Complete list regardless of other filters

The 'Related values' section shows only attribute values that exist within your current context. For example, with variables service.name and name (span name): when you select service.name = adservice, the name dropdown shows:

• Related values: Only spans found in the adservice
• All values: Spans from all services

This helps you quickly focus on relevant data within your selected context.

Note about ALL

The ALL option in dynamic variables means 'apply no filter' rather than 'select everything visible'. When ALL is chosen:

• The system sends a special __all__ parameter instead of a value list
• This tells the query to skip filtering on that field entirely
• The result is the same as having no filter applied

Example: If k8s.pod.name = ALL, the query includes data from all pods, regardless of what's displayed in the dropdown. However, selecting specific values creates an explicit filter using only those selections.

Query variable

Query - A ClickHouse SQL query that fetches data from ClickHouse

Example: You want to query the list of host names from the metrics database and use them as a variable. Any ClickHouse SQL query that returns a column with desired values is valid. For instance, a query to fetch all host names that are reporting the CPU metric collection would be

SELECT DISTINCT JSONExtractString(labels, 'host.name') AS `host.name`
FROM signoz_metrics.distributed_time_series_v4_1day
WHERE metric_name = 'system.cpu.time'

The following image shows the above case

Custom variable

Custom - A comma-separated list of values as a Variable

Example: It is common to have some attributes with a known and small number of unique values, such as the region or availability zone of the application deployment. The custom variable type allows you to achieve this with comma-delimited values. An example for reference

Textbox variable

Textbox - A free text input field with an optional default value

Example: Free text as a variable

Chaining Variables

It is often useful to chain variables to make the dashboard dynamic.

Example

Variable chaining allows you to create dependencies between variables, where one variable's selection filters the available options in another variable.

Note for Dynamic Variables: If you're using dynamic variables, explicit chaining is not necessary. Dynamic variables automatically provide "Related values" based on other variable selections, achieving the same filtering effect without manual configuration.

1. Write the query for service with name service.name

   Copy

   SELECT DISTINCT JSONExtractString(labels, 'service.name') AS `service.name`
   FROM signoz_metrics.distributed_time_series_v4_1day
   WHERE metric_name = 'signoz_calls_total'

2. Write the query for endpoint with name operation

   Copy

   SELECT DISTINCT JSONExtractString(labels, 'operation') AS operation
   FROM signoz_metrics.distributed_time_series_v4_1day
   WHERE metric_name = 'signoz_calls_total' AND JSONExtractString(labels, 'service.name') IN $service.name

Why avoid ClickHouse query variables

Important: We strongly discourage using ClickHouse query variables. Use dynamic variables instead for better performance and ease of use.

Why avoid?

• Performance issues: Custom queries often scan entire tables unnecessarily, causing slow dashboard loads
• Complexity: Requires knowledge of internal table schemas and SQL optimization
• Error-prone: Easy to write inefficient queries that impact overall system performance
• Maintenance burden: Queries may break with schema changes

Recommended approach:

Use dynamic variables which:

• Automatically optimize data retrieval
• Don't require SQL knowledge
• Update faster and more efficiently
• Provide built-in "Related values" filtering

If dynamic variables don't meet your needs:

If you have a specific use case where dynamic variables don't work:

1. Please comment on our tracking issue: https://github.com/SigNoz/signoz/issues/7394
2. Or reach out to support for assistance

We're actively working on dynamic variables and all feedback is welcome.

The variables bar

The variables bar sits above your panels and holds one control per dashboard variable. Each control shows the variable name as a label above its value selector, and all controls align to the bottom of the bar so selectors stay in a straight row even when names differ in length.

• Loading indicator: Query and dynamic variables show an animated bar along the bottom edge of their control while options are being fetched, or while they wait for a parent variable to resolve. The bar disappears once options are available.
• Truncated names: If a variable name is too long to fit its control, hover the name to see the full name in a tooltip.
• Expand and collapse: Use the More / Less toggle to expand or collapse the bar. The state is saved per dashboard and restored on your next visit, so a bar you left expanded loads expanded instead of resetting to collapsed.
• Overflow: When there are more variables than fit, the bar collapses the overflow into a +N button. Hover it to see a tooltip listing each hidden variable's name and its currently selected value.
• Add a variable inline: The + button at the end of the bar opens the variable editor directly, so you can add a variable without going through Configure → Variables.

View variable dependencies

Hover the info icon next to a variable name to open a tooltip that shows how the variable relates to others, along with its optional description:

• Depends on: The parent variables this variable reads from. This section is marked with an upward arrow and its names render in green.
• Used by: The child variables that reference this variable. This section is marked with a downward arrow and its names render in amber.

Use this to trace a chain before you change a variable, so you know which downstream variables and panels a change affects.

Multi-select variable behavior

When a variable has Enable multiple values to be checked turned on, it appears in the variables bar as a multi-select dropdown:

• Selections commit when the dropdown closes. Dependent panels and variables update once, after you close the dropdown, instead of cascading on every individual checkbox click.
• Only button. Hovering an option row shows an Only button. Selecting it keeps that single value and deselects all others.
• Clearing resets to the default. Clearing the selection with the × button falls back to the variable's configured default instead of leaving it empty.
• Overflow chip. When more than one value is selected, the variable pill shows the first selected value plus a +N chip for the remaining selections. Pills are truncated so the bar does not grow to fit every selected value.
• Stable defaults. Re-running the variable's query no longer clears the default when it returns the same option set. The default is reset only when the option set changes and no longer contains the current default.

Variable selections are preserved when you move between the dashboard and the panel editor, including across a hard refresh of the editor.

Filter panel data in real time

Selections in the variables bar filter panel data in real time. Choosing a value refetches data for every panel that uses the variable, with no page reload.

How selections are sent to each panel's query:

• Single value: The selected value replaces the variable reference in the query.
• Multi-select: When the variable allows multiple values and several are selected, all selected values are passed to each query.
• ALL (Dynamic variables): Selecting ALL applies no filter on that field. Internally it sends the __all__ sentinel so the query returns results across every value of the attribute. See Note about ALL.
• No selection: The query uses the variable's configured default value. If no default is configured, the variable is omitted from the query rather than sent as an empty value.

How variables load and refresh

SigNoz resolves dashboard variables in dependency order and refreshes only the panels that need it.

Dependency-ordered loading

Query variables load in dependency order. When a child variable references a parent variable (for example, a pod query that filters on $namespace), the child does not start fetching until the parent has resolved. This prevents the child from loading a stale or empty option list before the parent value is known.

Dynamic variables fetch their options in parallel with query variables at page load, so dashboards with mixed variable types populate their dropdowns faster.

Selective panel refresh

When you change a variable, SigNoz reloads only the panels that actually reference that variable. Panels that do not use the changed variable keep their current data and do not trigger new queries, so unrelated parts of the dashboard stay responsive.

Panels that reference a variable wait until every referenced variable has a resolved value before they render. They stay in a loading state instead of flashing "No data" while variables are still resolving. While a referenced variable is updating, each affected panel keeps showing its last-known data and renders a loading indicator in the background, so the panel does not go blank.

Apply a Dynamic variable to panels

A Dynamic variable does not filter anything until it is wired into panel queries. Rather than editing each panel by hand, pick the panels the variable should apply to and SigNoz writes the filter clause into their queries for you.

1. Open Configure, go to the Variables tab, and add or edit a Dynamic variable.
2. Use the Apply to panels multi-select to choose the panels the variable should filter. Panels that already reference the variable are pre-selected, so the picker reflects the current state.
3. Select Save.

For each selected panel, SigNoz composes a filter clause of the form <attribute> IN $<variable> into the panel's builder queries. For example, a Dynamic variable named pod on the k8s.pod.name attribute adds k8s.pod.name IN $pod.

Review the impact before applying

Because applying a variable rewrites panel queries, SigNoz shows an impact dialog before the change lands:

Applying $<variable> can update upto N panel queries. Review the changes before applying.

Each row shows the panel's Current query text (read-only) and the proposed Result, which you can edit. Clear a row's checkbox to leave that panel untouched. Confirm to apply every included change at once.

This is the same review dialog used when you rename or delete a referenced variable.

Rename or delete a referenced variable

When you rename or delete a variable that is referenced by panel queries or by other variables, SigNoz blocks the save behind an impact dialog so you can review every affected location before applying the change.

Rename impact review

1. Open Configure and go to the Variables tab, then edit the variable.
2. Change the Name and select Save.
3. The impact dialog lists every usage of the variable across Query Builder, PromQL, and ClickHouse panels, and any other variable definitions that reference it. Each row shows:
   • Current: the existing query text (read-only).
   • Result: the proposed rewrite with the new variable name. You can edit this field before confirming.
   • A checkbox to include or exclude that usage from the rename.
4. Deselect any usage you do not want to update, or edit its Result text manually.
5. Select Rename to apply every included change at once.

Delete impact review

1. In the Variables tab, delete a variable that is referenced elsewhere.
2. The same dialog appears with each affected location:
   • Query Builder filter clauses that reference the variable are stripped automatically in the proposed Result.
   • Raw queries (PromQL, ClickHouse SQL) and dependent variable definitions are shown unchanged, so you can edit them manually before deleting.
3. Edit or exclude each usage, then select Delete to apply the change.

Share variable selections

Variable selections are stored per dashboard in your browser rather than being written to the address bar as you change them. Copying the URL from your browser does not carry your selections to another user.

To share a link that reproduces your current selections:

1. Set the variable values you want to share.
2. Select Share in the dashboard header.
3. Turn on Include variables, then select Copy page link.

The Include variables toggle appears only when the dashboard has at least one variable, and is off by default. The generated link carries your selections in an encoded ?variables= query parameter. When the recipient opens it, SigNoz applies the selections, keeps them for subsequent refreshes, then removes the parameter from the URL.

Create alerts from a panel

When you create an alert from a dashboard panel that has active variable selections, SigNoz resolves the variable references in the panel query into their current values before opening the alert builder. For example, if $service.name is set to adservice in the variables bar, the alert builder opens with adservice in the query instead of the raw $service.name reference.

To create the alert, open the panel's action menu and select Create Alerts. For the full flow, including how the alert condition is seeded, see Create an alert from a panel.

Next Steps

• Using Variables in Queries: learn how to reference variables in Query Builder, ClickHouse SQL, and PromQL queries.
• Interactivity in Dashboards: drill down from panels and create alerts from a panel.

Get Help

If you need help with the steps in this topic, please reach out to us on SigNoz Community Slack. If you are a SigNoz Cloud user, please use in product chat support located at the bottom right corner of your SigNoz instance or contact us at cloud-support@signoz.io.