PingDirectory

Perform a metric query

A metric query returns the collected sample data from the various monitored instances. Depending on client requirements, you can present returned data in different ways.

Common query parameters

instanceType

Types of instances to get data from. Possible values include the following:

  • ds

  • proxy

  • sync

  • metrics-server

instanceLocation

Location(s) of the instances from which data is collected.

instanceHostname

Names of the machines hosting the instances.

instanceVersion

Version(s) of the instances providing the data.

instance

(multi-valued) – ID(s) of the instances from which data is collected. The instance ID is the cn of the external server and the same name as listed by the status command.

startTime

Include samples on or after the specified time. The time is either an absolute time in ISO 8601 format (such as 2016-08-13T19:36:00Z) or a time relative to the endTime (such as -5m or -4h). By default, the start time is -5m.

endTime

Include samples on or before this time. The end time is either an absolute time in ISO 8601 format or a time relative to now (such as -5m or -4h). The default end time is now. Offset time values are relative to the current system clock time on the PingDataMetrics server.

maxIntervals

The number of separate intervals, between the start and end times, returned. This is considered the “resolution” of the data over time. By default, the maximum number of intervals is 1, which means all samples collected between the start and end times will be aggregated into one result according to the statistic selected.

statistic

Retrieve and apply this statistic to the data. Default for count based metrics is count and average for other metric types. Possible values include the following:

  • count

  • average

  • minimum

  • maximum

  • histogram

dimension

Include only these dimension values. A colon separates the dimension name and values, which are separated by commas (for example, op-type:add,delete).

pivot

Pivot by these dimensions. A pivot keeps the data separated along different dimensional values. The value “instance” can be used to keep the data separate between different instances. For metrics that have the histogram statistic, the histogram pivot can also be used to keep the values of each histogram bucket separate.

tz

Specifies the timezone to be used when displaying dates. By default, it is GMT. The timezone is specified in Java Time Zone format. For example, "US/Central" is CST in the United States.

Sub-parameters for the count and average statistics

Both the count and average statistics of count type metrics can have a rate scale applied to occurrences over a period of time using the per sub-parameter. The valid rate scaling values are:

  • s or second

  • m or minute

  • h or hour

Sub-parameters for the histogram statistic

The histogram statistic includes all buckets and keeps the raw value for each bucket. Graphs can be configured to show the percentage of all operations above a given threshold, such as 50 ms. These graphs are useful for looking at a small percentage of operations in a given category. If the value falls between histogram bucket boundaries, the buckets where it falls will be included in the data. Possible values include the following:

min

Includes in the calculation only the histogram data above the given threshold.

max

Provides an upper bound on the histogram value.

percent

Allows the histogram values to be reported as a percentage of the overall values. Instead of returning raw counts, the value is a fraction of the total. This percentage is calculated within a pivot.

If both min and max are specified, the returned value is the sum of all buckets between and including min and max.