Explorer¶

The Guance Explorer can be used within various feature modules such as infrastructure, events, logs, APM, RUM PV, CI visualization, Synthetic Tests, Security Check. As one of the key tools for data observability, the Explorer provides multiple search and filtering methods and supports combining them to obtain final data results. This article will detail the functionality of the Explorer to help you quickly and accurately retrieve data and locate fault issues.

Search¶

Text Search¶

Searches generally consist of two parts: terms and operators. Wildcard queries are supported, where * matches 0 or more arbitrary characters, and ? matches 1 arbitrary character. To combine multiple terms into a complex query, Boolean operators (AND/OR/NOT) can be used. 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 log viewer.

By default, precise searches are performed on the content of message, which must be in JSON format. Logs in other formats do not support this search method. The search format is @key:value. If it's multi-level JSON, use . to connect, i.e., @key1.key2:value, as shown 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.

Operator Description¶

Different types of fields support different operators, as follows:

• 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 Description¶

Supports * or ? wildcard queries, where * matches 0 or more arbitrary characters, and ? matches 1 arbitrary character.

Value: guanceyun

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

# Only ? matching is used, suitable when only certain fixed position characters are dynamically updated
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 Handling¶

In the Explorer, some characters have special meanings, such as space being used to separate multiple words. Therefore, if the search content includes any of the following characters, special handling is required: space, :, ", “, \, (, ), [, ], {, }.

Convert text into a phrase¶

1. Add " double quotes around the text to turn it into a phrase;
2. In this writing style, the content within double quotes will be matched as a whole, and wildcards will not take effect;
3. If the text contains \ or ", this method cannot be used for searching; please use Method Two.

Example Explanation: Searching the 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 treated 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 treated as a wildcard

Escape characters¶

1. Add \ before special characters;
2. If the text itself contains \, the processing methods for search and filter differ: three additional \ are required for escaping during search; only one \ is needed for filtering.

Example Explanation: Searching the 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 conditions in the form of AND/OR/NOT.

Search/Filtering Precautions¶

Grouping¶

Use parentheses () to increase the priority of data query conditions, meaning that if () exists in the query, the search and filter conditions within () will be executed first. Within (), the query priority still follows NOT > AND > OR.

Handwritten Mode¶

Support switching the search box to "Handwritten Mode" This handwritten mode covers all Explorers (except dashboards/custom Explorers). In the new mode, UI interactions allow adding search and filter conditions and freely switch between handwritten mode, without making any changes to the content before switching modes, truly enabling real-time switching and restoration between UI and handwritten input.

Analysis Mode¶

In the Explorer analysis panel, multi-dimensional aggregation queries can be performed on data for statistical analysis, reflecting the distribution characteristics and trends of data at different dimensions over time.

Click Analyze, to enter the data chart analysis mode, including time series graphs, top lists, pie charts, and treemaps. You can also choose different time intervals to display data.

Data Display Explanation:

• Data Points: Data points refer to the coordinates of data values. Time series line and area charts automatically aggregate into data points based on the selected time range, with no more than 360 data points; bar charts have no more than 60 data points.
• Data Range: Data range refers to the value range of each data point, i.e., the interval range from the coordinate point of the current data point back to the previous data point, taking the value of the data within that range.

In chart analysis mode, refer to Operations to manage charts.

Quick Filters¶

In the Explorer, you can edit Quick Filters to add new filter fields. Two configuration methods are supported: workspace-level filter items and personal-level filter items.

Quick filters support preset fields. Newly added fields default to the field type in field management, or text format if they do not exist in field management.

• Click the illustrated icon to hide the quick filter column:

• Click the icon in the figure below to quickly add the field to the data list, click again to remove.

Related Operations¶

Filter History¶

Guance supports viewing filter and search history through Filter History, which can be applied across 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 keys (Mac OS: shift+cmd+k / Windows: shift+ctrl+k) to quickly open the filter history;
• Hide Filter History: Click the close button x or press the esc key to hide the filter history.

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

Operation Instructions¶

In the Explorer's filter history, up to 100 filter and search conditions can be viewed, and you can switch between filter and search conditions using the keyboard arrow keys (↑ ↓). Pressing the enter key adds the selected condition to the filter.

• Pin to Filter: Hover over the filter history and pin frequently used filter/search conditions using 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 multiple selections;
• Remove from Filter: After adding to the filter, clicking the same filter/search condition again removes it from the filter;

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

Time Widget¶

Guance supports controlling the data display range of the current Explorer via the time widget. Users can manually input a time range, or quickly select a built-in time range for the current Explorer, or customize the time range.

Manually Input Time Range¶

The time widget supports interval displays by default, allowing you to manually input the time range format by clicking the time widget. It supports dynamic time and static time. After input, press Enter or click any blank area to filter and view corresponding data according to the entered 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 options like "Last 15 Minutes, Last 1 Hour, Last 1 Day," and dynamic times like "30s, 45m, 3d."

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

Custom Time Range¶

Besides the preset time ranges, you can click Custom Time in the time widget to select a time range, including the date and specific time, and click Apply to filter data according to the customized time range.

URL Time Range¶

In addition to the time range provided by the time widget, Guance also supports modifying the time parameter in the browser's URL directly to query data for the current workspace Explorer. It supports four units: seconds, minutes, hours, and days, such as time=30s, time=20m, time=6h, time=2d, etc. As shown in the figure below, modifying time=2h in the browser causes the Explorer to display data from the last 2 hours.

Lock Time Range¶

Guance supports locking a fixed query time range via 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 display data for "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:

• Displays "Browser Time" by default, which is the local time detected by the browser;
• After the owner or administrator sets "Workspace Time Zone," members can choose the configured workspace time zone.

You can also modify it in Account Management.

Auto Refresh¶

Helps quickly obtain real-time Explorer data. Available 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:

• Customize adding, editing, deleting, and dragging display columns;
• Use keyboard arrow keys (↑ ↓) to select and add display columns;
• Keyword search for fields;
• Define display columns as preset fields, so data reported after pipeline cutting can be displayed directly.

Time Column¶

If the Explorer has a time column, it can be directly checked in the display column configuration to show or hide it in the list.

Adding Display Columns¶

In the drop-down box for adding display columns, select fields to add to the display columns. Alternatively, directly search for 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¶

In the Standard Mode of the Explorer list, hover over the display column and 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, select a time range, add display columns, etc., then click the snapshot icon in the upper left corner of the Explorer and click Save Snapshot to save the data content currently displayed 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, select a time range, add display columns, etc., then click the on the right side of the Explorer to export the data content currently displayed in the Explorer. You can Export to CSV File, Export to Dashboard, and Export to Notebook for data viewing and analysis.

To export a specific data entry, open the details page of that entry 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 entries.

Charts¶

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

• Collapse/Expand Chart: