cov()

Calculates the covariance between two numeric fields in a group.

Syntax

Parameters

EXPR_X

An expression that returns the value for the first variable.

EXPR_Y

An expression that returns the value for the second variable.

Description

The cov() function accumulates pairs of numeric values returned by EXPR_X and EXPR_Y as it processes records in a group. If either value in a pair is null or non-numeric, that record is excluded from aggregation.

Covariance is a statistical measure of how much two variables change together. It uses the online algorithm based on Welford's method recommended by Wikipedia (Algorithms for calculating variance — Covariance), making it numerically stable.

The function calculates the population covariance (denominator n) and returns the result as a 64-bit floating-point number (double). If there are no valid pairs to aggregate, it returns null.

This function can only be used in aggregation commands such as stats and timechart.

Error codes

N/A

Usage examples

Covariance measures how much two continuous numeric values change together. Fields that are stored as numbers but represent categories (such as the HTTP status code in the status field) are not valid inputs. Use pairs of continuous measurements, such as the request count per minute and the average response latency, as inputs in real operational scenarios.

1. Calculate the covariance between request count and average response latency

   json "[{'minute': 1, 'req_count': 50, 'avg_latency_ms': 30}, {'minute': 2, 'req_count': 120, 'avg_latency_ms': 75}, {'minute': 3, 'req_count': 200, 'avg_latency_ms': 140}, {'minute': 4, 'req_count': 350, 'avg_latency_ms': 280}, {'minute': 5, 'req_count': 500, 'avg_latency_ms': 450}]"
   | stats cov(req_count, avg_latency_ms)
   | # Returns a positive covariance because both values increase together.
   

2. Calculate the covariance between request count and average response latency per host

   json "[{'host': 'web-01', 'req_count': 100, 'avg_latency_ms': 50}, {'host': 'web-01', 'req_count': 220, 'avg_latency_ms': 130}, {'host': 'web-01', 'req_count': 380, 'avg_latency_ms': 260}, {'host': 'web-02', 'req_count': 80, 'avg_latency_ms': 40}, {'host': 'web-02', 'req_count': 180, 'avg_latency_ms': 100}, {'host': 'web-02', 'req_count': 320, 'avg_latency_ms': 220}]"
   | stats cov(req_count, avg_latency_ms) by host
   

3. Null value handling

   json "[{'x': 1, 'y': 2}, {'x': null, 'y': 4}, {'x': 3, 'y': 6}]"
   | stats cov(x, y)
   | # Records where x is null are excluded from aggregation.
   

Compatibility

The cov() function has been available since before Logpresso Sonar 4.0.