[CUBA-component] Runtime diagnose preview

Ideas
#1

Hi,

i created a cuba-application component that you can use. It is in preview mode currently. Before releasing it “officially” i would like to get your feedback on it. It is open source (Apache 2 license) and you can find it on github:

GitHub - mariodavid/cuba-component-runtime-diagnose: CUBA component for interactive runtime application diagnose and debugging.

If you have any thoughts on that, like bug, feature requests etc. i would love to hear from you.

I’ll just copy over the README.md so you get an impression on what it does:

CUBA Platform Component - Runtime diagnose

This application component can be used for interactive runtime application diagnose and debugging of a CUBA application.
It is based on the idea of the Grails console.

It mainly consists of the three parts:

  • interactive Groovy console
  • interactive SQL console
  • non-interactive diagnose wizard

Groovy console

The groovy console allows you to interactivly inspect the running application. You enter a groovy script and execute it in an ad-hoc fashion.

WARN: Using the groovy console in production can be dangerous. Make sure that you will use the security subsystem properly so that only allowed users are able to execute code in production. For more information see the section about security

The console uses the Scripting Interface of the platform in order to execute groovy code. Therefore most of the features of the scripting interface apply to the groovy console as well.

Using existing classes

In order to use existing platform beans or your application specific beans, you can use AppBeans.get() to get a reference to abitrary Spring beans.

NOTE: To reference classes by name you have to manually add the corresponding import statements at the top of the scripts

If you want to define custom variables that are accessible in your scripts, you have to extend the GroovyDiagnoseServiceBean like this:

class MyGroovyDiagnoseServiceBean extends GroovyDiagnoseServiceBean {

    @Override
    protected Map<String, Object> getAdditionalBindingVariableMap() {
        [now: new Date()]
    }
}

The resulting map will additionally passed to the script. In order to use your bean, you have to register it in the spring.xml of the core module of your application like this:

<bean id="ddcrd_GroovyConsoleService" class="com.company.myapp.core.MyGroovyDiagnoseServiceBean" />

This way, Spring will pick up your extension GroovyDiagnoseService.

Execution results

There are different results of a groovy script (displayed in the different tabs). The actual result of the script (meaning the return value of the last statement) is displayed in the first tab. The stacktrace tab displayes the stacktrace of a possible exception that occurs during script execution. The tab executed script shows the actual executed script.

Result log

Since STDOUT and STDERR will not captured through the runtime, println ‘hello world’ will not be included in any of the execution results. To make debug statements you can use the log variable which is passed into the script.

The possible methods are:

  • log.debug(‘debug information’)
  • log.warn(‘warnnings’)
  • log.error(‘error information’)

Download of the execution results

Execution results can be downloaded through the corresponding button. It will create a zip file which will contain the different execution results in different files. Additionally, there is a file called environmentInformation.log which will include information about the current environment of execution (like information about the user that executed the script, information about the application itself etc.)

SQL console

The SQL console allows you to interactivly interact with the database usnig raw SQL statements. You enter a SQL script and execute it in an ad-hoc fashion.

NOTE: for normal data diagnosis the Entity inspector is oftentimes more user friendly, even for debugging purposes. Usage of the SQL-console is to be preferable to the entity inspector if you want to access data across tables using joins e.g.

Results of a SQL statement are displayed in a table in the result tab. The result can be downloaded using the Excel button in the Results tab.

Security of the SQL-Console

By default, only SELECT stements are allowed to execute through the SQL-Console. If you want to execute other types of SQL statements like INSERT or ALTER it has to be explicitly configured the application component through CUBAs App properties UI: Administration > Application properties > console

The following configuration options allow different statement types:

  • runtime-diagnose.sql.allowDataManipulation
    • INSERT INTO…
    • UPDATE …
    • DELETE …
    • MERGE …
    • REPLACE …
    • TRUNCATE …
  • runtime-diagnose.sql.allowSchemaManipulation
    • DROP …
    • CREATE TABLE …
    • CREATE VIEW …
    • ALTER …
    • ALTER VIEW …
    • CREATE INDEX …
  • runtime-diagnose.sql.allowExecuteOperations
    • EXECUTE …
    • SET …

Diagnose wizard

The last part is the diagnose wizard. This option is relevant if you as a developer or customer support person don’t have direct access to the running application, because of security reasons or it is boxed software that is running out of your control. You could send your counterpart on customer side a text file which the the user should execute in the Groovy / SQL console, but this process is fairly insecure as well as error prone.

In these cases you can send the person a zip file (as a black box) and tell them to upload this file in the diagnose wizard. The person will be guided through the different steps, executed the scripts and gets back the execution results (as a zip file) that should be handed back to you.

Checks on the diagnose file

There are some checks in place in the wizard that will ensure the correctness of the zip file. Within the zip archive, there has to be the following files:

  • diagnose.groovy / diganose.sql
  • manifest.json

The diagnose.(sql|groovy) contains the executable script. The manifest file describes some metadata on the diagnose archive. Here’s a valid manifest.json file:

{
  "appVersion": "1.1",
  "appName": "runtime-diagnose-app",
  "producer": "Company Inc.",
  "diagnoseType": "GROOVY"
}

The diagnoseType has to be either GROOVY or SQL.

If the values in the manifest file do not match the expected values from the application, the script cannot be executed.

The diagnose files can be created manually or preferably from the Groovy / SQL Console. After defining the diagnose script, the “Download Diagnose File” lets the developer create the diagnose file that can be handed to the customer representative.

Bye
Mario