Upgrading `metricq`

metricq follows the semver versioning scheme, so releases of new major versions contain breaking changes. These are listed below, together with suggested steps to take when upgrading.

1.x → 2.0

Changed required Python version to 3.8

Python 3.7 has had issues with TLS/SSL encrypted connections, therefore the minimum required version was changed to 3.8. Make sure, a matching Python version is available on the system.

Location of exception classes

All exception classes have moved into the module metricq.exceptions, documented here. If you are importing exceptions from other submodules directly, your code might now fail with an ImportError.

AgentStoppedError, ConnectFailedError, ReceivedSignalError, PublishFailedError:

Import them from metricq.exceptions, without the ...Error-suffix:

metricq.agent.RPCError, metricq.history_client.InvalidHistoryResponse:

Moved to metricq.exceptions:

Removed exceptions

metricq.source.MetricSendError, metricq.agent.RPCReplyError, metricq.client.ManagementRpcPublishError:: Handle PublishFailed instead.
metricq.sink.SinkError, metricq.sink.SinkResubscribeError:: Removed, the exception that caused them is raised directly.

Validation of `Source` chunk sizes

Previously, anything could be assigned to Source.chunk_size, now only None (to disable automatic chunking) and positive integers are accepted.

Removal of previously deprecated methods

Support for tuple-unpacking instances of TimeAggregate has been removed.
The methods history_metric_list and history_metric_metadata on HistoryClient have been removed. They are superseded by the more general HistoryClient.get_metrics(); to upgrade, make the following changes:
client = HistoryClient(...) -await client.history_metric_list(...) +await client.get_metrics(...) -await client.history_metric_metadata(...) +await client.get_metrics(..., metadata=True)

Type changes to reduce ambiguity

Some class attributes were raw numbers; we gave them appropriate wrapper types that make it harder to accidentally misuse them.

TimeAggregate.active_time and IntervalSource.period:

These are now proper durations (Timedelta) instead of a raw numbers of seconds.

>>> now = Timestamp.now()
>>> agg = TimeAggregate.from_value_pair(now, now + Timedelta.from_ms(500), value=42.0)
>>> agg.active_time.precise_string
'500ms'

Deprecation of `TimeAggregate.integral`

The property TimeAggregate.integral returned the integral of values over the time spanned by a TimeAggregate. To reduce confusion over which time unit is used to integrate, we deprecated it and added TimeAggregate.integral_s and TimeAggregate.integral_ns for seconds- and nanoseconds-based integrals, respectively.

2.x → 3.0

Removal of `TimeAggregate.integral`

The property TimeAggregate.integral returned the integral of values over the time spanned by a TimeAggregate. This property was broken and thus removed, instead, use TimeAggregate.integral_s and TimeAggregate.integral_ns for seconds- and nanoseconds-based integrals, respectively.

3.x → 4.0

Dropping support for older Python versions

With version 4.0, MetricQ-Python only supports Python 3.10 (and newer). You need to upgrade to this Python version.

Removal of Asyncio Loop

Python 3.10 removed the loop parameter from the asyncio interface. In particular, the constructor parameter event_loop of Agent got removed, as well as, the property Agent.event_loop.

4.x → 5.0

Removing internal types module

The module metricq.types has been removed. If you have imported types from it directly you should change to import directly from the primary metricq package.

Timestamp
Timedelta
TimeValue
TimeAggregate
Metric (available in metricq since 5.0)
JsonDict (available in metricq since 5.0)

Return value of `get_metrics`

Client.get_metrics() now always returns a dict with metric names as keys. If metadata=True (default), the dict-values are JsonDict with the metadata. For metadata=False, the dict values are in turn empty dict.

Deprecation of `dict` methods

The methods TimeAggregate.dict() and TimeValue.dict() have been deprecated. Use the individual fields instead. The using code has more context and should know better which fields to include. In particular, whether to use TimeAggregate.mean_sum or TimeAggregate.mean_integral() and which TimeValue.timestamp type to use.

Agent `management_url` renamed to `url`

The constructor parameter management_url of Agent has been renamed to url. A graceful fallback with a DeprecationWarning is provided for now. It will be removed later.

Agent `stop` / `_close`

The method Agent.stop() has different parameters that must be passed when overriding it in a child class. The method _close was renamed to Agent.teardown() and should instead be used for overriding. It is called by Agent.stop() and benefits from a timeout and not having to deal with parameters. In any case, you must call the respective super() method.

Internal Agent changes

Some methods in Agent have changed to reflect new aio_pika typing. The parameter connection_name of Agent.make_connection() is now required. This should not affect any user code.

Renaming of setup.py options

The user option out-dir has been renamed to package-dir.

Upgrading metricq