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.

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.

5.x → 6.0

Renaming of CLI decorators

The docorators of the CLI feature have been renamed.

  • metricq_syslog_option -> cli.decorator.syslog_option()

  • metricq_server_option -> cli.decorator.server_option()

  • metricq_token_option -> cli.decorator.token_option()

  • metricq_metric_option -> cli.decorator.metric_option()

  • metricq_command -> cli.decorator.command()