Profiling Annotations

Disclaimer: Before using Profiling, protect your application and verify that performance is an issue (if it isn't, then there is no reason to profile the application).

Using profiling in the Automatic mode, provides a quick way of evaluating the suggested performance tweaks.

However, it requires profiling to be added as a pre-protection step in your CI/CD process, therefore increasing the build time of your application. Keep in mind that this profiling step implies executing some sort of automated tests.

If this extra step is not feasible for your case, we recommend that you use Profiling Annotations as an alternative.

Usage

Profiling Annotations are a special case of Code Annotations and users can add them to their application's source code.

These can have two formats, supporting either Jscrambler default templates or a list of transformations. For example:

// @jscrambler profiling default lightObfuscation
<or>
// @jscrambler profiling enable stringConcealing, numberToString

These annotations are generated after profiling your application and they are available in the Application Profiling report page, seen in the image below.

Profiling Summary

Step-By-Step Guide To Protect Your Application Using Profiling Annotations

1. Getting The Profiling Annotations

The profiling annotations can be retrieved from the "Profiling Report" page in two ways:

  • Clicking on the "Download Annotations" which will download a ".csv" file containing all the profiling annotations in the following structure.

    Annotation,Function Name,Line:Column,Filename   
    "// @jscrambler profiling default lightObfuscation","foo",1:10,"index.js"
    "// @jscrambler profiling default lightObfuscation","bar",5:2,"index.js"
    ...
    
  • Or clicking the "Copy to Clipboard" icon in each function row, which will only copy the profiling annotation for the specific function in that row.

    // @jscrambler profiling default lightObfuscation
    

2. Adding Profiling Annotations To The Source Code

Now, you just have to go to each function in your source code, using the location information that we provide (filename, function name, line, column), and add its respective profiling annotation, e.g.:

// @jscrambler profiling default lightObfuscation
function highCostFunction() {
 // performance-intensive logic
}

Note 1: if the location of the functions doesn't seem right, take a look at Source Maps.

Note 2: be careful when adding profiling annotations as code comments, which are usually removed by minifiers. To avoid this, you can add profiling annotations as strings, assuring that it is the first statement in the target function. For example:

function highCostFunction() {
  '@jscrambler profiling default lightObfuscation';
  // performance-intensive logic
}

When you finish adding all the profiling annotations to your application's source code, you are ready to protect your app.

3. Protecting The Application

To protect your app, upload it, like you usually do, then select the "Profiling Mode: Annotations" and click "Protect App" like shown in the following image.

Note: If you are using the Jscrambler CLI, please take a look into the Profiling via CLI guide.

Profiling Summary

Source Maps

In some scenarios, the source code that you are trying to protect is not exactly the source code of your application. You might have some bundling or minification process that happens before sending your bundle file for protection. A good example of this is using our jscrambler-webpack-plugin or something similar. In cases like that, the mapping between function name and filename, line and column will most likely be wrong. To solve that problem, we recommend that you upload the source maps produced by that pre-protection process so that Jscrambler can trace the location back to your original source code.

After that you will be able to enable Source Maps directly in the Profiling Report page:

Profiling Source Maps

Frequently Asked Questions

If I add the annotations to my code, can I use the automatic profiling flow again in the future?

Yes, you can. When selecting the Automatic mode, Jscrambler will ignore those profiling annotations.

What happens to code that already uses non-profiling annotations?

The two types of annotations can coexist in the same files, but not in the same statement.

Do other types of annotations (such as disable, order or define) also have profiling counterparts?

No, only the enable and default keywords are available for profiling annotations. However, you can refer to aliases created with define keyword when using profiling enable annotations.

What happens to code that includes profiling annotations when using the 'Off' or 'Automatic' modes?

When you select Off or Automatic modes, Jscrambler ignores the profiling annotations present in your code. All the other non-profiling annotations continue to work as usual.

What can I do if the location of my functions is wrong in the Profiling Report page?

This is most likely related to the uploaded source code not being exactly your application source code because you have some kind of bundling/minification process before protecting your code. Take a look at Source Maps and see if it's suitable for your case.