Understand Ably SDK developers’ requirements for information logged by the SDK

[lawrence-forooghian]

Background

Ably SDK developers are the primary consumers of the log messages emitted by the SDK. This normally occurs in the context of debugging the behaviour of the SDK, for example:

• when writing automated tests that exercise the SDK
• when writing other SDKs that exercise the SDK (for example, ably-asset-tracking-swift)
• when helping users debug unexpected behaviours of the SDK

This issue aims to understand these users’ needs and how we might meet them.

User needs

Their primary need is to have information that helps them understand the observed behaviour of the SDK. This means that, from the log output, they need to be able to understand:

1. the SDK’s inputs and outputs
2. how the inputs led to the outputs

The SDK’s inputs are:

• invocations of the methods that constitute its public API
• events received from the network (transport events, received protocol messages, etc)
• events received from the operating system (e.g. network connectivity status)
• data loaded from disk (e.g. push machine state)

The SDK’s outputs are:

• data emitted through the public API:
  • return values of public methods
  • calls to user-provided callbacks
• interactions made with the network (opening a transport, sending protocol messages, etc)
• data written to disk

The inputs lead to the outputs via:

• interactions between internal SDK components
• decisions made by internal SDK components

The log output needs to allow us to understand the above even in the case where there are potentially multiple instances of the SDK active at the same time (e.g. in test cases). That is, it should allow us to distinguish between logs emitted by different instances of the SDK.

Metadata

The log messages should be accompanied by generally-useful metadata:

• from where in the codebase a log message was emitted; this means both:
  • the broad subsystem and its place in a hierarchy (e.g. "an ARTRealtimeChannel instance with address 0x6000000befc0, belonging to an ARTRealtime instance with address 0x6000000aedc3")
  • the code location (file and line number)
• a tag describing which of the above input/output categories the log message belongs to, if any

Next steps

The next steps for this issue are to split it into actionable tasks. I suggest we approach the scoping and implementation in order of lowest-hanging fruit first — that is, starting with the work that can be done mechanically without requiring us to spend much time understanding the internals of the SDK.

We should also think through potential scenarios in which we would wish to request that the customer send us logs, and whether the requirements gathered above would give us confidence that the logs would help us diagnose the customer’s issue.

Current subtasks

Logging contextual information

• Emit file name and line number with every logged message #1643
• Include identity of component that emitted a log message, where applicable #1659
• Include ancestor information in log messages emitted by child objects #1660

Logging public API activity

• Log all invocations of public API methods #1655
• Create a way to link public API invocations to their eventual outputs #1658
• Log all non-void return values of public API methods #1656 (on hold)
• Log all invocations of callbacks supplied to public API methods #1657

┆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-3502