| :linkattrs: |
| = Gerrit Inspector |
| |
| == NAME |
| Gerrit Inspector - Interactive Jython environment for Gerrit |
| |
| == SYNOPSIS |
| [verse] |
| -- |
| _java_ -jar gerrit.war _daemon_ |
| -d <SITE_PATH> |
| [--enable-httpd | --disable-httpd] |
| [--enable-sshd | --disable-sshd] |
| [--console-log] |
| [--replica] |
| -s |
| -- |
| |
| == DESCRIPTION |
| Runs the Gerrit network daemon on the local system as described |
| in the link:pgm-daemon.html[Daemon documentation], additionally |
| starting an interactive Jython shell for inspection |
| and troubleshooting of live data of the Gerrit instance. |
| |
| CAUTION: Gerrit Inspector works directly on instances of Java Virtual |
| Machine objects and it is possible to read and write instance |
| members as well as invoke Java functions. Access is granted |
| also to 'private' and 'protected' members. Therefore it is possible |
| to introduce changes to the internal state of the system in |
| an inconsistent way. Care must be taken not to break the running system |
| and/or destroy the data. |
| |
| == INSTALLATION |
| |
| Gerrit Inspector requires Jython library ('jython.jar') to be installed |
| in the '$site_path/lib' directory. Jython, a Python interpreter for |
| the Java Virtual Machine, can be obtained from the http://www.jython.org/[role=external,window=_blank] |
| website. Only 'jython.jar' file is needed, installation of Jython libraries |
| is optional. Gerrit Inspector has been tested with Jython 2.5.2 but |
| might work an earlier version. |
| |
| == STARTUP |
| |
| During startup Jython examines Java libraries found on the classpath. |
| While libraries are inspected a large amount of messages is displayed on the console: |
| |
| ---- |
| *sys-package-mgr*: processing new jar, '/home/user/.gerritcodereview/tmp/gerrit_4890671371398741854_app/sshd-core-0.5.1-r1095809.jar' |
| ---- |
| |
| After this a system-wide embedded initialization script is started. This script |
| is contained in the gerrit's WAR archive. This script produces output similar to |
| the following on the console: |
| |
| ---- |
| "Shell" is "com.google.gerrit.pgm.shell.JythonShell@61644f2d" |
| "m" is "com.google.gerrit.lifecycle.LifecycleManager@6f03b248" |
| |
| Welcome to the Gerrit Inspector |
| Enter help() to see the above again, EOF to quit and stop Gerrit |
| ---- |
| |
| Then an optional user startup script is processed. It should be |
| located in the gerrit user home directory as '.gerritcodereview/Startup.py'. |
| |
| This script can access all variables defined in the system (such |
| as the ones displayed by the initialization script as shown above). |
| Variables and functions defined by the startup scripts are available for |
| the interactive interpreter. |
| |
| When interactive interpreter exits (by issuing EOF on the command line), |
| a whole Gerrit instance is shut down gracefully. |
| |
| == USING THE INTERPRETER |
| |
| Gerrit Inspector launches Jython interpreter in the context of the Gerrit |
| Java Virtual Machine. All core facilities of the Jython (and Python) |
| language are available to the user. |
| |
| Additional facilities can be provided, for example a 'Lib' directory from the |
| Jython distribution can be installed under '$site_path/lib/Lib' to provide |
| access to many standard Python modules. Jython can also use additional Java |
| classes and libraries and most of the Python modules and scripts. |
| |
| The Inspector has by default access to classes and object instances available |
| in the Java Virtual Machine. Objects are introspected and *private* and *protected* |
| members are also available. |
| |
| For more information on using Jython, especially with regards to its limitations |
| in interfacing to the Java Virtual Machine, please refer to the |
| http://www.jython.org/[Jython documentation,role=external,window=_blank]. |
| |
| After successful initialization it is possible to examine components of |
| Java packages, classes and live instances. |
| |
| ---- |
| >>> import com.google.inject |
| >>> dir(com.google.inject) |
| ['AbstractModule', 'Binder', 'Binding', 'BindingAnnotation', 'ConfigurationException', 'CreationException', 'Exposed', 'Guice', 'ImplementedBy', 'Inject', 'Injector', 'Key', 'MembersInjector', 'Module', 'OutOfScopeException', 'PrivateBinder', 'PrivateModule', 'ProvidedBy', 'Provider', 'Provides', 'ProvisionException', 'Scope', 'ScopeAnnotation', 'Scopes', 'Singleton', 'Stage', 'TypeLiteral', '__name__', 'assistedinject', 'binder', 'internal', 'matcher', 'name', 'servlet', 'spi', 'util'] |
| >>> type(com.google.inject) |
| <type 'javapackage'> |
| >>> dir(com.google.inject.Guice) |
| ['__class__', '__copy__', '__deepcopy__', '__delattr__', '__doc__', |
| '__eq__', '__getattribute__', '__hash__', '__init__', '__ne__', |
| '__new__', '__reduce__', '__reduce_ex__', '__repr__', '__setattr__', |
| '__str__', '__unicode__', 'class', 'clone', 'createInjector', |
| 'equals', 'finalize', 'getClass', 'hashCode', 'notify', 'notifyAll', |
| 'registerNatives', 'toString', 'wait'] |
| ---- |
| |
| A built-in *help()* function provides values of global variables |
| defined in the interpreter: |
| |
| ---- |
| >>> help() |
| "m" is "com.google.gerrit.lifecycle.LifecycleManager@6f03b248" |
| "Shell" is "com.google.gerrit.pgm.shell.JythonShell@61644f2d" |
| "d" is "com.google.gerrit.pgm.Daemon@28a3f689" |
| |
| Welcome to the Gerrit Inspector |
| Enter help() to see the above again, EOF to quit and stop Gerrit |
| ---- |
| |
| Java and Python exceptions are intercepted by the Inspector: |
| ---- |
| >>> import java.lang.RuntimeException |
| >>> raise java.lang.RuntimeException("Exiting") |
| Traceback (most recent call last): |
| File "<stdin>", line 1, in <module> |
| at sun.reflect.NativeConstructorAccessorImpl.newInstance0(Native Method) |
| at sun.reflect.NativeConstructorAccessorImpl.newInstance(NativeConstructorAccessorImpl.java:57) |
| at sun.reflect.DelegatingConstructorAccessorImpl.newInstance(DelegatingConstructorAccessorImpl.java:45) |
| at java.lang.reflect.Constructor.newInstance(Constructor.java:532) |
| at org.python.core.PyReflectedConstructor.constructProxy(PyReflectedConstructor.java:210) |
| |
| java.lang.RuntimeException: java.lang.RuntimeException: Exiting |
| >>> |
| ---- |
| |
| To exit the interpreter, use EOF character (Ctrl-D on Unix systems, Ctrl-Z on Windows). |
| |
| It is also possible to shut down the JVM by using *System.exit()* |
| |
| ---- |
| >>> import java.lang.System |
| >>> java.lang.System.exit(1) |
| ---- |
| |
| And Gerrit should shut down all its subsystems and exit: |
| |
| ---- |
| [2012-04-17 15:31:08,458] INFO com.google.gerrit.pgm.Daemon : caught shutdown, cleaning up |
| ---- |
| |
| == TROUBLESHOOTING |
| |
| Gerrit Inspector is logging to the Gerrit error log. |
| |
| A successful startup is indicated in the logfile: |
| |
| ---- |
| [2012-04-17 13:43:44,888] INFO com.google.gerrit.pgm.shell.JythonShell : Jython shell instance created. |
| ---- |
| |
| If 'jython.jar' library is not available, Gerrit refuses to start when given *-s* option: |
| |
| ---- |
| [2012-04-17 13:57:29,611] ERROR com.google.gerrit.pgm.Daemon : Unable to start daemon |
| com.google.inject.ProvisionException: Guice provision errors: |
| |
| 1) Error injecting constructor, java.lang.UnsupportedOperationException: Cannot create Jython shell: Class org.python.util.InteractiveConsole not found |
| (You might need to install jython.jar in the lib directory) |
| at com.google.gerrit.pgm.shell.JythonShell.<init>(JythonShell.java:47) |
| while locating com.google.gerrit.pgm.shell.JythonShell |
| while locating com.google.gerrit.pgm.shell.InteractiveShell |
| ---- |
| |
| Errors during processing of the startup script, 'Startup.py', are logged |
| to the error log: |
| |
| ---- |
| [2012-04-17 14:20:30,558] INFO com.google.gerrit.pgm.shell.JythonShell : Jython shell instance created. |
| [2012-04-17 14:20:38,005] ERROR com.google.gerrit.pgm.shell.JythonShell : Exception occurred while loading file Startup.py : |
| java.lang.reflect.InvocationTargetException |
| at sun.reflect.NativeMethodAccessorImpl.invoke0(Native Method) |
| at sun.reflect.NativeMethodAccessorImpl.invoke(NativeMethodAccessorImpl.java:57) |
| at sun.reflect.DelegatingMethodAccessorImpl.invoke(DelegatingMethodAccessorImpl.java:43) |
| at java.lang.reflect.Method.invoke(Method.java:616) |
| at com.google.gerrit.pgm.shell.JythonShell.runMethod0(JythonShell.java:112) |
| at com.google.gerrit.pgm.shell.JythonShell.execFile(JythonShell.java:194) |
| at com.google.gerrit.pgm.shell.JythonShell.reload(JythonShell.java:178) |
| at com.google.gerrit.pgm.shell.JythonShell.run(JythonShell.java:152) |
| at com.google.gerrit.pgm.Daemon.run(Daemon.java:190) |
| at com.google.gerrit.pgm.util.AbstractProgram.main(AbstractProgram.java:67) |
| at sun.reflect.NativeMethodAccessorImpl.invoke0(Native Method) |
| at sun.reflect.NativeMethodAccessorImpl.invoke(NativeMethodAccessorImpl.java:57) |
| at sun.reflect.DelegatingMethodAccessorImpl.invoke(DelegatingMethodAccessorImpl.java:43) |
| at java.lang.reflect.Method.invoke(Method.java:616) |
| at com.google.gerrit.launcher.GerritLauncher.invokeProgram(GerritLauncher.java:167) |
| at com.google.gerrit.launcher.GerritLauncher.mainImpl(GerritLauncher.java:91) |
| at com.google.gerrit.launcher.GerritLauncher.main(GerritLauncher.java:49) |
| at Main.main(Main.java:25) |
| Caused by: Traceback (most recent call last): |
| File "/home/user/.gerritcodereview/Startup.py", line 1, in <module> |
| Test |
| NameError: name 'Test' is not defined |
| ---- |
| |
| Those errors are non-fatal. System and user scripts can be loaded again |
| by issuing the following command in the Gerrit Inspector console: |
| |
| ---- |
| Shell.reload() |
| ---- |
| |
| == LOGGING |
| Error and warning messages from the server are automatically written |
| to the log file under '$site_path/logs/error_log'. |
| |
| Output and error messages (including Java and Python exceptions) |
| resulting from interactive work are logged to the console. |
| |
| == KNOWN ISSUES |
| The Inspector does not yet recognize Google Guice bindings. |
| |
| [IMPORTANT] |
| Using the Inspector may void your warranty. |
| |
| GERRIT |
| ------ |
| Part of link:index.html[Gerrit Code Review] |
| |
| SEARCHBOX |
| --------- |
