---
title: "Query tracing"
description: "Optimize Aerospike Graph performance by tracing slow Gremlin queries using Zipkin."
---

# Query tracing

> For the complete documentation index see: [llms.txt](https://aerospike.com/docs/llms.txt)
> 
> All documentation pages available in markdown.

## Overview

Query Tracing is a feature to trace Gremlin queries in AGS. By logging query attributes such as query structure, execution steps, and time taken at each stage, it helps users diagnose query performance issues and pinpoint performance bottlenecks for optimization.

When to use Query Tracing?

Query Tracing is a valuable tool for diagnosing and optimizing query performance. It is best suited for testing and debugging rather than continuous production use, as it may introduce a minor performance impact.

Use Query Tracing in the following scenarios:

-   **Identifying slow queries** – Automatically detect queries that exceed a predefined SLA without manual intervention.
    
-   **Debugging query performance issues** – Analyze query structure and execution paths to pinpoint inefficiencies.
    
-   **Optimizing query efficiency** – Test different query patterns to determine the most effective approach for performance improvement
    

## How it works

When you enable Query Tracing, AGS automatically collects traces of queries that take longer than the configured threshold. The traces can by viewed with [Zipkin](https://zipkin.io/), an open-source distributed tracing system.

## Setup and usage

1.  **Start Zipkin**
    
    [Zipkin](https://zipkin.io/) is an open-source distributed tracing system. You can run Zipkin in various ways as described in their [documentation](https://zipkin.io/pages/quickstart.html), The procedure described here uses Docker.
    
    Start Zipkin in a Docker container:
    
    ```plaintext
    docker run -d --name ags-zipkin -p 9411:9411 openzipkin/zipkin:latest
    ```
    
2.  **Configure AGS**
    
    To use query tracing, configure the following AGS [options](https://aerospike.com/docs/graph/reference/config):
    
    -   `aerospike.graph.query-tracing.threshold-ms`
        
        Threshold in milliseconds above which queries are traced. Set this option to a positive integer to enable slow query tracing. Defaults to `-1` (disabled).
        
    -   `aerospike.graph.query-tracing.sampling-percentage`
        
        Percentage of queries that exceed the slow query tracing threshold to be traced. Defaults to `100`.
        
    -   `aerospike.graph.query-tracing.opentelemetry-host`
        
        Host IP for Zipkin. Defaults to `localhost`.
        
    -   `aerospike.graph.query-tracing.opentelemetry-port`
        
        Port number for Zipkin. Defaults to `9411`.
        
    -   `aerospike.graph.script-logging.redact-literals`
        
        When enabled, sensitive or literal data within queries (such as IDs, labels, etc) are redacted from the logs for security and privacy reasons. Defaults to `false`.
        
3.  **Start AGS**
    
    Start AGS in a Docker container. See [Deploying AGS](https://aerospike.com/docs/graph/2.5.0/install/docker#run-ags-with-docker) for details. When query tracing is enabled, AGS performs a health check to the Zipkin endpoint on start-up. If configured improperly, AGS fails to start with additional details noted in the AGS logs.
    
    Once AGS is running, any queries which run for longer than the threshold set in the `aerospike.graph.query-tracing.threshold-ms` option appear in the Zipkin UI. Access the Zipkin UI at `http://<zipkin-host>:<zipkin-port>`.
    

## Example setup

Access the Zipkin UI at `http://<zipkin-host-ip>:<zipkin-port>` as specified in the [configuration options](#setup-and-usage). The default address is `http://localhost:9411`.

The following screenshot shows the Zipkin UI with some example queries:

 ![The Zipkin UI](https://aerospike.com/docs/_astro/Zipkin-1.7AwKFeAO_Wwxfn.png)

Click on a query to expand. The following screenshot shows a detailed query breakdown:

 ![Query breakdown](https://aerospike.com/docs/_astro/Zipkin-2.DqhOUci__Z22IXwk.png)