Automatic Tracing Decorator

[NickSeagull]

Introduction

By using a decorator in all of our service classes (#1381 ) we can benefit from automatic augmentation of the capabilities of these.

The most important one, perhaps, is to the Automatic Tracing capability, which would enable instrumentation and monitoring of Booster applications, and even the CLI, in case we want to track anonymous data of the usage of Booster.

Although this sounds complicated, it really isn't. The key is to use a JavaScript Proxy Object that wraps all the methods of the decorated class, and then act on the arguments, method name, and output.

Naive implementation

The following code is long, but mainly because I've added error handler code and checks to ensure nothing is missing.

For instance, if we wanted to implement a decorator like this, that logs all method calls, and also the errors, it would be like:

export const Component =
  <TError extends Error = Error>(_?: ComponentOptions<TError>) =>

  // ensure that the class has a this.logger field and a this.catch method
  <T extends HasLogger & HasCatchMethod<TError>>(target: Class<T>) => {

    // Get all the property names of the target class
    const props = Object.getOwnPropertyNames(target.prototype)

    // Loop through each property name
    for (const prop of props) {

      // Get the property descriptor
      const descriptor = Object.getOwnPropertyDescriptor(target.prototype, prop)

      // Throw if descriptor is undefined, this should never happen
      if (!descriptor) {
        throw new Error(...)
      }

      // Check if the property is a method (and not the constructor)
      if (prop !== 'constructor' && typeof descriptor.value === 'function') {

        // Wrap the original method with a proxy object that logs it
        const origMethod = descriptor.value
        descriptor.value = new Proxy(origMethod, {
          apply: function (target: Class<T>, thisArg: T, argumentsList: unknown[]): unknown {

            // Get logger object from thisArg and log method name and arguments
            const logger = thisArg.logger
            logger.debug('LOGGING METHOD NAME AND ARGS')

            // Define function for logging error message
            const errorMessage = (error: unknown) => `${Brand.dangerize('[ERROR]')} at ${target.name}#${prop}: ${error}`

            try {
              // Try calling the original method and return result
              const result = target.apply(thisArg, argumentsList) as unknown

              if (result instanceof Promise) {
                // If the result is a Promise, catch any errors and log them, then re-throw the error
                return result.catch(async (error: unknown) => {
                  logger.debug('LOGGING ERROR')
                  const err = await thisArg.catch(error)
                  throw err
                })
              }

              return result

            } catch (error) {
              // If there is an error, log it and try to handle it using the catch method defined on the class instance
              logger.debug('LOGGING ERROR')
              const err = (async () => {
                const x = await thisArg.catch(error)
                return x
              })()
              throw err
            }
          },
        })

        // Redefine the property with the new descriptor
        Object.defineProperty(target.prototype, prop, descriptor)
      }
    }
  }

Issues with this approach

The issue with this implementation is that:

1. It forces the decorated class to depend on a logger instance
2. It forces the user of the decorator to handle errors (which is something good, but not the responsibility of this decorator)
3. It uses the logging object for internal tracing, which is not good as it would pollute the logs of the application.

The solution

Remove the constraints HasLogger and HasCatchMethod, and instead use OpenTelemetry.

OpenTelemetry has a singleton tracer instance that you can get from any part of the code, and has a lot of configuration options and plugins that don't require us to implement everything ourselves.

Also, on top of that, it has a span feature that allows delimiting the start and the end of a process, which is extremely useful for this to delimit the start and the end of method calls.

---

Related discussions

• Use class-based services instead of functions #1381
• Use DIOD library for enabling dependency injection #1382