History Client

class metricq.HistoryClient(*args, **kwargs)

A MetricQ client to access historical metric data.

await connect()

Connect to the MetricQ network and register this HistoryClient. You can either use this method, or use the class as an async context manager.

Return type:: None

await get_metrics(*args, **kwargs)

Retrieve information for historic metrics matching a selector pattern.

This is like Client.get_metrics(), but sets historic=True by default. See documentation there for a detailed description of the remaining arguments.

Return type:: dict[str, dict[str, Any]]

await history_data_request(metric, start_time, end_time, interval_max, request_type=HistoryRequestType.AGGREGATE_TIMELINE, timeout=60)

Request historical data points of a metric.

Parameters:

metric str: The metric of interest.
start_time Optional[Timestamp]: Only include data points from this point in time onward.
end_time Optional[Timestamp]: Only include data points up to this point in time.
interval_max Optional[Timedelta]: Maximum time between data points in response.
request_type HistoryRequestType (default: <HistoryRequestType.AGGREGATE_TIMELINE: 0>): The type of metric data to request. See HistoryRequestType.
timeout float (default: 60): Operation timeout in seconds.

Raises:

ValueError – if metric is empty or longer than 255 bytes

Return type:

HistoryResponse

await history_aggregate(metric, start_time=None, end_time=None, timeout=60)

Aggregate values of a metric for the specified span of time.

Parameters:

metric str: Name of the metric to aggregate.
start_time Optional[Timestamp] (default: None): Only aggregate values from this point in time onward. If omitted, aggregation starts at the first data point of this metric.
end_time Optional[Timestamp] (default: None): Only aggregate values up to this point in time. If omitted, aggregation includes the most recent values of this metric.
timeout float (default: 60): Operation timeout in seconds.

Return type:

TimeAggregate

Returns:

A single aggregate over values of this metric, including minimum/maximum/average/etc. values.

Raises:

InvalidHistoryResponse –

await history_aggregate_timeline(metric, *, interval_max, start_time=None, end_time=None, timeout=60)

Aggregate values of a metric in multiple steps.

Each aggregate spans values at most interval_max apart. Aggregates are returned in order, consecutive aggregates span consecutive values of this metric. Together, all aggregates span all values from start_time to end_time, inclusive.

Parameters:

metric str: Name of the metric to aggregate.
interval_max Timedelta: Maximum timespan of values covered by each aggregate.
start_time Optional[Timestamp] (default: None): Only aggregate values from this point in time onward. If omitted, aggregation starts at the first data point of this metric.
end_time Optional[Timestamp] (default: None): Only aggregate values up to this point in time. If omitted, aggregation includes the most recent values of this metric.
timeout float (default: 60): Operation timeout in seconds.

Return type:

Iterator[TimeAggregate]

Returns:

An iterator over aggregates for this metric.

Raises:

InvalidHistoryResponse –

await history_last_value(metric, timeout=60)

Fetch the last value recorded for a metric.

If this metric has no values recorded, return None.

Parameters:

metric str: Name of the metric of interest.
timeout float (default: 60): Operation timeout in seconds.

Raises:

InvalidHistoryResponse –

Return type:

Optional[TimeValue]

await history_raw_timeline(metric, start_time=None, end_time=None, timeout=60)

Retrieve raw values of a metric within the specified span of time.

Omitting both start_time and end_time yields all values recorded for this metric, omitting either one yields values up to/starting at a point in time.

Parameters:

metric str: Name of the metric.
start_time Optional[Timestamp] (default: None): Only retrieve values from this point in time onward. If omitted, include all values before end_time.
end_time Optional[Timestamp] (default: None): Only aggregate values up to this point in time. If omitted, include all values after start_time.
timeout float (default: 60): Operation timeout in seconds.

Return type:

Iterator[TimeValue]

Returns:

An iterator over values of this metric.

Raises:

InvalidHistoryResponse –

class metricq.history_client.HistoryRequestType(value)

The type of metric data to request.

Use the value below to select which to request in HistoryClient.history_data_request(). See HistoryResponse for a distinction between raw values and aggregates.

AGGREGATE_TIMELINE = 0: Retrieve a timeline of aggregates with the specified max_interval each.

AGGREGATE = 1: Retrieve a single aggregate over the specified duration.

LAST_VALUE = 2: Only retrieve the last data point recorded for a metric.

FLEX_TIMELINE = 3: Retrieve either aggregates or raw values, depending on the max_interval.

class metricq.history_client.HistoryResponse(proto, request_duration=None)

Response to a history request containing the historical data.

Providers of historical data send either raw values (time-value pairs, see TimeValue) or aggregates (see TimeAggregate).

The data is accessed by iterating over either values() or aggregates(). If the response is of the wrong type, these methods might fail and raise ValueError. Match on the value of mode determine whether this response contains raw values or aggregates. Alternatively, pass convert=True to either values() or aggregates() to transparently convert the data to the desired type.

property mode: HistoryResponseType

The type of response at hand.

This determines the behavior of aggregates() and values():

mode is VALUES:: values() will return an iterator of TimeValue. aggregates() will fail with ValueError, except if called with convert=True.
mode is AGGREGATES:: aggregates() will return an iterator of TimeAggregate. values() will fail with ValueError, except if called with convert=True.
mode is EMPTY:: Both values() and aggregates() return an empty iterator.
mode is LEGACY:: Both values() and aggregates() will raise ValueError unless called with convert=True.

Warning

The values listed here might be non-exhaustive, new ones might be added in the future. If matching on a value of HistoryResponseType, make sure to include a catch-all case:

if response.mode is HistoryResponseType.VALUES:
    ...
elif response.mode is HistoryResponseType.AGGREGATES:
    ...
else:
    # catch-all case, handle it cleanly

for ... in values(convert=False)

An iterator over all data points included in this response.

Parameters:

convert bool (default: False): Convert values transparently if response does not contain raw values. If the response contains aggregates, this will yield the mean value of each aggregate.

Raises:

ValueError – if convert=False and the response does not contain raw values.

Return type:

Iterator[TimeValue]

for ... in aggregates(convert=False)

An iterator over aggregates contained in this response.

Parameters:

convert bool (default: False): Convert values to aggregates transparently if response does not contain aggregates. If the response contains raw values, this will yield an aggregate for each value.

Raises:

ValueError – if convert=False and the underlying response does not contain aggregates
NonMonotonicTimestamps – if the underling data has mode VALUES and timestamps are not strictly monotonically increasing

Return type:

Iterator[TimeAggregate]

class metricq.history_client.HistoryResponseType(value)

The type of a history response.

See HistoryResponse.mode how these values should be interpreted in the context of a HistoryResponse.

EMPTY = 1: The response contains no values at all.

AGGREGATES = 2: The response contains a list of aggregates.

VALUES = 3: The response contains a list of time-value pairs.

LEGACY = 4: The response is in an unspecified legacy format.

class metricq.history_client.InvalidHistoryResponse(extra_message)

Bases: MessageError

A response to a history request could not be decoded.