massive-oss / mconsole

A cross platform Haxe implementation of the WebKit console API supporting logging, debugging and profiling. Currently supports AVM2, JavaScript and Neko.

Console provides a consistent cross platform logging and debugging API. The API is consistent with that of the WebKit console. Developers can:

• redirect calls to "trace" to the console
• log messages at different levels
• print stack traces
• inspect structured objects in the WebKit console
• log multiple values in a single trace
• make assertions that trigger errors when they fail
• count invocations at positions within their code
• visually group log messages
• use timers to measure program performance
• start and stop profiling where available
• log Haxe objects in way that is easily inspectable in the WebKit console
• insert breakpoints (on supported platforms)

Console currently supports a number compile time modes:

• On system platforms (neko/php/cpp/nodejs) console prints to stdout, colorising output
• In JS/Flash running in WebKit browser console prints to WebKit console
• In JS running in non-webkit browser console prints to an element in the DOM
• In Flash running standalone or in a non-WebKit browser console prints to an on screen logging panel.
• When the compiler flag no_console is set, the console inlines null expressions, removing any runtime overhead from logging.

Example Usage:

You can download an example of mconsole usage here.

To enable the console, call:

Console.start();

To log a message at a named level:

trace("log", "Something happened.");
trace("info", "Something interesting happened.");
trace("debug", "WHY WON'T YOU WORK!!");
trace("warn", "I didn't test this code at all...");
trace("error", "Something bad happened.");

Messages default to LogLevel.log:

trace("Logtastic");

Log multiple values using trace. In WebKit console each value is inspectable (rather than concatenating as a string)

trace("string", 10, {key:"value"});

You can also call the logging API directly:

Console.log("better than bad, it's good!");

Errors will print a message, then a stack trace:

Console.error("Epic fail");

Outputs:

Error: Epic fail
@ SomeClass.someMethod:20
@ SomeOtherClass.someOtherMethod:48

You can also use Console.trace to print a stack trace without triggering an error:

Console.trace();

Outputs:

Stack trace:
@ SomeClass.someMethod:20
@ SomeOtherClass.someOtherMethod:48

Assertion will print a message and stack trace, then throw and exception when the condition is false:

Console.assert(foo == false, "foo is not false!!");

Outputs:

Assertion failed: foo is not false
@ SomeClass.someMethod:20
@ SomeOtherClass.someOtherMethod:48

To count the number of times a line of code is invoked:

function someCode()
{
	Console.count("apples");
}

someCode();
someCode();

Outputs:

apples: 1
apples: 2

Note that counters are identified by their position, not their label:

Console.count("apples");
Console.count("apples");

Outputs

apples: 1
apples: 1

To insert a breakpoint in JavaScript or Flash:

Console.enterDebugger();

Group log messages together visually:

Console.group("Group");
Console.log("grouped log");
Console.group("Nested group");
Console.warn("nested warn");
Console.groupEnd();
Console.groupEnd();

Output:

Group
  grouped log
  Nested Group
    nested warn

Timers can be used to quickly monitor runtime performance:

Console.time("munging");
for (i in 0...4200000000) munge();
Console.timeEnd("munging");

Output:

munging: 2410ms

JavaScript/Webkit only

The WebKit profiler can be started and stopped:

Console.profile("performance");
var f = function(x) { return x * x; }
var x = f(10);
Console.profileEnd("performance");

And markers added to the WebKit timeline view:

Console.markTimeline("finished");

Type conversion

As the WebKit console has user friendly structure inspection, console will try to convert native Haxe values into something inspectable where possible:

// inspectable XML dom
Console.log(Xml.parse("<this><is><some><xml/><with/><elements/></some></is></this>"));

// enums and enums with parameters
Console.log(value1);
Console.log(value2(33));
Console.log(value3({oooh:"fancy"}));

// mapes
var map = new StringMap<String>();
map.set("mapy", "goodness");
Console.log(map);

var intMap = new IntMap<String>();
intMap.set(10, "int mapy goodness");
Console.log(intMap);

// and iterable objects in general
var list = new List<String>();
list.add("support for iterables in general");
list.add("also good");
Console.log(list);

Printer

Printing is implemented by a mconsole.Printer. Custom printers can be used:

Console.addPrinter(new MyConsolePrinter());

A default printer is always created. This is a ConsoleView for JavaScript and Flash, or a FilePrinter for system targets.

To implement a custom printer:

/**
A ConsolePrinter that raises an alert for each log message.
*/
class AlertConsolePrinter implements mconsole.Printer
{
	public function print(level:mconsole.LogLevel, params:Array<Dynamic>, indent:Int, pos:PosInfos):Void
	{
		js.Lib.alert(Std.string(level) + "@" + pos.className + "." + pos.methodName + ":" + params.join(", "));
	}
}

Caveats

When logging to the WebKit console (JavaScript in a WebKit browser) redirected traces will not display the correct source position in the console panel. The position of the Console.haxeTrace will be shown instead. This is a limitation of the Haxe logging API.

Flash targets can talk to the WebKit console over external interface, but messages will not show the correct position. Use a ConsoleView if you require log positions.

mconsole's Issues

Firefox - hangs browser if console not enabled in firebug

Looks like the detectWebKit function needs to be wrapped in a try catch

DefaultPrinter for WebWorkers

The JavaScript DefaultPrinter ConsoleView tries to create a pre-element. This fails if your JavaScript gets executed within a WebWorker.

The ConsoleView should check if Browser.document is null. If it's null it should use some postMessage mechanism to push the log message to the main Browser context. Similar to the mechanism used by the flash target.

MConsole throws exception if browser does not support Function.prototype.bind

For browsers that support console, but not Function.bind, any logging will cause exception.

in Console.callConsole()

Solution - include a polyfill like:
https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function/bind

DefaultPrinter for Javascript

The default printer for JS targets (ConsoleView) leaks memory in the background (Tested in the latest Chrome, Firefox and Safari) (Interestingly IE 11 seems to be unaffected).

Basically the ConsoleView creates (but does not add to the document) DOM elements for all logged messages regardless of weather the printer has been "attached" and visible on screen. Because the printer is added to the Console by default, but not attached, it silently logs and creates DOM elements to the point of causing memory issues.

Because it creates DOM elements the chrome debugger doesn't show it as a javascript memory leak(!) (But pressing shift-escape and viewing the chrome task manager (or even the using your system task manager) will show the issue).

To fix the issue, it is as simple as "Console.removePrinter(Console.defaultPrinter)" but I'm still raising the issue as this issue is present by default and so will cause memory leaks by default

mconsole fails when using html5 target and NME

The mconsole version available via Haxelib (1.1.1) does not work for me in Firefox. It throws the error TypeError: $it2.hasNext is not a function. It seems this is due to the faulty isWebKit detection method in that version.

So I cloned the latest and ran haxelib dev mconsole path/to/mconsole/src to use the latest version.

It errors with mconsole/src/mconsole/Console.hx:174: characters 3-24 mconsole.LogPrinter has no field attach.

I've removed these lines for now to get it working.

Only console.log supported in phantomjs

While phantomjs supports console.log, it does not yet support any of the other variations, i.e.

console.warn
console.error
console.info
....

ariya/phantomjs#10232

This causes a runtime exception when logging.

We'll need to probably check 1) we're in a browser and 2) the user agent to see if it's phantom then only output to console.log. Or we can do a check for console.<method> to see if it exists and fallback to log if not.

I.E 9 and Firefox break

When using Console.warn(<some string>) the IE and Firefox both crash (Infact, using any of the logging features causes the same isssue)

It seems that the root cause for the problem is the mconsole.Console.isWebKit check (which returns true in these browsers) causing console.warn.apply(console,mconsole.Console.toWebKitValues([message])) to be executed.

In IE this fails with: Object doesn't support property or method 'apply'
In firefox that line executes fine, but then fails in mconsole.Console.toWebKitValue as the string I'm logging is cast to an iterable - This fails, causing an error.

Console.assert throws null Function Pointer on CPP if message is not a string

E.g.

Console.assert(false, new FooException("something happened"));

Looks like it is related to the line:

print(LogLevel.error, ["Assertion failed: " + message + "\n" + stack], pos);

Haxe 3.0, Hxcpp 3.02

IE8 not supported

Finding a number of runtime errors when using mconsole under ie8. The first one was related to Function.prototype.bind throwing a null pointer exception as bind is not defined. https://github.com/massiveinteractive/mconsole/blob/master/src/mconsole/Console.hx#L509

mconsole fails with neko as target

When I use neko as target the application compiles fine, but after running I get the following error message:

Called from mconsole.PrinterBase::print line 109
Called from mconsole.FilePrinter::printLine line 141
Uncaught exception - Invalid call

To fix this error I had to cast the output variable to a propper class.
The following snippet fixed the error.

#if neko
cast( output, Output ).writeString( line + "\n" );
#else
output.writeString(line + "\n");
#end