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 are now supported for the dashboard panel chart for all three query types. The widget plots can use these variables and update the charts dynamically without updating the query for each value. When the value of the variable changes, the refreshed dashboard will reflect the new value. Variables allow users to make interactive dashboards. Variables are most commonly used to avoid hard coding the values for host names, Kubernetes pods, namespaces, etc. Variables are independent for each dashboard. Variables are shown using the dropdowns at the top of the dashboard.

How to add a Variable to a Dashboard?

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

1. From the left sidebar, choose Dashboards.
2. Find the dashboard to which you want to add a new variable.
3. Select Configure.
4. Select Add Variable from the Variables section tab.
5. Populate the following fields:
   1. Name: Name of the variable. This is used in Metrics builder/ClickHouse query/ PromQL later
   2. Description: Enter a brief and meaningful description of your variable.
   3. Type: Select the variable type from the list of available choices, and the UI changes accordingly.
   4. (Optional) Sort: Sort the values from the above variable type if applicable.
   5. (Optional) Enable multiple values to be checked: Make dropdown multi-select
   6. (Optional) Include an option for ALL values: Show the ALL option which includes all options from the multi-select dropdown
6. When you’ve finished, select the Save button.

Supported Variables types:

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

1. Query - A ClickHouse SQL query that fetches data from ClickHouse (only supported data source at the time) server SigNoz configured to use

   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'
   

   Follwing image shows above case

   

2. Custom - A comma-separated list 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

   

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

   Example: Free text as a variable

   

Variable syntax and usage in queries

All metric queries can refer to variables using any of the following syntax.

1. {{.variable_name}}
2. $variable_name
3. [[variable_name]]
4. {{variable_name}}

For example, A PromQL query for service request rate using dynamic service selection would be.

sum(rate(signoz_calls_total{service_name="$service_name"}[5m]))

Chaining Variables

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

Example

The following example shows how to chain the service name variable to make the endpoint URL dynamic.

1. Write the query for service with name service_name

   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

   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}}
   

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.