Profiling via Web App

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).

To start Profiling an application, please switch from the Protect App to the Create Profiling context. To do that, navigate to the right sidebar and from the dropdown at the top, select "Create Profiling".

Profiling Step-By-Step Guide

1. Instrumenting the Application

Instrumentation is the process of adapting the application to include measurement tools that report to Jscrambler how often and for how long each function of the program runs.

Note: If you are uploading transpiled or bundled source files (e.g using webpack or Babel), you should also upload the source maps for a better profiling experience.

Click "Instrument application" and wait for the process to finish.

This operation will generate a bundle containing all the application source files. Only the ones that contain JavaScript will be instrumented.

WARNING: These files are not protected and you should not distribute them to any untrusted party.

2. Running the Profiler

Once the instrumentation finishes, download the instrumented application by clicking the "Download Instrumented App" button.

Unzip the instrumented application and run it as you would normally run your application.

Don't forget to click "Start Profiling" in the Profiling menu to signal the Profiling service to start collecting statistics.

Simulate typical use cases of the application, making sure to include areas where the performance after obfuscation has been an issue. We recommend running the automated unit tests using the instrumented code, thus ensuring greater coverage of the program flows.

During the execution of the instrumented application, the profiler will collect performance statistics and periodically upload them to our servers. For better results, ensure that the application maintains internet connectivity throughout this process to avoid loss of profiling data.

During this process, a status box will appear, displaying the Profiling progress in realtime.

While this is running, you can check the Preliminary Report to have a realtime detailed overview of the statistics we collect. More on that in the Profile Report section.

It's common and expected that the instrumented application is slower than the original version. Do not worry: this slowdown is due to the overhead of measuring the properties of the application, and will not be present in the final protected version.

If for some reason, you believe that the collected data is not representative, you can stop and restart the Profiling from the beginning at any time.

3. Stopping the Profiler

When you consider that most of the application has been tested, you can click "Stop Current Profiling".

After ceasing profiling, the Jscrambler service will aggregate all the collected data, processing it afterward.

Note: The profiling service will automatically stop if it does not receive any profiling data for more than 30 minutes.

4. Analyzing the Profiling Summary

After stopping the current profiling, you can check a summary of the profiling, which provides granularity over the profiling code coverage.

As it can be seen in the image, the profiling summary has two main components. The first one, with a pie-chart can be seen as a high-level summary of the profiling service results. The second one introduces a ranking with emphasis on functions with the most impact throughout the process.

The pie-chart presents an overview of metadata collected and decisions made during profiling, namely:

• Profiled Functions: Functions executed during profiling;
• Remaining Functions: Functions that were not executed during profiling;
• Recommended Settings: Functions that will be protected with the recommended settings by the profiling service, for example recommending the light obfuscation default template when a function is profiled as being performance critical;
• General Settings: Functions that will be protected with the general settings selected by the user for the whole application.

Note that functions not covered during profiling will still be protected using the general settings chosen by the user for the entire application.

If the results do not show a high percentage of coverage of the target profiling functions, this could be due to many factors. We recommend you to re-check if you tested most of the application features and if you have managed to exercise most of its logic. These two issues are the typical cause of low/medium profiling coverage.

An alternative explanation would be that your application is not using some of the functionalities included in first or third-party libraries. In this case ⁠— although it's not mandatory ⁠— you could consider removing the logic that your application doesn't need. To do that you can use an optimization tool that applies techniques such as Tree shaking to your application code. This will not reduce the number of remaining functions to zero but will significantly reduce the size of the resulting code.

Keep in mind that it is not expected for your application to reach 100% of profiled functions coverage, especially when profiling big or complex applications. Nonetheless, if you are observing a significant count on functions that were not profiled, you should try to understand what might be causing this.

5. [Optional] See Profiling Report

If you want to have a more detailed view of the impact of each profiled function of your application, you can click the "See Report" button to access the Profiling Report page.

The Profiling Report page shows which template is applied to each function based on profiling data, so you can validate and customize those decisions.

For instance, if you know that a function is security-critical, you can use the profiling report to verify that the appropriate security settings are applied to it, changing the template if necessary (note: you can also use Code Annotations to force certain transformations to be applied).

You can also use the Profiling Report to learn more about the performance of your applications.

Below is a description of each column in the report page.

• Function Name: Function name ("anonymous" if it's an anonymous function);
• No. of calls: Number of times a function is called during profiling;
• Loop Counter: The count of iterations inside loops for the specific function (Note: a function may be called only a few times but still hold performance-critical logic due to its inner loops);
• Self Time: Indicates function's cumulative time spent executing code in the function itself (inline statements), ignoring any of the functions it might call;
• Template: Protection template (set of transformations) to be applied to a function;
• Line:Column: Line and column where the function declaration can be found;
• File Name: File name where the function can be found;
• Annotations: Profiling annotation "copy to clipboard" action.

Note: Please consider reading documentation about Profiling Code Annotations.

When you are done analyzing the Profiling Report, click "Create Protection" to move on to the App Protection Page.

Source Maps

Please notice the "Source Maps" toggle near the search box. When selected, this will map the location of the profiled functions back to your source code. For example, if you are protecting a bundle, this can map the bundle functions location back to the original code — thus making it easier for you to know where to add the Profiling Code Annotations.

For this to work, you must upload source-maps to your application.

For example:

• bundle.js
• bundle.js.map

Note: currently we do not support inline source-maps.

6. Protecting your application

You are all set to protect your application using the profiling settings. To do that, switch to the "Protect App" context (if you are not there yet) by selecting that option in the right sidebar dropdown menu. Then make sure that the option "Profiling Mode: Automatic" is selected. You can also choose Profiling Mode: Annotation — but, before that we recommend you to take a look into Profiling Annotations. To protect the application, click on "Protect App".

Once the protections finishes, run the protected version and you should notice significant performance improvements over the protected version that did not use profiling data.

If you wish to, you can still obtain a protected version that does not use profiling information, by selecting the "Profiling Mode: Off" option and protecting the application again.

The profiling settings used in each protection are available in the "Protection History" page.

Frequently Asked Questions

What happens if I change the application after profiling it? Is my profiling data still valid?

Any change to the application's source code will make the profiling data invalid. For this reason, if you select the automatic mode, we always recommend you to request new profiling. While in the annotations mode, you should only request new profiling, if you experience performance degradation on your application.

What happens when both Code Annotations and Profiling are used?

Code Annotations take precedence over all Profiling operations.

How long can Profiling take?

As long as it takes to execute all the representative use-cases of your application.

Can I stop Profiling and resume later?

No. If you stop Profiling, you will need to restart Profiling from the beginning to collect any additional data. If the instrumented application is closed but the profiling wasn't stopped, then it can be reopened for additional profiling, but if it is closed for too long (so it does not send any further data), profiling will be automatically stopped after some time.

It is also not recommended to leave the application open and idle for long periods unless that is something your end-users are also likely to do, since doing so have the profiler believe that being idle is a typical use case of the application.

Is it possible to access the Profile Report for a specific protection?

Yes. To do that go to "Protection History", select the desired protection and click the link in the "Profiling Report" section. As a side note, in the "Protection History", there is a column named "Profiling" which tells if a protection was made using profiling settings, helping users to easily identify these kinds of protections.

Is it possible to Profile a React Native application?

Yes, you can use the Jscrambler CLI to protect a React Native application.

What does it mean to have a high percentage of functions with Recommended Settings?

When the profiling service detects functions as being protection-sensitive (e.g. performance-critical) it automatically recommends specific protection settings to them.

You should be cautious in cases where a high percentage of the functions are recommended to be protected with a Light Obfuscation template, as this can reduce the level of protection on those functions. Please review each function individually to make sure that there isn't any case of a function that requires a high level of protection.

Does profiling work with source code without functions?

Not at this point. The profiling service does not analyze code outside functions.