Documentation/dev-inspector.txt - gerrit.git - Git at Google


            
            :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

            
            ---------
	: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
	---------