Augury Labs

Augury Labs is a project that provides developers with experimental tools and an instrumentation
framework used to profile, inspect and troubleshoot Angular applications.

About

Augury Labs is a new instrumentation & inspection framework for Angular
applications that allows for easy installation of specialized developer tools. We have recently
released the Performance Profiler Plugin, which can help you tune the performance of your
applications by providing insights into the following:

• Details of Angular change detection & instability periods
• When zone.js tasks occur and what triggered them
• Component tree details for each instability period (structure, added, removed, etc.)
• When and how long change detection took with a breakdown for individual components
• A detailed timeline to illustrate and explore correlations

After installing and configuring the npm packages, you can run
your app while augury-labs collects raw data about the runtime characteristics of your application.
This raw data is then processed into more meaningful information that you can explore to gain
valuable insights into your applications runtime behaviour.

In the spirit of the Augury DevTool Extension we set out to
help Angular developers better understand how their applications are running and provide insights
into how they can make them better. Augury labs is a culmination of these idea and distrubted as a
set of npm packages & plugin system. We hope you find it useful!

For more information about how this works, please read the architecture
guide.

NOTE: This tool is still experimental. Feedback is greatly appreciated 😄

Packages

• @augury/core - The main package responsible for
  collecting raw data and communicating with registered plugins. Also contains the core bootstrap
  procedure that injects the instrumentation code into your application.
• @augury/performance-profiler-plugin -
  Opens a popup window dashboard, displaying the execution of your app as a timeline graph,
  showing the interaction between Zone.js tasks, Angular’s stability cycles & change detection.

Installation

To setup augury-labs in your application you have two alternatives.

NOTE: The following assumes your application is a standard Angular CLI setup.

Using the Angular CLI ng add command will install the correct dependencies, perform the necessary configuration and execute initialization code.

ng add @augury/schematics

DISCLAIMER: This assumes your application are using the Angular Devkit 6+

To setup and install Augury manually, follow the manual installation.

Guides

• How to Use
• Architecture
• Development Guide
• Manual Installation

Examples

• Augury Examples
• RealWorld example app with Augury

Other Experiments

Here are some other unpublished experimental plugins:

• Unit Tester - Proof of concept which allows programmatic access
  to @augury/core to be used in e2e tests. This could be used to check for acceptable
  thresholds of runtime behaviour in specific areas of your application.

Have other ideas? See our CONTRIBUTING guide.

Troubleshooting

If your having trouble running augury-labs, please submit a GitHub Issue.

Known Issues

• Lazy loaded modules cannot currently be instrumented due to how augury-labs wraps the Angular
  boostrap process. See GitHub Issue.

• Large component trees can cause some performance issues. We are looking into ways to mitigate
  this. You can use the start & pause recording buttons on the specific areas you would like to
  profile. This will help reduce the performance impact to shorter profiling periods.

• Because the bootstrap code in this main.augury.ts file is different from Angular’s bootstrap
  code you may need to tell the Angular CLI builder where is the main module of your application,
  adding a "entryModule": "./app/app.module#AppModule" to the "angularCompilerOptions" object
  of your application’s tsconfig.json file. Replace the path and name of the module if you
  changed it from the defaults.

Contributing

We’d love to have your helping hand on augury-labs! See CONTRIBUTING.md for
more information on what we’re looking for and how to get started.

License

Augury Labs is open source software licensed as MIT.