Tracking Query Performance with Query Profiler

Query Profiler provides a centralized log for all VQL queries run using both Vault API and Vault Java SDK QueryService. During a session, the profiler records query data in a single log. You can use this record to analyze, troubleshoot, and optimize the performance of all your queries.

For example, Query Profiler can reveal whether any of your Vault’s queries are running slowly or are consistently reporting no data. You can also identify gaps between the data the query returns and the data the SDK code can access.

Only one profiler session can be active at a time. The max query length is 50,000 characters.

Prerequisites

You must have the Admin: Logs: Developer permission to start, end, or download profiler sessions.

Creating a Session with Filters

You can create a new profiler session using Vault API v26.2+ and the Create New Session endpoint.

When starting a profiler session, add filters to capture results for specific aspects such as user, query target, or result count. Add each filter as a body parameter in the Vault API request.

You cannot change filters for an active session.

User & Origin

By default, Query Profiler looks at queries initiated by all users in the Vault. You can identify a specific user to profile by providing the user_id as a filter. This allows you to isolate and analyze only those queries generated by a specific user.

The query_origin filter determines whether a query originated from the Vault API or Vault Java SDK (or both). Select api to capture queries from Vault API calls, or sdk for queries executed with Vault Java SDK QueryService. For a comprehensive view of how different interfaces interact, use all to capture both sources.

Query Target

The query_targets filter allows you to profile specific Vault query targets. To isolate query target traffic, provide a comma-separated list of up to 20 target names. This is useful for troubleshooting an integration that targets specific data such as documents and product__v.

If this parameter is omitted or set to all, the session monitors all available VQL targets in the Vault. You can use this when auditing the performance of all targets.

Performance Thresholds

The result_count and query_time filters allow you to isolate queries based on specific performance criteria instead of reviewing every query executed during a session.

To identify discrepancies between data retrieval and data processing, set the result_count_min and result_count_max filters. Use this to verify why a query is returning a high volume of records while the associated SDK code only accesses some of them.

To find performance bottlenecks, use the query_time_min and query_time_max filters to capture queries within a specific range of execution times. Setting only a minimum duration allows you to filter out fast, performant queries and focus on those that exceed the specified execution time. For example, set a minimum duration of 5 seconds to isolate queries that are running very slowly.

If the initial query execution time is not captured (such as when a session is already active), the profiler still includes the record in the resulting log to ensure visibility.

Response Status

The response_status filter allows you to isolate queries based on the outcome of their execution.

To identify syntax errors or permission issues, set the filter to error. This captures queries that failed to execute and provides the corresponding error message (truncated to 1,500 characters) and error_type.

To investigate areas of improvement, use the warn status. This captures queries that have completed but triggered system warnings.

The success status captures queries that were executed as intended. A success status may still be returned even if num_records_returned is 0.

When the response_status parameter is omitted or set to all, the profiler captures every query regardless of the result.

Viewing & Interpreting Results

Use the List All Sessions endpoint to retrieve a list of all profiler sessions in your Vault, including their current status and metadata. To view a specific session, use the List Single Session endpoint and specify the {session_name} in the path. Use these calls to track the status of a session and identify the specific expiration_date, which is 30 days after session creation.

To download session results, use the Download Session Results endpoint. This returns a .zip file containing a single CSV log file. Results are available around 15 minutes after a session ends.

When interpreting the CSV log, look for the following performance indicators:

A higher num_records_returned than num_records_accessed indicates queries may be inefficiently retrieving more data than the Vault Java SDK logic requires.
The query_execution_time_subsequent_pages and the initial query_execution_time values may reveal bottlenecks during page offset and page retrieval.
The error and error_type columns indicate why specific queries failed.
If a page of results is requested multiple times, the log aggregates the execution time and accessed records into a single row for that query. This allows you to see the total resource impact of a single VQL execution across its entire lifecycle.

Ending a Session

To manually terminate an active session before it completes, use the End Active Session endpoint. A session also terminates automatically when it reaches the defined limits, either 20 minutes of data or 10,000 queries.

To delete a session record and its associated log file from the Vault, use the Delete Session endpoint. Deleting logs helps manage the storage limit of captured sessions (default 10).