Log all invocations of public API methods

[lawrence-forooghian]

Background

As described in #1623, we want the SDK to emit messages that describe all of the invocations of the methods that constitute its public API.

Requirements

Let’s take an example of a representative method in the public API of the SDK. Here we have -[ARTRealtimeChannel publish:data:callback:]:

- (void)publish:(nullable NSString *)name data:(nullable id)data callback:(nullable ARTCallback)callback;

When this method is called, we want to immediately emit a log message which includes the following information:

• the fact that a method of the public API was called
• the name of the method that was called
• the arguments that were passed to the method

We want to do this for all of the methods that make up the public API of the SDK (I think more specifically I mean those that have side effects; e.g. we probably don't need to log property getter calls.)

Not yet known

• What log level these messages should be logged at — we’ll defer this until Define the different log levels and how they should be used #1634, let’s use verbose for now
• How exactly the arguments should be represented in the log messages — we’ll defer this until Decide how to represent objects and values in log messages #1637, let’s do whatever’s easiest for now

Logging API considerations (falls under #1617)

The above should be implemented in a way that is consistent throughout the codebase and which is easy to add to new methods. This means exposing an internal logging API that helps us to log these messages.

For example, we could introduce an ARTLogPublicAPICall macro, which would be invoked something like the below (for the example method given above):

ARTLogPublicAPICall(self.logger, "%@", name, "%@", data, "%@", callback)

(The __PRETTY_FUNCTION__ variable might come in handy for writing the above.)

Internally this would call an ARTInternalLog method with a signature something like this:

- (void)logPublicAPICallNamed:(const char *)methodName withLevel:(ARTLogLevel)level file:(const char *)fileName (... arguments ...?);

And this method would call a similar ARTInternalLogCore method, which ultimately would log a string like this:

[NSString stringWithFormat:@"Received call to -[ARTRealtimeChannel publish:data:callback:], with name: %@, data: %@, callback: %@", name, data, callback];

Categorising the log message

We would like to be able to filter the emitted logs to find all of the messages that correspond to a public API call. This might be a good time to consider augmenting our log messages with further metadata that allows us to categorise the messages.

For example, we could add the ability to pass one or more "tags" to the -[ARTVersion2Log log:withLevel:file:line:] method, where a tag is a value that categorises the log message. For example in this case, the tag might be named publicAPICall.

Prior art

The InternalLogHandler protocol in the Asset Tracking SDK provides convenience methods for logging information about activity on the public API of the SDK in a somewhat consistent fashion (but not as consistent as what is proposed above).

┆Issue is synchronized with this Jira Task by Unito

[sync-by-unito]

➤ Automation for Jira commented:

The link to the corresponding Jira issue is https://ably.atlassian.net/browse/SDK-3529