ajstacy/adze

A library for shaping your JavaScript logs.

adze's Issues

printed is incorrectly returning true when the log is silent

refactor cases where the log render is null

• The log render should only be null when a log is filtered out by its namespace, label, or level.
• The log render should be generated for silent logs.

utilize structuredClone for duplication of log data and remove defaultsDeep

https://developer.mozilla.org/en-US/docs/Web/API/structuredClone

By implementing structuredClone and removing defaultsDeep we can eliminate lodash as a dependency and reduce our package size.

Support for pretty printing data to the terminal?

Does adze support pretty printing JSON objects/arrays to the terminal? That could be really useful especially if JSON objects could be color highlighted.

Adze Concepts modifiers incorrect verbiage

In the Adze Concepts section of the docs, the modifiers subsection has incorrect verbiage on the example. We need to update the example code and snap new screenshots.

Create Website for Adze that Includes Examples

Create a website for Adze that includes documentation, examples, and a playground.

Create a stdout Modifier

• Add support for a new modifier that adds support for stdout by stripping away extra formatting.

Create Convenience Formatter Functions

Create a couple of convenience log data formatter functions for use within log listeners that accepts the log data object.

• formatHumanReadable(data);
• formatMachineReadable(data);

Remove adze-0.4.2.tgz from repository

Shed: Optionally Cache to Local Storage for Persistence

Allow Shed to be configured to cache logs to local storage to add persistance across refreshes and reloads.

Create Allowed Namespaces API

Rather than letting the user create a new namespace on the fly, it would be useful to control them centrally so that you can know what namespaces exist. This will assist with filtering logs because you can view all app namespaces at a glance.

How to use with Google Cloud?

GCPs logs are rather odd. Using adze normally results in one log per line. So if I log an object, with 5 properties, I see 5 separate logs. I have tried to do a bit of research and it's something to do with stdout.

I tried using machineReadable, but it resulted in this error:

Converting circular structure to JSON
--> starting at object with constructor 'Socket'
| property 'parser' -> object with constructor 'HTTPParser'
--- property 'socket' closes the circle

Any ideas on how to configure adze to "work"? They have a few packages for compatability with loggers:

• https://github.com/googleapis/nodejs-logging
• https://github.com/googleapis/nodejs-logging-winston

log object should be extended when a label is added to support counters, timers, and mdc

When a log chain is started the label() method should return an extended log object that contains the counter, timer, and mdc methods. This will allow TS to throw errors when a user attempts to write a log using a counter, timer, or mdc method that hasn't already specified a label.

This will allow the modifier queue to be removed since labels will be enforced to occur before count, time, and mdc.

Add documentation for unit testing

Write documentation explaining global environment variables that can be used for toggling logs during unit testing.

Configuration Flag to Disable Styling

Logs should be able to have styling disabled through a flag. In some cases, stdout will print style characters which is undesirable.

Add CODEOWNERS file

https://docs.github.com/en/github/creating-cloning-and-archiving-repositories/about-code-owners

Setup SSL Cert for Docs

Follow the steps here to setup SSL: https://docs.github.com/en/pages/getting-started-with-github-pages/securing-your-github-pages-site-with-https

Switch to GitHub Actions

• Travis CI now caps OSS project builds. Switching to GH Actions.

make render of number of args in log in the leader optional

Feature suggestion: intercept log data or configurable middleware

I've run into a few situations while using adze where I wish I had a way to modify or intercept the log data before it is terminated. Something like this would be exceptionally useful.

adze({
  middlware: (logData) => {
    if(foo) {
      // terminate as is
      return logData
    } else {
      // do not log this request
      return null
    }
  }
});

// Or

adze().intercept((logData) => {/* do something else */}).log("log something")

This would be exceptionally handy for writing custom logging code ontop of adze. In my case this would be helpful for building a react hook where a log call needs to be placed inside of an effect.

react hook example

const useAdzeEffect = () => {
  const [logDataState, setLogDataState] = useState(null);
  const logger = adze().intercept((currentLogData) => {
    if(logDataState) {
       return currentLogData;
    } else {
      setLogDataState(currentLogData)
    }
  });
  useEffect(() => {
    if(logDataState) {
      logDataState
      logger.log(...logDataState.args)
    }
    
  }, [logData])
  return logger;
}

const MyComponent = () => {
  let logger = useAdzeEffect()
  logger.label("MyComponent").log("Some state variable")
  //...
}

Another use could be modifying the log level or isSilent keys in place in special cases, such as a function taking too long.

Slow function warning example

function mySometimesSlowFunction() {
  adze().label('slowfn').time.verbose('Begin slow function')
  // occasionally slow code...
  adze().label('slowfn').timeEnd.intercept(
    (logData) => {
      if(logData.data.timeElapsed > 10000){
        logData.level = 0;
      }
      return logData
    }
  ).verbose('Function complete')
}

Going back to react, adding the ability to not log every other render when strict mode is enabled would be very handy.

React strict mode example

function useStrictLogger() {
  const [countState, setCountState] = useState(0)
  adze().intercept(
    (logData) => {
      if(countState % 2 === 0){
        return null
      }
      return logData
    }
  ).log('Rendered component')
  setCountState(countState + 1);
}

And some other helpful use cases:

• Debugging custom levels and contexts by logging in the logger
• Adjusting browser console output styles dynamically based on the content of the log
• Filtering PII before it reaches the shed
• Adding / Removing methods from modifierQueue dynamically

This is only a suggestion of course, and I realize an 'escape hatch' like this is not best practice and much of this can be accomplished by filtering in the shed. That said, from my experience using adze, not having a way to add my own modifiers has been an inconvenience when using an otherwise lovely logging library.

Create Backend Node Service for Collecting Logs Remotely

Create a backend Node service that provides an API for collecting logs remotely. It should be built on Docker and also provide some basic reporting.

make render of the leader optional

The Namespace Modifier Should Allow for Restof Operator

Currently when applying namespaces to a log via the namespace or ns methods you must pass in an array of strings if you want to apply multiple namespaces. This API could be simplified to allow a restof args operator to collect the multiple namespaces.

// Current API
adze().ns(['namespace-1', 'namespace-2']);

// Proposed API
adze().ns('namespace-1', 'namespace-2');

Write Adze Readme Documentation

Write readme documentation for Adze.

Add Filters Description to Config Docs

The config docs for Adze Configuration show's filters as a config property but doesn't document it in the description table below.

Create Common Usage Example

Under the Adze Concepts page there should be a common usage example to clarify the primary way Adze is meant to be used.

remove bundle feature since it is not very useful

refactor namespace modifier to always use restof operator

Describe TS Compiler Requirements in Installation Docs

• Using Adze with TS requires a couple of properties to be present in the tsconfig and requires a specific version of TS. Specify these in the docs.

Support Meta Data Defaults on Log Instances

Allow the user to specify default meta data on a new Adze instance that is applied to every child log.

URL Param for Env Control

Adze should support a URL param for controlling the logging environment. The param name should be configurable by the user.

Create Listener Function for Writing Logs to File (Machine Readable)

Batteries-Included:
Write a listener function that write machine readable (JSON) logs to a file.

Clarify the bundle() documentation

The bundling concept in the documentation isn't immediately clear how it works. Expound on the documentation for this feature.

Rerender function doesn't work with sealed logs.

The rerender function doesn't accept sealed logs.

const { log: loga, render: log_render } = log().custom("honeybadger", "All of the other animals just eat his scraps.");

const coll = shed.getCollection('*');

filterNamespace(coll, ['foo']).forEach(rerender);

drop support for node 10, 12, 14, and 16 for support of 18+

Create Listener Function for Writing Logs to File (Human Readable)

Batteries-Included:
Write a function for listening to logs and writing the data to a file in a human readable format.

Expose function for getting reference to the GlobalStore instance

create and export type for an Adze factory function

The library should export a type for an Adze factory function so that if an adze factory is being passed as an argument it can be strongly typed with TypeScript.

Colors Not Functioning on Dist

• The library dist file is breaking chalk styles and colors in the terminal.

Enable Filters on Adze Configuration

Currently filtering can only occur with a configured Shed. Adze logs should support filter configuration and as logs are terminated they will self-filter based on the config.

remove lodash cloneDeep in favor of structuredClone

Unbeknownst to me a standard function already exists for creating deep clones of objects named structuredClone. Current implementations of the lodash cloneDeep function should be removed in favor of this. This will improve performance and reduce bundle size.

https://developer.mozilla.org/en-US/docs/Web/API/structuredClone

Test Modifier Documentation Example is Incorrect

The example for the test modifier has incorrect text and comment for the x === y log.

Update the Preview Image

The preview image shows the old "attention" log level that is now replaced by alert. Update the image to reflect the API changes.

Level Filter Documentation Incorrect

The documentation for Level Filter was never updated after copying the documentation block.

Create Docs for Micro-Frontends

• Adze + Shed can be utilized together to enable efficient logging in micro frontend architectures. Write a docs section explaining how it works.

Create Listener Function for Sending Logs to an API Endpoint

Batteries-Included:
Create a listener function that enables the user to configure an API endpoint to send the logs to in JSON format.

Make multiple calls to namespace method additive rather then replacing the previous

The current behavior with the namespace modifier is that multiple calls to it will overwrite the namespaces that are applied to the log rather than adding to them.

adze().ns('foo').ns('bar').log('Testing');

The log generated by this will only have the namespace of "bar." Ideally it would have "foo" + "bar".

Add codecov integration

https://about.codecov.io/

Rename Shed to GlobalStore

Rename Shed to GlobalStore for clarity.