Define SDK’s internal logging API

Background

The issues #1623 and #1624 will define the information that the SDK needs to log. The internal components of the SDK need access to a logger object that helps them to meet these requirements. This object will only be used internally by the SDK and will not be exposed to users. (The public logging API will be defined in #1625 and #1618.)

This issue aims to define the API of this internal logger object.

Shortcomings of the current internal logging API

Currently, the SDK directly uses the ARTLog class for its logging needs.

This class does not provide much in the way of logging helper functionality. For example, there is no way for a component to identify itself as the emitter of a log message — this is handled in an ad-hoc fashion, and the codebase is full of strings that start with things like "RT: %p". This adds overhead to each new log statement written, since developers have to remember to include this context information and they have to check existing log statements to keep things consistent. We would like to reduce the friction involved in writing new log statements.

Prior art

The InternalLogHandler protocol in the Asset Tracking SDK would be a good starting point for thinking about what our API might look like.

It is expected to store a list of subsystems, and to insert this list of subsystems into its logged messages. Upon creating a new subsystem, we create a new logger instance which appends the new subsystem to the provided logger’s list of subsystems (example). This allows us to log context information in a consistent fashion.

It also provides convenience methods for logging information about activity on the public API of the SDK in a consistent fashion.

Next steps

In #1619 we’ll create the type which will implement this interface. Initially its interface will match that of ARTLog. Then, in https://github.com/ably/ably-cocoa/issues/1622, we’ll update the SDK to use this type for its logging.

After that, as we start splitting #1623 and #1624 into concrete tasks, we will split the current issue into corresponding tasks to define any internal API required in order to implement those requirements.

┆Issue is synchronized with this Jira Task by Unito

ably / ably-cocoa