Latency

One of the main metrics TraceView collects is latency. Latency of your entire app, latency of a particular URL, client-side latency, and more. The Latency API exposes this data, in a couple of different formats, each with a number of different filters.

Endpoints

Series

GET /api-v2/latency/<app-name>/server/series

GET /api-v2/latency/<app-name>/client/series

Return a timeseries line of the application’s latency and volume, either from a client-side or server-side perspective. The latency reflected here is an average latency of the requests within each slice of time. Each point returned is a triple of (timestamp, volume, latency).

Value Description
fields Comma-separated string listing the fieldnames
items A list of lists – the timeseries data
timestamp Milliseconds since the epoch of this point
volume The number of traces recorded at this point
latency The average latency, in microseconds

Each series will have ~100 data points in it (with appropriately varying step size), depending on the time_window requested.

Both endpoints respond to filters, which are described in the section below.

Example output:

{
    "data": {
        "fields": "timestamp,volume,avg_latency",
        'items': [
            [ 1353259500, 11, 1180500 ],
            [ 1353259530, 10, 1246510 ],
            [ 1353259560, 6, 1022766.6666666666 ],
            [ 1353259590, 8, 1130812.5 ]
        ]
    },
    "response": "ok"
}

By-Layer

GET /api-v2/latency/<app-name>/server/by-layer

Returns timeseries data for each of the layers in the application. The return value is a series of objects with attributes named layer and timeseries. The timeseries is an object with attributes for fields (field names) and items (the data series). Each latency value reported here is the total number of seconds spent in the layer. The counts are the total number of calls to the layer. To get average latency per call, divide the latency by the count. To get average latency per request, use the count from the /api-v2/latency/<app-name>/server/by-layer endpoint instead.

Value Description
layer The name of the layer
fields Comma-separated string listing the fieldnames
items Series of [timestamp, volume, total latency] triplets
volume The number of calls into this layer recorded at this point
latency The total latency of this volume in microseconds

Each series will have ~100 data points in it (with appropriately varying step size), depending on the time_window requested.

Both endpoints respond to filters, described in the section below.

Example output:

{
    'data': [{
        'timeseries': {
            'fields': 'timestamp,volume,avg_latency',
            'items': [
                [1378931430.0, 7, 811684.0],
                [1378931460.0, 9, 1036504.0],
                [1378931490.0, 17, 506987.0],
                [1378931520.0, 9, 278861.0]
        ]},
        'layer': 'Cassandra:client'
    }, {
        'timeseries': {
            'fields': 'timestamp,volume,avg_latency',
            'items': [
                [1378931430.0, 6, 715784.0],
                [1378931460.0, 8, 1310193.0],
                [1378931490.0, 7, 631103.0],
                [1378931520.0, 8, 90745.0]
        ]},
        'layer': 'nginx'
    }, {
        'timeseries': {
            'fields': 'timestamp,volume,avg_latency',
            'items': [
                [1378931430.0, 5, 2647537.0],
                [1378931460.0, 9, 2421637.0],
                [1378931490.0, 12, 4999099.0],
                [1378931520.0, 9, 2083804.0]
        ]},
        'layer': 'etlworker'
    }],
    'response': 'ok'
}

Summary

GET /api-v2/latency/<app-name>/server/summary

GET /api-v2/latency/<app-name>/client/summary

Returns a summary of the latency and volume traced, for either the client side or the server side. The return value is a dictionary with the following entries:

Key Value
average The average latency over the time period
latest The most recently recorded average latency*
volume The number of traces seen

* Latency latency is an average over the most recent minute, 15 minutes, or hour, depending on the value of time_window (hour, day, and week, respectively).

Filters

All endpoints in this section can take the following optional query parameters:

Parameter Options Description
time_window hour, day, or week How far back to fetch data. Defaults to hour
time_end ISO-8601 date/time or ms since epoch Shifts the time window back so it ends at that time
domain any valid domain Filter for a specific domain
url any valid url path (i.e., /index.php) Filter for a specific URL path
controller any code controller Filter for a specific controller
action any code action Filter for a specific action

In addition, the client-side endpoints can also take the following optional query parameters:

Parameter Options Description
browser any valid browser Filter for a specific browser family
region any valid region Filter for a specific region

The by-layer endpoint can also support an additional parameter: