About the Studio Customization Toolkit Origin Trace Facility

You can enable the generation of a stacktrace to be passed as a parameter whenever a call from the Studio Customization Toolkit client is made into the 3DSpace kernel. This means that log output enabled by MX_VERBOSE_TRACE can include the Studio Customization Toolkit/client-side class (that is, the app, applet, servlet, bean, jsp page, or JPO) of any call, so that the origin of problematic Studio Customization Toolkit calls can be identified and fixed. In addition, when Studio Customization Toolkit origin tracing is enabled, its output is added to the output of the MQL server monitor command. (Refer to the MQL Guide for details.) Studio Customization Toolkit origin tracing can be enabled on the Studio Modeling Native Apps, XML client, 3DSpace Service, and JNI (RIP) architectures.

This page discusses:

See Also
Enabling the Studio Customization Toolkit Client
ENOVIA Live Collaboration Memory Management
Example of Studio Customization Toolkit Origin Trace Ouput

Tracing must be enabled on the Studio Customization Toolkit client (or Studio Modeling Native Apps) as well as the Web Server and 3DSpace Service layers. When enabled on the Studio Customization Toolkit client, the stacktrace information is created; when enabled on the 3DSpace Service, this information is printed to the server's log file (for the Studio Modeling Native Apps, it is created and printed to the local log file) and available for adding to the server monitor command output. The added information may result in greatly increased network traffic, slower performance, and consumption of server disk space, and therefore is not on by default, and should only be enabled when troubleshooting.

Studio Customization Toolkit origin tracing should not be enabled during production use, since additional machine resources are required.

When a problematic Studio Customization Toolkit call (such as a dangling transaction or a wildcard query) is identified, implementors should look at the verbose trace file for the stack trace string of that problematic call. This string will show the Studio Customization Toolkit origin page, bean, servlet, jsp page or app class.

Enabling the Studio Customization Toolkit Client

XML Applet

To enable the Web version of the 3DSpace to generate a stacktrace for all calls, uncomment the following to the jsp that is used to start Matrix:

props.put("ADKTrace", "TRUE");

The default setting is "FALSE."

You must also enable the platform and web servers to print the stack traces in a log file.

Custom Studio Customization Toolkit apps

To enable this level of tracing in the Studio Customization Toolkit client app, use one of the following methods in the matrix.db.Context class. For global tracing on all Context objects created use:

    public static void setOriginTraceAll(boolean set) 

    public static boolean getOriginTraceAll()

For tracing on a single Context object, jsp, or JPO use: 

    public void setOriginTrace(boolean set)

    public boolean getOriginTrace()

You must also enable the platform and web servers to print the stack traces in a log file.

Enabling the Web or App Server

To trace all servlets and jsps executed on the server, uncomment the following in your framework.properties file:

ematrix.origin.trace=true

This enables tracing globally for all context objects created.

Alternatively, you can add this setting to web.xml (either by modifying the file in a blown out war file, or using the app server's administration console to modify an already deployed webapp).

When tracing jsps, it is helpful to configure the web server to "keep generated" java code for jsps. Consult your web server documentation for instructions.

Enabling the ENOVIA Live Collaboration Kernel

This topic describes how to enable the 3DSpace kernel.

To enable the 3DSpace Service or Studio Modeling Native Apps to print the stack traces into a file called matrixserver.log add the following to the .ini file or emxEnv.sh:

MX_VERBOSE_TRACE=matrixserver.log

Also include the appropriate setting(s) to indicate which Studio Customization Toolkit calls to trace:

  • To trace all Studio Customization Toolkit calls, use:

MX_ADK_TRACEALL=true

  • To trace only specific Studio Customization Toolkit calls, each jdl call can be enabled individually, using it's name as the keyword. Do not include MX_ADK_TRACEALL. For example:
executeCmd_bosMQLCommand=true
evaluate_bosQuery=true
start_bosContext=true

On Windows, a file named adkTrace.ini is installed in the ENOVIA_INSTALL directory when the Studio Modeling Native Apps or the 3DSpace Service is installed. This file contains samples of all possible per-Studio Customization Toolkit call trace settings. Administrators can use this file to copy settings to their enovia.ini files for the Studio Modeling Native Apps or 3DSpace Service (previously matrix.ini or ematrix.ini) when they wish to enable tracing on a particular Studio Customization Toolkit call.

On Unix, a file called adkTrace.sh is installed in the SERVERHOME directory when the Studio Modeling Native Apps or the 3DSpace Service is installed. The Studio Modeling Native Apps as well as the 3DSpace Service's shell scripts call this auxiliary shell script, which contains commented out/disabled samples of all possible per-ADK call trace settings (as well as the traceall setting). Administrators can uncomment those they wish to have traced.

Studio Customization Toolkit Exceptions

The freeContext.bosInterface call does not include a stack trace; it is called by the java garbage collector.

The allocExternalContext.bosInterface stack trace is supplied as a parameter to the call in verbose logging if Studio Customization Toolkit origin tracing is enabled on the client side (regardless of MX_ADK_TRACEALL setting). If client side tracing is disabled, a blank stack trace is generated. To prevent unwanted network traffic, ensure the stack trace for allocExternalContext.bosInterface is blank, thus ensuring the feature is disabled on the client side (JPO, applet or web server).

Studio Customization Toolkit Origin Trace Output

MX_VERBOSE_TRACE processing prints the session ID and stack trace string.

Here is sample output from a JPO:

15:52:49.109 VERB t@2544 allocate context for session 
EvcL6qZfvtlNMKrC2q3O33lKBmevRTQtNa5MSmBWb0Kps2IdbX2j!1231146595!1156521163062:mx435012
3950b68a7:(__emxnavigator.java:959)

15:52:49.109 VERB t@2544   input params: 
className=emxPropertyUtil_mxJPOzXZnZQAAAAEAAAAB

15:52:49.109 VERB t@2544     stacktrace: 

    at com.matrixone.jdl.bosInterfaceShim.classLoader(Unknown Source)

    at matrix.db.MatrixClassLoader.getBytes(MatrixClassLoader.java:67)

    at matrix.db.MatrixClassLoader.findClass(MatrixClassLoader.java:86)

    at java.lang.ClassLoader.loadClass(ClassLoader.java:294)

    at matrix.db.MatrixClassLoader.newClass(MatrixClassLoader.java:167)

    at matrix.db.MatrixClassLoader.newInstance(MatrixClassLoader.java:197)

    at matrix.db.MatrixClassLoader.newInstance(MatrixClassLoader.java:292)

    at com.matrixone.jni.MatrixKernel.statelessDispatch(Native Method)

    at com.matrixone.jdl.rmi.bosInterfaceImpl.invokeClass(Unknown Source)

    at java.lang.reflect.Method.invoke(Native Method)

    at sun.rmi.server.UnicastServerRef.dispatch(UnicastServerRef.java:236)

    at sun.rmi.transport.Transport$1.run(Transport.java:147)

    at java.security.AccessController.doPrivileged(Native Method)

    at sun.rmi.transport.Transport.serviceCall(Transport.java:143)

    at sun.rmi.transport.tcp.TCPTransport.handleMessages(TCPTransport.java:460)

    at sun.rmi.transport.tcp.TCPTransport$ConnectionHandler.run(TCPTransport.java:701)

    at java.lang.Thread.run(Thread.java:479)

15:52:49.140 VERB t@2544   output params: returnVal length=365

15:52:49.140 VERB t@2544 dispatch complete since 15:52:49.109, 0.031 secs (0.031 direct 
0.000 nested)

Verbose tracing output can include the caller information appended to the context session id generated by Framework.getFrameContext(). Following is an example illustrating this- note that the caller information emxteamsearchcontentresult.java follows the string: B1yyHxgoYeuyPHpaAPAH2qLIBGplw42XKR5B228B2Oki2UJNLuKH!-682390697!16 7842110!7001!7002!1102426802906:mx1102427172562633055.

13:46:13.390 VERB t@1776 stateless dispatch for evaluateSelect.bosQuery

13:46:13.390 VERB t@1776 allocate context for session 
B1yyHxgoYeuyPHpaAPAH2qLIBGplw42XKR5B228B2Oki2UJNLuKH!-682390697!167842110!7001!7002!11 
02426802906:mx1102427172562633055:(__emxteamsearchcontentresult.java:3628)

13:46:13.390 VERB t@1776   input params: name=, query type=Document, name=*, 
revision=*, lattice=eService Production, owner=*, where=(revision == last) && 
(("to[Vaulted Objects].from.id" !~~ "zz")) && (current.access[read] == TRUE), limit=0, 
expandTypes=true

, objectSelect length=2

13:46:13.437 VERB t@1776   output params: