Fondue documentation

You can follow along and play with Fondue in your browser using The Fondue playground.

What's fondue?

Fondue is a real-time program tracing library for JavaScript. You use it if you want to:

• Visualize the function calls in a program
• Get a graph of all the files and functions that are defined in a program

Get the code with git clone https://github.com/adobe-research/fondue.git or use it in your Node.js project with npm install fondue.

How to trace some code

Call require('fondue').instrument(src, options). You pass it the JavaScript code you want to trace as a string, and it returns the same code, but modified so that if you run it, it will store trace data in a global object called __tracer.

Example: a script that inspects itself

Fondue comes with a script bin/fondue that calls instrument(src, { path: ... }) for you automatically. Try saving the following code as example01.js:

// example01.js

var nodesHandle = __tracer.trackNodes();
__tracer.newNodes(nodesHandle).forEach(printNode);

function printNode(node) {
	if (node.type === 'function') {
		console.log('found a function: ' + node.name + ' at ' + node.path + ':' + node.start.line + ' with id ' + node.id);
	}
}

Then execute the following commands:

1. ./fondue/bin/fondue example01.js > example01.fondue.js
2. node example01.fondue.js

It should print out something like this:

found a function: [log] at [built-in]:0 with id log
found a function: printNode at /Users/tom/src/example01.js:6 with id /Users/tom/src/example01.js-function-6-0-10-1

(log is a special function representing console.log. You can ignore it in your scripts if you want.)

If you add more functions to example01.js and re-run the commands, you should see that it prints out all the functions you add.

Example: a script that inspects another script

You can find basically the same example in the Fondue playground. Just hit "Run". You might find it easier to experiment there than on the command-line.

How to access the data (Fondue's API)

__tracer uses a polling data model. As you saw in the example, to get all nodes, first you call trackNodes() to get a handle object, then you call newNodes(handle) to get all the nodes that have been instrumented since the last call to newNodes.

As another example, trackHits() gives you a handle for tracking the hit counts of all functions. hitCountDeltas(handle) gives you an object containing the counts of all function calls that occurred since the last call to hitCountDeltas(handle) for that handle:

var hitsHandle = __tracer.trackHits();
var hits1 = __tracer.hitCountDeltas(hitsHandle); // { 'func-id-1' : 1, 'func-id-2' : 3 }
var hits2 = __tracer.hitCountDeltas(hitsHandle); // {}
var hits3 = __tracer.hitCountDeltas(hitsHandle); // {}
var hits4 = __tracer.hitCountDeltas(hitsHandle); // { 'func-id-2' : 1 }
var hits5 = __tracer.hitCountDeltas(hitsHandle); // {}
// ...

API Reference

I apologize for inconsistencies. The only consumer of this API until recently was my own project, Theseus.

Fondue's API

__tracer API

Fondue-instrumented code creates a global __tracer object that you can also access to get information about that code's execution.

function foo() {
	setTimeout(function bar() { /* ... */ });
}

Getting fancy (tracing whole programs, whole web sites, etc)