<learning class='always'>...

I love development & the goal is to "hopefully" capture my experiences (right, wrong or somewhere in-between) as I go.

Jun 5, 2013

An Arrow In The Developer's Quiver - traceGL

What is it?

traceGL is one of those tools you'll want to keep handy alongside your debugging and profiling tools. It allows you to capture what is going on in your application (browser or node) and then examine the captured data at your leisure.

It gives you the answer to:

What did my code just do?

It does this by capturing all function calls (you can optionally filter things out) and the data that was passed to it. It highlights the path it took through your code by highlighting it and if it was based on an if statement it will show you which part evaluated to true.

When you have a busy app with a lot happening it can be helpful to run through a scenario, capture what's going on and then go through it at your own pace (or share the trace with someone for a second opinion).

The Setup

To demo it you need the following:

  • Node.js
  • traceGL - This is a commercial tool, but at a reasonable price ($14.99/€12.00). Once you buy it you will be emailed a link which will give you the javascript file you need to run with node.
  • A sample app. I've been looking at angularjs so I picked one of the open source projects they reference on their site: angularjs github contributors

It's a shame there isn't a trial so you can try before you buy (but since you get given the source I understand why) and it still has rough edges (more on that later) but I hope this post at least makes you aware of the tool so that you can decide for yourself if it is worth the gamble.

The Walkthrough

This is assuming you have a working node installation, you have purchased and downloaded the tracegl.js file and have the sample project ready.

traceGL lets you trace a node app, a local web app (hosted by traceGL) and a web app that is hosted by you (e.g. local IIS) but the requests are served through the traceGL proxy. You can also capture and load traces (useful if you wish to attach a trace to an issue).

The walkthrough will go though the sample application and show you the resulting trace from each displayed page (your results might be slightly different but this should give you an idea of what to expect).

traceGL lets you filter out code you don't wish to trace so each screenshot of the app is followed by two traceGL screenshots (the first where everything is traced and the second where we exclude angularjs files).

The last few screenshots give you an example of traceGL's filtering capability and an example of tracing the node web server script included with the sample project.

I've run traceGL on windows 7 and on the Mac. I've based this example on my Mac usage but you should be able to update the examples for windows (only the way you specify paths should need to change).

Some rough edges

Proxy Mode: I've not had much luck with using traceGL as a proxy (even with this sample application it wasn't showing me any trace information. Now this may be just me but I've found the other two approaches to be better).

SSL Support: I've raised a request to support https (I needed it for a specific project). While SSL support has been improved (I raised a GitHub issue) it still required me to edit the js file in order to enable it as you can't do it via the command line (this may have changed by the time you are reading this).

Display: On the odd occasion the trace text looked wrong and I needed to close and re-open the browser/tab and try again (this has been a rare occurrence but I thought it worth a mention).

Starting traceGL

traceGL has the following command line options:

Usage:

node tracegl [flag] target [args]

../path/to/wwwroot Trace browser js via static fileserver
http://proxytarget:port Trace browser js via proxy
nodefile.js [args] Trace Node.js process
trace.gz Play back trace.gz file

-gz[:trace.gz] Record trace to gzip file. No trace UI started
-do[/:]match Only trace filenames containing match. Filters -do set first, then -no
-no[/:]match Ignore filenames containing match. Replace : with / for a regexp, use double escaped \\ 
-nolib Short for -no/jquery.* -no:require.js -no/node\\_modules 
-noup Don't update traceGL automatically
-nocatch Don't create exception catching
-bind:0.0.0.0 Set the hostname to bind our external ports to, default 0.0.0.0
-ui:port Set trace UI port. default: 2000
-tgt:port Set browser JS port. default: 2080

node tracegl.js [commmand]
-settings write a .tracegl settings template in the current dir
-update do an explicit update of traceGL (normally in background) 

To get up and running and trace everything I typed the following:

node /PATH/TO/YOUR/tracegl.js /PATH/TO/THE/SAMPLE/app

To exclude the angularjs files (and reduce the noise so you only see your code executing) I typed the following:

node /PATH/TO/YOUR/tracegl.js -no:angular.js -no:angular-resource.js /PATH/TO/THE/SAMPLE/app

If you also pass in -nolib traceGL will exclude some common libraries such as jquery (but I didn't need that for this example).

You should see the following:

[trace.GL] See your code. This product has a commercial license.
[trace.GL] WebGL trace UI: http://0.0.0.0:2000
[trace.GL] Checking for update...[trace.GL] Serving browser JS: http://0.0.0.0:2080

Loading traceGL and the first view of the sample app

Start Chrome (I've used Chrome because of it's support for WebGL…..and because I like it :)) and go to http://0.0.0.0:2000 / http://localhost:2000 and you should see the following:

traceGL-start

Going to http://0.0.0.0:2080 / http://localhost:2080 should give you the first view of the sample application:

sample-app-view1

Trace with angular:

tracegl-sample-app-view1

Trace excluding angular:

tracegl-sample-app-view1-noangular

I won't go over the code itself as the purpose of the post isn't to cover angular or the sample app but the two views does give you some idea of the amount of work angular does even for the initial view. If you've ever been curious about how angular works under the covers looking through the trace might be of interest. When you mainly want to focus on your own code I recommend excluding things with the options traceGL gives you as it can cut out a lot of noise.

If you look at the screenshots you'll see that traceGL can highlight the path it took, the conditions that passed or failed and how many times a loop was executed if you hover over it.

Navigating the app - view 2: search results

On the first view if you simply search for angular (the default) you'll be taken to this results page. The two traceGL screenshots give you an example of the information that was captured and it also highlights that it can show you the values that were set within or passed to a function.

sample-app-view2

Trace with angular:

tracegl-sample-app-view2

Trace excluding angular:

tracegl-sample-app-view2-noangular

Navigating the app - view 3: Seeing a list of project contributors

By clicking on one of the projects (I selected angular) you'll be taken to a page listing everyone who has contributed to the app. The traces here are just examples of the information captured and it gives you an example of the type of information that can be captured.

sample-app-view3

Trace with angular:

tracegl-sample-app-view3

Trace excluding angular:

tracegl-sample-app-view3-noangular

Navigating the app - view 4: Selecting a contributor

Selecting a contributor will take you to a view that lists all of the projects he has contributed to. The angular trace shows you a list of the values it handled whereas the trace excluding angular lets you focus on the information passed to the controller (which is nice when you want to confirm how you are navigating through your app). If you click on one of the contributor's projects you'll reach the last main view which shows you others who have also contributed to this project. I'm not including the screenshot or traces here as they are very similar to the ones above but I have them on flickr and you should be able to see them if you click on any of the images in this post.

sample-app-view4

Trace with angular:

tracegl-sample-app-view4

Trace excluding angular:

tracegl-sample-app-view4-noangular

Trace overload….looking for something specific

If you have already specified filters before the trace started but there is still too much information captured then filtering is your friend. At the top of traceGL ui you can enter text which will be used filter your captured results.

It can be used to search for a specific function or as the screenshot below shows in some cases it can even find places where a specific value was passed (in the screenshot I search for the name I clicked on in view 3).

tracegl-filtering

That's exactly what I was looking for….now if only I could change it

A nice thing about traceGL is that you can go from traceGL to e.g. Sublime Text 2 by double clicking. This worked out of the box for me on a Mac and opened the file for editing on roughly (it was 1 line out) the line I double clicked on. I haven't tried this feature on Windows but the docs say the following:

Editor integration uses a commandline call to your editor, and uses $file and $line to build up the arguments. Put it in the right platform key (darwin, win32, sunos, linux, freebsd). If you have a configuration thats useful, please consider sharing it in a github issue so it can be turned into a default.

"bin":"/Applications/Sublime Text 2.app/Contents/SharedSupport/bin/subl"
"args":["$file:$line"]

Double clicking on UserCtrl within traceGL opens it in Sublime Text 2:

tracegl-ide-integration

If you are hosting your files with traceGL it will detect any changes and reload the webpage on save.

What about Node.js?

The nice thing about this sample project is that it also has a little web server script which serves as a nice way of demonstrating client and server side tracing with one project. To trace the web server do the following (note if you still have the previous instance of traceGL running you'll need to specify a different port for the traceGL ui):

node /PATH/TO/YOUR/tracegl.js -nolib /PATH/TO/THE/SAMPLE/scripts/web-server.js

Note: The working directory is /PATH/TO/THE/SAMPLE/app

You should see the following:

[trace.GL] See your code. This product has a commercial license.
[trace.GL] WebGL trace UI: http://0.0.0.0:2000
[trace.GL] Checking for update...Http Server running at http://localhost:8000/
up to date.

Fire up chrome and navigate to http://0.0.0.0:2000 / http://localhost:2000 for the traceGL ui and http://localhost:8000/index.html for the sample app (this time served by the web-server.js script). I navigated through the views as described above and captured the resulting screenshot:

tracegl-debug-node

Capturing your trace?

If you've come across a scenario where you wish to capture a trace to attach to an issue (or share with someone else) then you can specify -gz (which will save a trace.gz file)

node /PATH/TO/YOUR/tracegl.js -nolib -gz /PATH/TO/THE/SAMPLE/scripts/web-server.js

Note: The working directory is /PATH/TO/THE/SAMPLE/app

You'll see the following output:

[trace.GL] See your code. This product has a commercial license.
[trace.GL] Checking for update...Http Server running at http://localhost:8000/
up to date. 

You'll notice that no url for the traceGL UI is shown as everything is now recorded to the trace file. It would be nice if you could still view the UI or fire up the UI and then have an export/save option.

Fire up chrome and navigate to http://localhost:8000/index.html, navigate around the application and when you're ready Ctrl + C will cancel traceGL and show you something similar to the following:

^Cgot sigint, flushing gz
end!
exit!

You should see a file called trace.gz in your working directory: /PATH/TO/THE/SAMPLE/app/trace.gz

You can now attach this file to an issue, send it to someone or inspect it using the traceGL UI. To do the latter execute the following command:

node /PATH/TO/YOUR/tracegl.js /PATH/TO/THE/SAMPLE/app/trace.gz

Note: if the working directory is the app directory you can just specify trace.gz

You should see the following:

[trace.GL] See your code. This product has a commercial license.
[trace.GL] WebGL trace UI: http://0.0.0.0:2000
[trace.GL] Checking for update...Loading gzipped trace .Complete!
up to date.

Firing up chrome and navigating to http://localhost:2000 will show you your trace results.

Note: When I navigated to the traceGL ui it didn't load and I needed to reload it (the UI presents you with a reload button when WebGL fails) to get it to work.

Wrap up

I was going to do a screencast but there are already two screencasts covering traceGL that are worth a watch:

There are times when I don't feel like watching a video and just feel like reading some text and seeing some images (so this post is for times like that). The i

Apr 4, 2013

AngularJs - Where To Start?

AngularJs seems to be getting a lot more tweets, posts and samples lately so I thought it might be useful to record the resources I looked at when considering whether or not to invest time in Angular.

Where did I start?

Now sometimes I just jump into something and try building something and learn as I go. I didn't do this with AngularJs for the following reasons:

  • It is a framework more than just a library that does a specific thing so I wanted an idea of what it had to offer before jumping in
  • In my initial search I saw multiple statements along the lines of "long learning curve", "the angular way" etc
  • I quite like KnockoutJs and was thinking about investing time learning Durandal (although the learning curve for Durandal would be a lot less as Knockout forms a part of it. If you use Knockout or if you haven't heard of Durandal it's worth a look). I might do a similar post for Durandal when I get round to investing more time in it but as I've done a fair bit of Knockout I wanted to try something different.

I initially went where I guess everyone does:

The site has documentation and live examples to give you an idea of what it can do. It also shows examples of apps built with Angular (there are some open source ones so you can have a look at how it was put together) and links to the google groups etc.

After that I watched a few videos, read some posts, looked at samples, read a small book and watched twitter for any interesting discussions/links about Angular.

If I was to suggest just one link what would it be?

So you've heard about angular, checked out the main site and want more…..stop searching and go straight to egghead.io This is a site created by John Lindquist @johnlindquist that contains (at this current time) 39 short videos covering a specific part of Angular. You can quickly go through them to get a general idea about Angular and go back to specific videos when you need to double check something.

John also works on the AngularJs plugin for WebStorm which you may want to check out.

Videos to watch

I've already mentioned egghead.io but here are some additional ones I've come across:

  • http://www.youtube.com/user/angularjs - This is the youtube channel for Angular and contains a wide range of videos (so not a specific recommendation although the best practices, binding and directive ones seem good)
  • http://tekpub.com/productions/angular The tekpub videos are well done and still being produced (currently it is up to episode 5 as I write this. I'm up to episode 4. Overall I still prefer egghead.io but for $15 it is worth it (in my opinion) and if you already have a a subscription then you've already paid for it…go there now :) )
  • I believe someone is currently working on an AngularJs course for http://pluralsight.com/ I think it may be Dan Wahlin who has done a number of JavaScript related courses for them
  • codeschool.com currently aren't doing a course for Angular (I really like the way they do their courses and they offer some for free so if you've never done any it is worth checking out). They do have a video in their code tv section http://www.codeschool.com/code_tv/angularjs-part-1 (I haven't seen it as I no longer have a subscription but if you have one it may be worth watching)
  • Dan Wahlin has recently (April 13th 2013) released a 60 minute (slightly over) video covering Angular. It covers a fair bit (except directives apart from a mention) and gives you a good idea of what Angular is capable of. It can be found here: AngularJS Fundamentals in 60-ish Minutes

Books to read

There are only a few Angular specific books out there but this will likely change as the the framework gets more popular:

  • Instant AngularJS Starter - I liked that it was a quick read (I wasn't looking to read a big book at this stage), and it built an application (I didn't try and go through the code samples…there were some reports of a few issues but I think these are being resolved and the code sample updated). It seems to have got mixed reviews on amazon but I enjoyed it as a quick introduction.
  • AngularJs - I've not read this book so I don't have an opinion on it but it is due out in April
  • Recipes with angular - I've not read this one but thought I'd list it for completeness.
  • AngularJs in Action - This one is currently being worked on although you can get early access. I'll likely get this one.

Tools to help when you do start developing

Here are a few tools which you my fine helpful when you start coding away with Angular:

  • Yeoman - Yeoman combines yo (scaffolds out a new application), bower (dependency management) and grunt (build tool with a fair number of plugins) to help you get up and running quickly. Only used it on the Mac and it took a little bit of fiddling to get started but I like the live reload capability and the watch/build & deploy feature (you could do this with grunt on it's own but yeoman gives you an initial starting point).
  • Batarang - If you are building an AngularJs app Batarang is a Chrome plugin that lets you inspect your app (showing you your scopes and performance implications of approach etc)
  • ngmin - ngmin will help you prepare your code for minification (ngmin is an AngularJS application pre-minifier. The goal is ultimately to use this alongside yeoman and grunt to make developing and building Angular apps fast, easy, and fun.). A good example of why you may need this is highlighted in an odetocode.com post: AngularJS - Controllers, Dependencies, and Minification
  • If you use Webstorm then there is a plugin for Angular created by @johnlindquist (which I mentioned earlier)
  • If you use Visual Studio and have resharper then this may interest you https://github.com/JetBrains/resharper-angularjs
  • Karma - The AngularJs test runner (previously called Testacular)

Libraries/Extensions for Angular

  • AngularUI - A number of additional directives and filters that you can add to your project
  • Angular Bootstrap - By the same team as AngularUI. This adds twitter bootstrap support but instead of using the javascript that comes with bootstrap they have directives that aim to do the same but are done in an angular way. If you are a foundation fan then it looks like they have plans to add support for that too but it is still early days: https://github.com/angular-ui/bootstrap/issues/260.
  • ng-grid - a grid directive with examples.
  • ui-router - a new addition (as of March 2013) with the following goal: To evolve the concept of an Angular "Route" into a more general concept of a "State" for managing coarse application UI states
  • There is a website where you can add/find additional modules for your app which you may find useful: http://ngmodules.org/
  • If you use Kendo UI (from Telerik) then there is support for Angular which can be found here http://kendo-labs.github.com/angular-kendo/
  • If you are looking to tie in Angular with a backend datasource (especially if you are using .NET and the Entity Framework) then you may want to check out Breeze : Video and site: http://www.breezejs.com/samples/todo-angular

Where to go for help

I guess the three main places would be:

Source code examples?

  • The Angular site does list a fair number of sites/apps built with Angular (and you can filter to show open source ones as well): http://builtwith.angularjs.org/
  • TodoMvc has an Angular Todo app written in JavaScript & in TypeScript. It also has a todo app using a large number of other frameworks to give you an easy way of comparing Angular against some of the other options out there.
  • TypeScript AngularJs TradeZone Sample - An example showing typescript, angular and a bit of rxjs in action. The project is in VS2012 format.

Blog Posts/Articles etc

Now there are quite a few out there so I'm only going to list a few which contain a fair bit of content or show Angular being used in non typical ways (phonegap, win8 etc).