Explorer

The Explorer page in Traceable acts as a centralized dashboard for monitoring and analyzing API activity, providing an overarching view of how requests interact with your application system. It categorizes data into endpoint traces, spans, and events, providing a detailed understanding of API behavior. While endpoint traces provide information about the process of individual requests at each API endpoint, spans provide the building blocks of a trace. Events provide additional detail by highlighting specific, significant occurrences of threats within spans, such as security checks or errors, and include context like timestamp and service details.

The Explorer page contains the following tabs:

Note

These tabs are available in Explorer version 2 (v2) only. To switch to v2 from v1, use the Switch to v2 drop-down at the top of the page and vice-versa.

• Explorer — The Explorer tab shows data for endpoint traces, spans, and events. The tab also shows Visualizations, enabling you to select and customize parameters, such as metrics and aggregation types to better understand data trends. The Results table in the tab shows an interactive view of traces, spans, and events with options to expand each row for detailed information. The Filters enable targeted searches, and you can save complex or frequently used queries for quick access through the save queries option.

• Recent — The Recent tab keeps a log of executed queries while categorizing them as in-queue or completed, and enables you to track their statuses, further streamlining query management and tracking.

• Saved — The Saved tab shows queries that you wish to reuse, enabling you to quickly access, edit, or share these saved queries with team members.

Using the above tabs and functionalities, the Explorer page provides efficient monitoring and in-depth analysis of API security, performance, and activity data.

The following sections explain each tab in detail.

Explorer

The Explorer tab contains the following sub-tabs:

• Endpoint Traces — Traces are records of the lifecycle of a request as it navigates through various components or services of your application ecosystem. Endpoint traces are a sub-segment of the trace that provide detailed information about the activities of an API endpoint.

• Spans — Spans are individual components that together build up a trace. They represent a specific function call within a request lifecycle.

• Events — Events are specific time periods within a span at which Traceable observed threats in an API request. They capture details about the operation within a span, for example, errors, service in which they occur, timestamp, etc.

The data in the above tabs is shown for the Last 1 day across All Environments, by default. However, you can customize the time range and environments according to your requirements, from the tab’s top right corner. You can also visualize the data shown in these sub-tabs based on various metrics. For more information on visualizing this data, see Visualization.

The Traceable platform receives raw span data from its agent. Traceable's business logic creates the trace and the Endpoint trace from these spans and events. The Explorer tab also gives you the capability to view raw span and events data. Traceable identifies all the request and response data in an API request; for example, request headers, body, cookies, etc. and captures them as individual span attributes and events. This data is shown in the form of a table under the Results section.

You can also apply one or more filters or conditions to narrow down the search and run the query according to your requirements. If a filter has an associated operation, it is shown when you enter a space in the search bar. For more information on the filters and associated operators, see Filters.

Query Processing

Once you run the query, Traceable inspects the query parameters, like time range, filters, attributes, etc. and dynamically processes it using either of the following methods:

Note

These methods are applied in the Endpoint Traces and Spans tab only.

Using the real-time OLAP store

Traceable, upon receiving the query, synchronously executes it in the OLAP store and shows the result in the page within a 30-second timeout.

Using the data lake

For queries processed using the data lake, Traceable shows a dialogue box on the Explorer page while executing the query in the background. In this box, you can either click Cancel Request to abort the query execution or click Ok, post-which Traceable redirects you to the Recent tab where you can monitor the progress of the query.

You can also navigate away from the page while Traceable is processing the query. Once the query execution is complete, Traceable shows a notification on the page’s bottom right corner with the option to View Results. Upon clicking, you are redirected to the Explorer page where you can view the results.

Based on the query execution and result, you can also create custom rate limiting policies according to your requirements. To create the policy, click + Create Policy above the search bar. While Traceable pre-fills the configurations based on your filters, you can customize them according to your requirements. For more information on these policies, see Custom Policy.

The following sections explain the various components shown in the Explorer tab.

Visualization

The Visualization section shows a chart that you can use for analysis. You can also customize this chart according to your requirements by doing either of the following:

• Add or remove metrics and aggregations

  Note

  You must add at least one metric for the visualization to appear.

• Modify the type of visualization

• Select the interval for which you wish to view the data

• Select the parameter based on which you wish to group the data by

• Select the parameter based on which you wish to order the visualization by

Once you have customized the visualization, you can hover over it to view the required details. The following demo shows how you can create a visualization to view the call rate (sec) metric grouped by endpoint name with 10 maximum groups in the chart, having the interval as None. The visualization is also ordered by the descending number of calls. When you hover the mouse over the columns, a pop-up shows the call rate for all 10 endpoints. Similarly, you can create several visualizations to compare various parameters.

Results

The Results section contains a table showing the list of traces, spans, or events for the time range and environment you select. Each list item contains detailed information about it. To view the information, expand the item by clicking the > icon corresponding to a row. Upon expanding, depending on the tab, you can also create label rules or custom policies according to your business requirements. For more information on creating them, see Label Management and Custom Policy.

In addition to the above actions, you can download the desired number of results by clicking the Menu () icon → Download as CSV in the section’s top right corner.

Filters

Traceable allows you to add one or more filters according to your requirements. To add the filters, complete the following steps:

1. Click the search bar at the top of the page and specify the parameter. For commonly used filters across Endpoint Traces and Spans, see Filter Parameters.

2. Add a space after the parameter and add the operator. For descriptions and examples, see Operators.

3. Specify the values corresponding to the parameter and operator.

4. Click Enter or return and click Run.

You can also auto-fill filters by hovering over a value in any column and clicking the Filter () icon corresponding to it. Upon clicking, Traceable shows a list having the same column name and value, but different operators. You can choose the list item having the operator that you wish to apply. For example, if you wish to see data for services with frontend as the name, then you can select Service Name = frontend. Similarly, you can apply multiple auto-fill filters according to your requirements. The following demo shows how you can add auto-fill filters.

Once you have applied the necessary filters, you can save the queries for later use. For more information on saving queries, see the below section.

Save Queries

Traceable provides you with an option to save your queries for future use. Saving queries can help you save time if you wish to use the same query again. While saving a query, you can select the time range you wish to save the query for. Traceable provides the following options for selecting the time range:

• Application Time Range - This is equivalent to not choosing any time range.

• Last 1 day — This time range is the same as the one you chose from the time-range drop-down at the top of the tab. In the demo shown below, it is Last 1 day. The time range changes if you choose a different one from the drop-down at the top of the page. When you choose this option, the result of the query will be based on the saved time range. This means that if the application time range is 1 week and the saved query time range is 1 day, then the result would be based on the last 1 day's data.

• Exact time — This option saves the query for the time when it was last run. For example, in the demo below, the query is run for 04/11/2024, 19:23:51 - 05/11/2024, 19:23:51. When you save the query with this time range, it will always show the result between 4th and 5th November.

  Note

  The exact time range query result is available only during the data retention period (3 days). If the chosen time range lies outside of this period, the saved query does not show any result.

The following demo shows how you can save a query:

You can view the saved queries in either of the following ways:

• From the Saved tab. For more information, see Saved.

• By clicking the Filter () icon corresponding to the search bar and searching for the query using its name. You can also hover over the File () icon corresponding to a query to view its details.

  

Traceable also provides you the option to save queries from the Recent tab. For more information, see the section below.

Recent

The Recent tab displays the queries that you execute in the Endpoint Traces and Spans tabs under Explorer. The tab is divided into two parts, Queries in Queue and Completed Queries. The following sections explains these parts.

Queries in Queue

This section lists the queries that are currently in queue or are being processed. You may have run these queries in the Explorer tab and they may have required a longer time for execution (processing using the data-lake). The queries are executed simultaneously based on the availability of resources. For each query, Traceable shows some basic details, the time at which you ran the query, and the progress bar for it. You can also cancel the query execution while it is in progress by clicking the X icon corresponding to a row.

Completed Queries

This section lists the queries whose execution is completed. This includes queries that have succeeded or failed. The following details are shown for each query:

• Time of expiry — The amount of time remaining for a query and its result to expire. Traceable stores a query for three days after which it is deleted. If you wish to retain these queries, you can save them according to your requirements.

• Time Range — The time range that you selected in the Explorer tab while running the query.

• Scope — The tab under which you executed the query, for example, Endpoint Traces in the above screenshot.

• Filters — The parameters based on which you applied filters for executing the query, for example, Service Name like (~) service.

• Metric Selections — The number of metrics you selected for visualizing data shown as part of the result. For more information on these metrics, see Visualization.

• Results Selections — The number of columns shown as part of the result, for example, 11 in the above screenshot.

• Run At — The time at which you executed the query in the Explorer tab.

• Actions — This column provides the option to run the query again. You can click Run to execute the queries again to fetch results. Upon clicking, you must select the time range for which you wish to execute query. Traceable redirects you to the Explorer tab and displays the results.
  For queries processed using the data lake (long running queries), Traceable provides you the option to view the Previous Results. Upon clicking, Traceable redirects you to the relevant section (Endpoint Traces or Spans) and shows the results for the time range used while executing the query. For example, if you executed the query for the 27/10/2024, 19:23:51 - 28/10/2024, 19:23:51 time range, then, Traceable shows the results for the same time range.

Traceable also allows you to filter data shown in this section based on the query state (succeeded or failed). To do so, you can click the Filter () icon above the section as shown in the above screenshot.

Additional Actions

You can click the Ellipse () icon corresponding to a query and perform the following actions:

• Copy Link — This option enables you to share the query results with your team members added to the Traceable platform. The team members are redirected to the Explorer tab displaying the result of the query.

• Save Query — This option enables you to save the query for later use. The query is stored indefinitely. You can navigate to the Saved tab and execute the query according to your requirements. While saving the query, you can specify a name for the query, the time range for which you wish to execute the query in the future, and comments. For more information on Saved queries, see Saved.

• Delete — This option allows you to delete the query permanently.

  Note

  A deleted query cannot be restored.

Saved

Traceable provides some pre-saved queries out-of-the-box that are most frequently used. You can execute these queries on the Endpoint Traces from the Saved tab and view the relevant results. You can also edit these queries to modify the name, time range for which they are executed, and add comments.

Apart from the pre-saved queries, the page also lists the queries that you may have saved from the Explorer or Recent tab. The following columns are shown on the page:

• Query — This column shows the query name that you specified while saving the query. It also shows the scope of the query, which is the tab under which the query was executed, such as Endpoint Traces, Spans, or Events. You can also hover over the File icon corresponding to a query to view the configured details for that query.

• Owner — This columns shows the team member name who saved the query. The queries provided out-of-the-box are labeled with Traceable as the owner.

You can click Run corresponding to each query and execute it according to your required time range. You can also click the Ellipse () icon corresponding to a query and perform the following actions:

• Copy Link — This option enables you to share the query results with your team members added to the Traceable platform. The team members are redirected to the Explorer tab displaying the result of the query.

• Edit — This option enables you to edit the query name, time range for which you wish to execute the query, and comments.

• Delete — This option allows you to delete the query permanently.

  Note

  A deleted query cannot be restored.

Filter Parameters

The following tables explain a few of the filter parameters for Endpoint traces and spans.

Endpoint Traces

Spans

Operators

The following table lists the various operators with their descriptions and examples.