Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add logging functions #20

Merged
merged 2 commits into from
Aug 19, 2022
Merged

Add logging functions #20

merged 2 commits into from
Aug 19, 2022

Conversation

mcmire
Copy link
Contributor

@mcmire mcmire commented Aug 17, 2022

For context behind this change: In order to write tests for the provider API that the extension exposes (MetaMask/metamask-extension#15556) I've found adding logging to the various libraries that the network layer uses to be useful. After discussing this with @Gudahtt we determined that it might be nice to have a unified logging solution across all of our libraries.


This commit introduces logging via the debug library. One key feature
of this library is that it allows you to assign a label to log messages.
All log messages are suppressed and will not be shown by default, but
the label you choose can be namespaced, and you can use these namespaces
to selectively show the log messages you're interested in.

With that in mind this commit defines at least two logging namespaces: a
global metamask namespace for all projects that need logging and a
project-level namespace.

The way it works is this. Say your project is called
eth-block-tracker. To add logging to your project, you'd add a file
(call it logging-utils.ts) which contains:

import { createProjectLogger } from "@metamask/utils";

export const projectLogger = createProjectLogger("eth-block-tracker");

You could either use projectLogger anywhere in your project like this:

import { projectLogger as log } from "./logging-utils";

log("This is a log message");

Then you could run your tests, or whatever command you want to run, by
setting the DEBUG environment variable like this:

DEBUG=metamask:eth-block-tracker <command goes here>

And in the output you'd see something like:

metamask:eth-block-tracker This is a log message +0ms

However if you wanted to namespace your log messages further — say you
wanted to only show log messages for a polling-block-tracker.ts file —
you could update logging-utils.ts like this:

import { createProjectLogger, createModuleLogger } from "@metamask/utils";

export const projectLogger = createProjectLogger("eth-block-tracker");

export { createModuleLogger };

Then add the following to polling-block-tracker.ts:

import { projectLogger, createModuleLogger } from "./logging-utils";

const log = createModuleLogger(projectLogger, "polling-block-tracker");

log("This is a log message");

Now you could run your command with:

DEBUG=metamask:eth-block-tracker:polling-block-tracker <command goes here>

or, for all eth-block-tracker log messages:

DEBUG=metamask:eth-block-tracker:* <command goes here>

And in the output you'd see something like:

metamask:eth-block-tracker:polling-block-message This is a log message +0ms

Finally if you wanted to show all log messages across all MetaMask
projects that are also making use of this logging mechanism, you could
say:

DEBUG=metamask:* <command goes here>

@mcmire mcmire requested a review from a team as a code owner August 17, 2022 22:21
* @returns An instance of `debug`.
*/
export function createProjectLogger(projectName: string): Debugger {
return globalLogger.extend(projectName);
Copy link
Contributor Author

@mcmire mcmire Aug 17, 2022

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm choosing to wrap debug in case we want to swap this out for something else in the future. UPDATE: Well, I guess the interface of the object that this functions returns will probably change if we do go with a different library, but hopefully we won't have to change this name.

@mcmire mcmire force-pushed the add-logging branch 2 times, most recently from bf4b91c to beb1e1a Compare August 17, 2022 23:01
This commit introduces logging via the `debug` library. One key feature
of this library is that it allows you to assign a label to log messages.
All log messages are suppressed and will not be shown by default, but
the label you choose can be namespaced, and you can use these namespaces
to selectively show the log messages you're interested in.

With that in mind this commit defines at least two logging namespaces: a
global `metamask` namespace for all projects that need logging and a
project-level namespace.

The way it works is this. Say your project is called
`eth-block-tracker`. To add logging to your project, you'd add a file
(call it `logging-utils.ts`) which contains:

    import { createProjectLogger } from "@metamask/utils";

    export const projectLogger = createProjectLogger("eth-block-tracker");

You could either use `projectLogger` anywhere in your project like this:

    import { projectLogger as log } from "./logging-utils";

    log("This is a log message");

Then you could run your tests, or whatever command you want to run, by
setting the `DEBUG` environment variable like this:

    DEBUG=metamask:eth-block-tracker <command goes here>

And in the output you'd see something like:

    metamask:eth-block-tracker This is a log message +0ms

However if you wanted to namespace your log messages further — say you
wanted to only show log messages for a `polling-block-tracker.ts` file —
you could update `logging-utils.ts` like this:

    import { createProjectLogger, createModuleLogger } from "@metamask/utils";

    export const projectLogger = createProjectLogger("eth-block-tracker");

    export { createModuleLogger };

Then add the following to `polling-block-tracker.ts`:

    import { projectLogger, createModuleLogger } from "./logging-utils";

    const log = createModuleLogger(projectLogger, "polling-block-tracker");

    log("This is a log message");

Now you could run your command with:

    DEBUG=metamask:eth-block-tracker:polling-block-tracker <command goes here>

or, for all `eth-block-tracker` log messages:

    DEBUG=metamask:eth-block-tracker:* <command goes here>

And in the output you'd see something like:

    metamask:eth-block-tracker:polling-block-message This is a log message +0ms

Finally if you wanted to show all log messages across all MetaMask
projects that are also making use of this logging mechanism, you could
say:

    DEBUG=metamask:* <command goes here>
"prettier": "^2.2.1",
"prettier-plugin-packagejson": "^2.2.11",
"rimraf": "^3.0.2",
"ts-jest": "^26.3.0",
"stdio-mock": "^1.2.0",
"ts-jest": "^28.0.8",
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Getting this peer dependency warning:

warning " > ts-jest@28.0.8" has incorrect peer dependency "typescript@>=4.3".

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I fixed this by bumping TypeScript: #21

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is merged now.

Copy link
Member

@Gudahtt Gudahtt left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Looks great! I can approve it after the peer dependency warning is resolved

@mcmire
Copy link
Contributor Author

mcmire commented Aug 18, 2022

Ready for review again.

Copy link
Member

@Gudahtt Gudahtt left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

LGTM!

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

2 participants