Understand SDK users’ requirements for log output

[lawrence-forooghian]

Background

Here, “SDK users” means users of the SDK who aren’t Ably SDK developers.

Issues #1623 and #1624 will define the information that the SDK needs to log, and #1617 defines the internal API through which they will do so. However, they say nothing about what happens to this information after it has been submitted to this API.

In order for the logged information to be useful, it needs to be output in some fashion. This issue aims to understand some of the mechanisms through which an SDK user might wish to do so.

What follows in this issue is currently speculation on my part about some possible user needs. It has not been validated by research.

Contexts

There are two likely contexts in which an SDK user will be using the SDK:

1. in an app
2. in a library

Logging within an app

This is the case where a user directly adds the ably-cocoa SDK to their app. In this case, one of two things will be true:

1. They wish to use a default log output solution provided by ably-cocoa (we’ll define this in #1627)
2. They wish to integrate with some other logging solution which their app is using

The second case is the one which interests us here. Some possible logging solutions are:

• Foundation’s NSLog
• The Swift Logger type (not actually sure what library this lives in), or its Objective-C counterpart OSLog
• The open-source (Apple-driven) swift-log package (this seems to be primarily targeting non-Apple platforms, though)
• A custom logging implementation written by the SDK user

Except for NSLog, these loggers provide functionality for augmenting log messages with various kinds of information. For example, Logger supports specifiying privacy levels for interpolated strings, so that the logging system can redact them in certain circumstances to avoid leaking sensitive user information. Both Logger and OSLog also support attaching a "subsystem" and "category" name to a logger instance, for use when filtering log messages. swift-log supports attaching metadata (e.g. a request ID) to a logger. It seems reasonable to expect that SDK users would like the SDK to emit logging information in a manner that allows them to take advantage of these features of the loggers.

The user’s choice of logging solution might ultimately write its output to one or more destinations, such as:

• the console
• a file
• the network

If possible, the SDK should implement its logging solution such that this choice does not affect the performance of the SDK (e.g. consider the case where blocking I/O is used). For example, in the case of Apple’s logging system:

The severity of the log level impacts the speed at which the system logs the information. Debug logs have very low overhead because the system stores them only in memory. Faults and other severe messages incur more overhead because the system often captures additional information and writes all of that information to disk.

However, if we were to mitigate slow logging by, for example, performing logging asynchronously, we would need to consider the implications and document this behaviour.

The user may already have chosen a way in which they wish to represent various pieces of log-related metadata, such as file names and line numbers. In this case, they may wish to be able to present the corresponding metadata emitted by the SDK in a fashion consistent with the rest of their app.

Logging within a library

This is the case where a user is writing a library which has the ably-cocoa SDK as a dependency. Since, after some layers of indirection (i.e. there may be other intermediate libraries), their library will ultimately be used in an app, the same concerns as above apply. The user may also wish to present log-related metadata in a manner consistent with the rest of their library.

Redaction

As mentioned above, the Logger Swift type supports the ability to redact sensitive data. This seems like something that could be more generally useful independent of the logging solution used, for example in the case where we ask users to send us SDK logs to help them debug an issue, or when the user has their own redaction requirements.

Redaction is probably something context-dependent. For example, when debugging the library locally in a test environment with dummy data, we might want all data to be logged without redaction. But when running in a production environment, we may wish to specify a different redaction configuration which hides all data that could be sensitive.

Shortcomings of the current public logging API

Currently, the SDK writes its output to an instance of ARTLog. This writes its output to NSLog. If an SDK user wishes to provide their own logging implementation, they are required to subclass ARTLog. We do not provide any instructions on how they are meant to do so or which methods they should override, which makes this difficult.

The current API also only emits precomposed strings — it does not split out the various pieces of metadata that compose a log message, so a user does not have control over how this metadata is represented in the log output (see comment re file names and line numbers above).

Any new public logging API must be well-documented and simple for an SDK user to implement ("simple to implement" meaning something along the lines of "makes the easy things easy and the hard things possible").

Questions about the current public logging API

ARTLog allows users to change its logging level at any time. I would like to know if this ability is based on any observed requirement, or whether it was something we speculated would be useful. Whilst it's possible to imagine scenarios that would require this functionality — e.g. Ably wrapped by a user library that itself provides this functionality — I wonder whether we want to provide it.

Next steps

Put this in front of Product, for the above assumptions to be validated, and for other user needs to be added.

┆Issue is synchronized with this Jira Task by Unito

[sync-by-unito[bot]]

➤ Automation for Jira commented:

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