Explorer¶

The Guance Explorer can be used within infrastructure, events, logs, APM, RUM PV, CI visualization, Synthetic Tests, Security Check and other Features modules. As one of the important tools for data observability, the Explorer provides various search and filtering methods and supports combining them to obtain final data results. This article will provide a detailed introduction to the Explorer's Features to help you quickly and accurately retrieve data and locate fault issues.

Search¶

Text Search¶

Searches are generally composed of terms and operators. Wildcard queries are supported, where * matches zero or more arbitrary characters and ? matches one arbitrary character. To combine multiple terms into a complex query, you can use Boolean operators (AND/OR/NOT). The Explorer uses the query_string() query syntax.

Terms can be single words or phrases. For example:

• Single word: guance;
• Multiple words: guance test; (equivalent to guance AND test)
• Phrase: "guance test"; (using double quotes converts a group of words into a phrase)

Search Query Example:

JSON Search¶

Prerequisites for Use:

1. Workspace created after June 23, 2022;
2. Used in the Logs Explorer.

By default, precise searches are performed on the content of message, and the message must be in JSON format. Other formats of log content are not supported by this search method. The search format is @key:value; if it’s multi-level JSON, use “.” as the connector, i.e., @key1.key2:value, as shown in the figure below.

Scenario Example:

Message information:
{
    __namespace:tracing,
    cluster_name_k8s:k8s-demo,
    meta:{    
        service:ruoyi-mysql-k8s,
        name:mysql.query,
        resource:select dict_code, dict_sort, dict_label, dict_value, dict_type, css_class, list_class, is_default, status, create_by, create_time, remark 
                from sys_dict_data
 }
}

# Query cluster_name_k8s = k8s-demo
@cluster_name_k8s:k8s-demo     // Precise match
@cluster_name_k8s:k?s*        // Fuzzy match

# Query meta.service = ruoyi-mysql-k8s
@meta.service:ruoyi-mysql-k8s   // Precise match
@meta.service:ruoyi?mysql*   // Fuzzy match

Filtering¶

In the Explorer, you can perform filter queries based on field names and field values.

Note: The main difference between filtering and searching is whether there is a : colon separator in the input content. If it exists, it is judged as a filtering condition; if not, it is considered a search condition.

Operator Description¶

Different types of fields support different operators, as shown below:

• String field operators: =, ≠, match, not match, wildcard, not wildcard, exist, not exist, regexp, not regexp;
• Numeric field operators: =, ≠, >, >=, <, <=, [xx TO xx], exist, not exist.

Wildcard Explanation¶

Supports * or ? wildcard queries, * matches zero or more arbitrary characters, ? matches one arbitrary character.

Value: guanceyun

# Only suffix * matching is used, suitable when the prefix of a value string is fixed and precise, while the latter part changes dynamically.
attribute:guance*    // * matches yun

# Only ? matching is used, suitable when only individual fixed-position characters update dynamically.
attribute:gua?ceyun   // ? matches n

# ? * combined usage
attribute:gua?ce*   // ? matches n , * matches yun

# Mixed * usage
attribute:gua*e*   // First * matches nc , second * matches yun

Special Character Search Processing¶

In the Explorer, some characters have special meanings, such as space which separates multiple words. Therefore, if the search content contains the following characters, special processing is required: space, :, ", “, \, (, ), [, ], {, }.

Convert text into a phrase¶

1. Add " double quotes around the text, converting the text into a phrase;
2. Under this format, the content within double quotes is treated as a whole for matching search, wildcards will not work;
3. If the text contains \ or ", this method cannot be used for searching; please refer to Method Two.

Example: Field name cmdline, field value nginx: worker process:

• Search

"nginx: worker process"   // Successful search, precise match of words

"nginx * process"   // Failed search, because * in double quotes is not recognized as a wildcard

• Filter

cmdline:"nginx: worker process"   // Successful search, precise match of words

cmdline:"nginx: worker*"  // Failed search, because * in double quotes is not recognized as a wildcard

Escape characters¶

1. Add \ before special characters;
2. If the search text itself contains \, the handling methods for search and filtering differ: for search, add three \ before the character to escape it; for filtering, adding one \ is sufficient.

Example: Field name cmdline, field value E:\software_installer\vm\vmware-authd.exe:

• Search

E\:\\\\software_installer\\\\vm\\\\vmware-authd.exe     // Successful search, precise match of words

E\:\\\\software_installer*exe     // Successful search, wildcard fuzzy match

• Filter

cmdline:E\:\\software_installer\\vm\\vmware-authd.exe    // Successful search, precise match of words

cmdline:E\:\\software_installer*exe    // Successful search, wildcard fuzzy match

Boolean Operators¶

Supports further combination of search and filter using AND/OR/NOT.

Search/Filtering Notes¶

Grouping¶

Use parentheses () to increase the priority of data query conditions, meaning that parts enclosed by () will execute their query logic first. Inside (), the query precedence follows NOT > AND > OR.

Handwritten Mode¶

Supports switching the search box to "Handwritten Mode". This hand-written mode covers all Explorers (except dashboards/custom Explorers), allowing UI interaction to add search/filter conditions and switch freely between handwritten and UI modes without making any changes to the content before switching modes, truly enabling real-time switching and restoration between UI and handwritten inputs.

Analysis Mode¶

In the analysis bar of the Explorer, multi-dimensional aggregation queries and analysis statistics based on data are supported, reflecting the distribution characteristics and trends of data at different times under different dimensions.

Click Analysis to enter the data chart analysis method, including time series graphs, Top Lists, pie charts, and rectangular tree maps. You can also choose different time intervals to display data.

Data Display Explanation:

• Data Points: Data points refer to the coordinate points where data values are located. Time series line and area charts will automatically aggregate data points based on your selected time range, with no more than 360 data points; the number of data points for bar charts does not exceed 60.
• Data Range: The data range refers to the value range of each data point, i.e., the interval range from the current data point's coordinate point pushed forward to the previous data point's coordinate point, taking the value of the data within that range.

In chart analysis mode, you can refer to Actions to manage charts.

Quick Filter¶

The Explorer supports editing Quick Filters to add new filter fields. There are two configuration methods: workspace-level filter items and personal-level filter items.

In quick filters, preset fields are supported. Newly added fields default to the field type in field management; if there is none in field management, they default to text format.

• Click the icon shown to collapse the quick filter column:

• Click the icon shown below to quickly add the field to the data list, clicking again will remove it.

Related Actions¶

Filter History¶

Guance supports viewing filter/search history in Filter History, and applying it to different Explorers within the current workspace.

• Open Filter History: Supported by clicking the icon to the right of the search bar above the Explorer, or directly via shortcut key (Mac OS: shift+cmd+k / Windows: shift+ctrl+k) to quickly open the filter history;
• Collapse Filter History: Click the close button x or use the esc key to collapse the filter history.

Note: Filter history is only supported for viewing the current user's filter/search conditions in the local browser.

Operation Instructions¶

In the Explorer's filter history, up to 100 filter/search conditions can be viewed, and you can switch between filter/search conditions using the keyboard arrow keys (↑ ↓). Press the keyboard enter to add to the filter.

• Pin to Filter: Place the mouse over the filter history, and you can pin filter/search conditions to the top via the "Pin to Filter" button on the right;
• Add to Filter: Click the filter/search condition to add it to the Explorer for filtering, supporting multi-selection;
• Cancel Filter: After adding to the filter, click the filter/search condition again to cancel the filter;

• Apply Filter History in Different Explorers: When browsing -source: default filter history (as shown in the figure above) in Logs > Explorer, you can directly use it in link explorers and other Explorers for filtering and searching.

Time Widget¶

Guance supports controlling the data display range of the current Explorer through the Time Widget. Users can manually input time ranges, or quickly select built-in time ranges for the current Explorer, or set custom time ranges.

Manually Input Time Range¶

The Time Widget supports interval display by default, and supports viewing the manual input time range format by clicking the Time Widget, including dynamic time and static time. After inputting, press Enter or click any blank area to filter and view corresponding data according to the input time range.

Quick Filter Time Range¶

You can quickly select corresponding time ranges for data viewing by clicking More in the Time Widget. The Time Widget presets multiple quick filter time ranges, including dropdown lists like "Last 15 Minutes, Last 1 Hour, Last 1 Day", etc., and dynamic times like "30s, 45m, 3d", etc.

Hovering over dynamic times allows real-time linkage with the input box content, clicking views data content corresponding to the time range.

Custom Time Range¶

In addition to the preset time ranges, you can click Custom Time in the Time Widget to select time ranges, including dates and specific times, and click Apply to filter data according to the custom time range.

Time Range in URL¶

In addition to the time range selection provided by the Time Widget, Guance also supports directly modifying the time parameter in the browser's URL for data queries in the current workspace Explorer, supporting seconds, minutes, hours, and days in 4 units, such as time=30s, time=20m, time=6h, time=2d, etc. As shown in the figure below, modifying time=2h in the browser displays data from the last 2 hours in the Explorer.

Lock Time Range¶

Guance supports setting a fixed query time range by clicking the lock icon in the Time Widget. After setting, all Explorers/Dashboards default to displaying the current time range.

As shown in the figure below, if the locked time is "Last 45 Minutes", then all Explorers/Dashboards will query and display data from "Last 45 Minutes" according to the current locked time.

Set Time Zone¶

Guance supports setting the current display time zone in the Time Widget to switch to the corresponding workspace time zone for data viewing.

Enter Time Widget > Time Zone Settings, in the Modify Time Zone window:

• Default display "Browser Time", i.e., the local browser detected time;
• After the owner or administrator sets "Workspace Time Zone", members can choose the configured workspace time zone.

You can also modify in Account Management.

Auto Refresh¶

Helps quickly obtain real-time Explorer data. Optional frequencies: 5s, 10s, 30s, 1m, 5m, 30m, 1h.

If auto-refresh is not needed, select Off (disable) to turn it off.

Note: All Explorers share one refresh configuration.

Display Columns¶

The Explorer supports selecting the number of rows to expand and view log data:

• You can customize adding, editing, deleting, and dragging display columns;
• You can use the keyboard arrow keys (↑ ↓) to select and add display columns;
• You can search fields by keyword;
• You can define display columns as preset fields, and after reporting data through Pipeline field cutting, the reported data can be displayed directly.

Time Column¶

If the Explorer has a time column, you can directly check it in the display column configuration to choose whether to show it in the list.

Add Display Column¶

In the drop-down box for adding display columns, select the field to add to the display column. Or directly search and locate the target field.

If the target field is not found in the drop-down box, you can directly input the field name in "Add Display Column" and press Enter to complete the addition.

Display Column Operations¶

Under the Standard Mode of the Explorer list, when hovering over the display column, click the settings button to perform the following operations on the display column.

Save Snapshot¶

You can perform searches and filters on the currently displayed data, choose the time range, add display columns, etc., then click the snapshot small icon in the upper-left corner of the Explorer, and click Save Snapshot to save the currently displayed data content in the Explorer.

For more details on snapshot usage, refer to Snapshot.

Export¶

In the Explorer, you can perform searches and filters on the currently displayed data, choose the time range, add display columns, etc., then click the on the right side of the Explorer to export the currently displayed data content. You can Export to CSV File, Export to Dashboard, and Export to Note for data viewing and analysis.

To export a specific piece of data, open the detail page of that data, and click the icon in the upper-right corner.

Export to CSV File¶

You can choose to export 1k, 5k, 10k, 50k, or 100k data quantities.

Charts¶

• Chart Export: In the Explorer chart, you can hover over the chart with your mouse, click Export to export or copy the chart to the dashboard or note for display and analysis;
• Chart Time Interval: In the Explorer chart, you can choose the chart's time interval to view the corresponding chart data.

• Collapse/Expand Chart: