Relational Queries

Overview

Relational queries in Coralogix's Query Builder empower you to analyze and understand the intricate relationships within your distributed traces.

Modern applications often consist of complex, interconnected services. Understanding how these services interact is crucial for performance optimization and issue resolution. With relational queries, you can query spans based on their relationships within a trace, providing deeper insights into your application's behavior.

Understanding trace relationships

Use Coralogix's Query Builder in both Visual Explorer and Custom Dashboards to query spans based on their relationships within a trace. Create more targeted and insightful queries by applying relational prefixes (root., parent., any.) to existing fields.

Relational prefixes

The following relational prefixes are available:

• root.: Identifies spans with root spans that match specific attributes.
• parent.: Pinpoints spans with direct parent spans that match specific attributes.
• any.: Targets all spans in a trace if any span within that trace matches the specified attributes.

Take the following example:

A user visits an online store and clicks on a product to view its details. This simple action triggers a request that flows through multiple service. Each step in this process is captured as a span, and the relationships between these spans help you analyze system behavior and performance.

Root span

The root span represents the very first step in the trace—the initial user request.

In this example, the user's click sends a request to the frontend service to load the product page. This is the root span—it starts everything else.

To query spans based on the root’s attributes:

root.user.id = "73cb6c82-3279-467e-b262-198b33d8964b"

Parent span

A parent span is the direct trigger for another span—the immediate upstream action.

In a payment flow, the payment service might call downstream systems to complete a transaction—for example, a fraud detection service or a notification service that confirms payment to the user. The payment service span is the parent of those downstream spans.

To query spans based on the parent’s attributes:

parent.Service = "paymentservice"

This query returns all spans that were directly triggered by the payment service—helping you analyze what the service initiated, and how those operations performed.

Any span

The any span lets you match spans where any other span in the trace meets a condition, no matter where it appears.

In the e-commerce flow, you might want to surface any product page loads where any span—perhaps an asynchronous logging service or external API—encountered an error.

To query spans based on any matching condition:

any.error = true

Building a relational query

Investigate all spans within traces that originated from a specific service. This helps you analyze the downstream behavior triggered by user interactions starting in the frontend.

1. Open the Query Builder in Visual Explorer or Custom Dashboards.
2. Click “Spans” and select the “Monitoring” option (see limitations for more details).
3. Click “Select field” in the Filter panel.
4. Choose or type a relational prefix (root., parent., or any.) from the dropdown. For example, choose the root. prefix to filter based on the root span—the first span in each trace.
5. The list of available fields updates automatically with the selected prefix applied.
6. Select a field such as root.service.name and assign it a value - for example, frontend-service.

You now see all spans that belong to traces whose root span originated from the frontend-service. This lets you analyze the full trace impact of user-facing requests across services, errors, and latency.

Relational query performance optimization

To enhance the efficiency of your queries using relational field prefixes in Coralogix, consider the following best practices:

1. Utilize multiple filters

• Combine filters: Combine relational prefix usage with non-relational field filters.
• Ensure selectivity: Use filters that significantly reduce the dataset size.
• Fallback filtering: If needed, apply a filter on a common field like application.name to limit the query scope.

2. Understand prefix performance

Different relational field prefixes have varying performance characteristics:

• root. prefix: Most performant; inherently filters to root spans.
• any. prefixes: Moderately performant; Match the first span meeting criteria, reducing the dataset.
• parent. prefix: Potentially less performant; Requires identifying each span’s parent.

3. Limit time ranges

Shorter time ranges reduce data volume, leading to faster query execution.

Converting queries to DataPrime

• Clicking "Convert to DataPrime" will generate the raw query format.
• Switching back to the Builder view will clear any existing query (one-way conversion).

Limitations

• Monitoring pipeline: This feature can be used in the monitoring pipeline only. Queries using relational filters in the Monitoring pipeline will automatically fetch data from both the Monitoring and Compliance pipelines, ensuring broader coverage for complex analysis.

• Query constraints: Up to two different relationships can be included in a query, across both filters and group by functions. For example, it’s not possible to filter by root. and any. and also perform an aggregation on parent..

  Note

  There is no limit on the amount of filters per relationship type.

• Query limits: Broad queries may reach system limits, resulting in incomplete results or timeouts. Narrowing the time range or adding more filters can help mitigate this.

• Field value options: Only field values that exist within the selected time range will appear as selectable filter options.

Support

Need help?

Our world-class customer success team is available 24/7 to walk you through your setup and answer any questions that may come up.

Feel free to reach out to us via our in-app chat or by sending us an email at support@coralogix.com.

Previous Querying Coralogix with SQL

Next Highlights

Theme

Light

light

dark