Logging

[matthew-carroll]

Logging is something that every programmer does, but every programmer does it differently, and often without much thought.

The current state of logging in super_editor is very poor. The logger is either on or off, and when it's on, the console quickly fills with noise. Sometimes part of that noise is important, but whatever portion you're interested in is interspersed with noise that you're not interested in. Moreover, it's unclear what the purpose of any given log message might be.

This proposal outlines some notes on what might constitute effective logging, and how we might achieve it.

Effective Logging

Notes from "Logging in JavaScript Best Practices"

Log statements should make clear the following details:

• Context
• Purpose
• Importance
• Format (human readable, grep-able, computer-parsable)

Types of logging:

• Tracing: for debugging, logging function invocations and variable values. Answers questions like: what did the user do to get to this point?
• Event Logging: Goal: analytics. what's happening inside the system?
• Progress Logging: Goal: UX. Audience: users. Displays the progress of a task to the user.
• Audit: Goal: verification. Audience: compliance, gov, business.

Golden rules:

• Remember the reader
• No personal data
• Answer the question

Everything you wanted to know about logging

Logging can be thought of as:

1. Log Levels
2. Log Shipping
3. Querying & Streaming
4. Serialization & Filtering
5. Defaults & Mutations

Log Levels

RFC 5424 - The Syslog Protocol
https://datatracker.ietf.org/doc/html/rfc5424

Syslog offers the following log levels:

• emerg: 0
• alert: 1
• crit: 2
• error: 3
• warning: 4
• notice: 5
• info : 6
• debug: 7

NPM offers the following log levels:

• error: 0
• warn: 1
• http: 2
• info: 3
• verbose: 4
• debug: 5
• silly: 6

The most important/critical level is the lowest number.

Log Shipping

AKA "transports", "streams", "appenders"

Recommends that these should always be streams. Streams offer back-pressure out of the box.

Querying & Streaming

Want to do some kind of analysis on the logs. Solutions for this are typically SAAS products that are made for log analysis.

Serialization & Filtering

The final representation, e.g., JSON, pretty-printed string.

Defaults & Mutation

Logging should provide defaults, but allow alteration of defaults over time.

AKA "serializers", "tokens", "patterns"

Thoughts on logging

super_editor logs might be used for the following purposes:

• real-time tracing when building new features or debugging issues with existing features
• after-the-fact debugging when investigating reported issues

Describing objects

Effective handling of log messages is required, but is not sufficient for effective logging. Various super_editor objects need to provide useful serializations for logging purposes. For example, every change applied to a document should be logged, and that change should produce a useful serialization (perhaps one serialization for humans and another for robots).

Here's a concept for a Describable interface:

/// An object that can produce a structured description of itself that is useful for human and
/// robot inspection.
abstract class Describable {
  LogObjectDescription debugDescribe();
}

/// A structured description of a particular object at a moment in time.
class LogObjectDescription {
  final String name;
  final Map<String, String> properties;
}

If this description mechanism is adopted, most objects in super_editor should implement Describable. This is especially true for all document change events and attributed spans and text.

Major tracing areas

There are specific super_editor behavior areas that are important for tracing:

• Changes applied to a document
• Document layout reflows, especially with regard to mapping components with their document nodes
• Mapping of user input to document and layout changes
• Changes to, and the current configuration of attributed text
• (De)serialization of documents to formats like markdown

[matthew-carroll]

For now I've brought in the logging package and I've started adding various loggers for areas of functionality. We might come back to this later for rework.