Using Advanced Telemetry with Monocle

Project Monocle (codename) is an upcoming tool from Adobe to profile ActionScript 3 (Flash Player and AIR) applications on both desktop and mobile. It provides an amazing level of insight into just about all aspecs of an application across time. If you would like a general overview of its capabilities, here is a nice video.

Monocle has been in private beta for some time now, and was recently made available much more widely through a public beta program:


Note that even though the beta is now public, I believe many things are still restricted to the NDA agreement of the prerelease program, so I will not be getting into any specifics in this article about Monocle usage itself. Basically, so long as Monocle is running on your system, any SWF with advanced telemetry enabled will be able to be profiled within the application when it is run from a website, development environment, mobile device, or whatever.

Using Flash Builder 4.7

The easiest way to get going with Monocle is to use the beta 2 of Flash Builder 4.7 to enable telemetry and compile your projects. The process is super easy as there is a little checkbok (Enable detailed telemetry) in the ActionScript Compiler section of the project properties dialog which allows you to easily turn this feature on and off.

There are a few things to note in regard to this, however. This option is only available on pure ActionScript projects since at this time, only pure AS3 projects can be compiled using ASC2.0 – which is the compiler FB4.7 uses to compile AS3 projects and insert the telemetry features into the compiled app. As a result, you cannot use this with Flex projects with Flash Builder (yet, anyway).

Once telemetry has been enabled for a project, the next step would be to run the Monocle application so that it is listening for telemetry data. Starting a capable SWF (using Flash Player 11.4 or AIR 3.4 and above) will trigger a new Monocle profiling session.

In the above example, I’m using a simple Hallowe’en themed Away3D AS3 project in FB4.7 with advanced telemetry enabled in order to test out Monocle. Since Monocle has some rather special Stage3D profiling features, this will enable me to profile the full range of available options provided by the application.

Switching over to Monocle, we can see that all of the data for this session has been collected in gorgeous detail. One of the things that is really impressive with the project is that all of this data is interactive – even the Stage3D bits!

Using Flash Professional

If using older Flash Player and AIR projects in Monocle, we have an alternative to re-compiling everything through FB4.7 – we can even use this method along with Flash Professional CS6! This method takes a previously compiled SWF and runs it against a small Python script to shuffle the bits around and enable telemetry.

NOTE THAT THIS METHOD IS NOT A FINAL SOLUTION BUT SIMPLY WHAT WE MUST USE AT THIS PRESENT TIME IF NOT COMPILING WITH FB4.7

The first thing we need to do is get Python installed on the system we’ll be working with. I’m using a Windows 7 machine so downloaded the .msi installer which provided an option to add Python to my PATH options. Very convenient.

After installation, we can then open up a command prompt and run the script (add-advanced-telemetry.py) that comes bundled with the Monocle package, feeding in the SWF we wish to enable telemetry on as an argument. Again, this isn’t the best way to enable telemetry… but with some trial and error – it is workable.

17 thoughts on “Using Advanced Telemetry with Monocle”

  1. Thank you for this write up. One thing I did notice about using Python was that the script runs fine with Python2x and not 3x. Too many hiccups in 3x to resolve. Just thought I should add.

    And of course, Monocle rocks!

    @tah_med

  2. More shyte from adobe.. see below..

    :\Python33>add-advanced-telemetry.py projectX.swf
    File “C:\Python33\add-advanced-telemetry.py”, line 98
    print(“\nIf PASSWORD is provided, then a password will be r
    vanced telemetry in Monocle.”)
    Error: inconsistent use of tabs and spaces in indentation

    1. Version 3.x doesn’t seem to work for most people so be sure you are using 2.x – that doesn’t seem to be the only variable though.

      Cannot emphasis enough that the Python script is a temporary way to do this. Not Adobe’s final solution.

      1. Right it works like this with the python route:

        use python 2.x,

        Run [python add-advanced-telemetry.py yourproject.swf]

        If like me you are crap with paths, stick all 3 files ‘python.exe’ the script and the swf in the one locationand run the command from CMD in the run menu in win 7.

        If successful the filesize of the SWF should have increased a good bit.

        Run monocle.

        I then ran my swf with iexplore for success as I found nothing happened when i ran it standalone.

  3. I am having trouble enabling telemetry on my swf file…. when i run the python script on my file i get following error

    add-advanced-telemetry.py”, line 135, in
    assert(rh != “”)
    AssertionError
    I am using python 2.7.3

  4. So, is it possible to enable telemetry on Flex projects using the Python workaround? That seems to be subtly implied above but I want to make sure before I spend a bunch of time trying to get it to work. Thanks!

  5. I was wondering if anyone had the Python script handy? I downloaded the newest Prerelease of Scout / ProjectMoncole — Build 11/15/2012 (Drop 8) — and the DMG doesn’t seem to include the Python script. I’ve got a Flex project I’m working that I’d love to test with Scout.

  6. Is it possible to use to script to enable telemetry on an iOS AIR app (ipa) that has been created through Flash Pro CS6?

Leave a Reply to Joseph Labrecque Cancel Reply

Your email address will not be published. Required fields are marked *