#logging #wasm32-unknown-unknown #wasm-pack #js

clg

A logger specifically designed for wasm32-unknown-unknown

4 releases

0.0.3 Jun 9, 2024
0.0.2 Jun 9, 2024
0.0.1 Jun 9, 2024
0.0.0 Jun 9, 2024

#143 in WebAssembly

Apache-2.0

19KB
232 lines

clg

A logger specifically designed for wasm32-unknown-unknown.

crates.io

Documentation Apache-2 licensed

Languages/語言 ID
English en-Latn-US
中文 zh-Hans-CN

Q&A

Q: What is this used for?

A: Output logs to the Web/Node.js/Deno console in Rust.

Screenshot_2024-06-09__09-54-09 Screenshot_2024-06-09__06-23-49

Q: Why not use the standard library directly?

A: For wasm32-wasi, we can directly use Rust std's eprintln, as well as the regular logger.

However, for wasm32-unknown-unknown, we need to call the web console, that is, call js's console.log() and console.error() functions.

Q: How to use it?

A:

  • If a logger has already been configured, use the log macro:
    • For example, warn!("{warn_1} {warn_2}"), debug!("{dbg_1} {dbg_2}")
    • After calling log::debug!("This is a debug message"), the output content is similar to 06:23:16:223 [DEBUG] clg::test_wasm:186 This is a debug message

log macro:

  • log::error!()
  • log::warn!()
  • log::info!()
  • log::debug!()
  • log::trace!()
  • If a logger is not configured, use the clg macro:
    • For example, clg!("{message_1}")
    • When calling the clg macro, it will not include additional log information, nor will it automatically determine the log-level.
    • Since some browsers do not support console.debug(), there is no c_dbg!()

Calling c_err!("{msg1} {msg2}") in Rust is equivalent to calling the following in JavaScript:

console.error(`${msg1} ${msg2}`)

clg macro:

  • clg::clg!() => console.log()
  • clg::c_err!() => console.error()
  • clg::c_warn!() => console.warn()
  • clg::c_info!() => console.info()
  • clg::c_trace!() => console.trace()

For more usage instructions, see below.

Usage

Step1. Install wasm-pack

cargo install cargo-binstall
cargo binstall wasm-pack

Step2. Add Deps

Cargo.toml:

[lib]
crate-type = ["cdylib"]

[dependencies]
wasm-bindgen = "0.2.92"
log = { version = "0.4.21", features = ["std"] }
clg = "0.0.2"
# js-sys = "0.3.69"
# web-sys = "0.3.69"

Step3. Configure Logger

Let's first introduce what a log level is.

From low to high, they are:

  • Off (No Log)
  • Error
  • Warn (Warning)
  • Info (Information)
  • Debug
  • Trace

The higher the level, the more detailed the printed content.

A lower level cannot display messages of a higher level.

Assume the current level is warn, and the following code exists:

use log::{debug, error, warn};
let id = "div_2";
debug!("Getting DOM element, id: {id}");
let Some(element) = document.get_element_by_id(id) else {
    warn!("Cannot get element");
    error!("An error occurred");
    return;
};

Assume debug = 3, warn = 2, error = 1

Since debug(3) > warn(2) > error(1)

When level = warn(2), only warn(2) and error(1) can be displayed, debug(3) logs will not be displayed.

That is to say, the above code will not output "Getting DOM element...".

Configuring in Rust

You can configure the Log Level in Rust, as well as in js.

src/lib.rs:

use clg::{log_level::LogLevel, ConsoleLogger};
use wasm_bindgen::prelude::wasm_bindgen;

#[wasm_bindgen(js_name = initLogger)]
pub fn init_logger() {
    ConsoleLogger::init(Some(LogLevel::Debug));
}

Compile and package:

# You can change nodejs to deno, and finally use deno to execute
wasm-pack build --release --target nodejs --out-dir pkg --out-name wasm

js/index.cjs:

// index.mjs: import * as wasm from "../pkg/wasm.js";
const wasm = require("../pkg/wasm.js");

const _init = wasm.initLogger();
wasm._clg_testLogger();

Finally, run index.cjs with nodejs:

node js/index.cjs

Configuring in JS

Note: The logger is global. Each thread can only run one logger, do not initialize the logger multiple times. Once the logger is initialized, you can directly use the log macro elsewhere (inside Rust functions).

src/lib.rs:

#[allow(unused_imports)]
use clg::ConsoleLogger as _;

js/index.cjs:

const wasm = require("../pkg/wasm.js");

// const lv = wasm._clg_LogLevel.Warn;
const lv = wasm._clg_newLogLevel("debug");
const _init = new wasm._clg_ConsoleLogger(lv);

wasm._clg_testLogger();

Run:

node js/index.cjs

Dependencies

~7–10MB
~186K SLoC