Logging

Starting with Oryon version 2.4.0, the Oryon agent allows to control its logging, primarily for circumstances where troubleshooting is required.

For that purpose, two Java properties may be set (if they are not present, the system will use defaults as outlined below).

oryon.loglevel

Sample usage: -Doryon.loglevel=debug

This setting defines the verbosity of the logging. The supported values are:

  • ERROR
  • WARN
  • INFO
  • DEBUG
  • TRACE

The default log level is INFO, which is not very verbose. Note that you may specify the loglevel in a case-insensitive manner, as shown in the above example.

oryon.logtarget

Sample usage: -Doryon.logtarget=C:/temp/oryon-agent.log

This setting defines where the logs will be written to. There are three predefined values:

  • stdout: Standard output
  • stderr: Standard error
  • slf4j: Force using the SLF4J logging framework

The default behavior is: Try to use slf4j if it seems to be usable (i.e. if the corresponding classes exist), otherwise fall back to stdout.

Finally, if the setting does not correspond to any of the predefined values (as shown in the example above), the value is interpreted as a filename. It is strongly recommended to provide an absolute path. Also ensure that the target directory exists, and that the file can be written to.

If logging to the given file fails for some reason, it will fall back to the default as specified above.

oryon.f7log

Sample usage: -Doryon.f7log=E

This property, introduced with version 2.8.0, allows to react to F7 keypresses (highlight current node) even if there is no Oryon IDE connected to the target application.

Traditionally, the F6 and F7 keys are used while developing Oryon scripts, with the target application running at the same time as the IDE, where the F6 key lets users invoke actions on the node under the mouse cursor, whereas the F7 key tells the IDE to highlight the respective node in the tree representation of the IDE.

Note that it is actually the IDE reacting to these keypresses and performing the appropriate logic; in other words, if there is no IDE connected, then the keypresses will have no effect.

How to use

The format for setting the value of this property is very simple:

  • if it contains the letter E, logging will be performed to stderr.
  • if it contains the letter O, logging will be performed to stdout.
  • if it contains the letter L, logging will be performed using the currently active logging framework (log4j or java logging).

Example: -Doryon.f7log=EOL will log using all three methods. That is not necessarily recommended or needed, but this implementation should be flexible enough to cover most needs. Here is a sample output when running with the abovementioned setting and pressing F7 on a menu entry (notice how it is logged 3 times using all output targets as specified):

F7: /Frame[@nativname='SyriusAppFrame']//Menu[@text='Partner']/MenuItem[@text='Partner']
F7: /Frame[@nativname='SyriusAppFrame']//Menu[@text='Partner']/MenuItem[@text='Partner']
2024-04-02 14:29:23,450 Oryon: INFO [JavaFX Application Thread] F7Logger F7: /Frame[@nativname='SyriusAppFrame']//Menu[@text='Partner']/MenuItem[@text='Partner']

Where to use

This property is evaluated by the Oryon agent as well as the Oryon driver.

In other words, you can use it directly when launching the JVM that runs the target application with the Oryon agent injected, or you can use it in the JVM that is using the Oryon driver to automate the target application (for instance when locally running unit tests). You could even do both at the same time! The recommendation however is to only enable it if needed, and when you are able to actually access (i.e., see) its output.

Notes

  • This property is not evaluated by the Oryon IDE; it is not needed there, because the IDE already appropriately reacts to F7 events by highlighting the node in the tree view.
  • When using this property on the client (=OryonDriver) side while debugging, you must ensure that the client JVM is not entirely halted when a breakpoint is hit. The easiest way to accomplish this is to adjust the breakpoint properties so that it only suspends the thread hitting the breakpoint, not the entire JVM. Otherwise, if the entire JVM is halted, the notification about the F7 keypress will not be processed – and therefore no logs shown – until the JVM (and thus also the thread consuming the notification and performing the logging) is resumed.
  • The property can be set as shown above, i.e., by adding it to the JVM parameters when launching an application. It is also possible (and possibly preferable) to directly define it in code; here’s a trivial “define-and-forget” implementation which will work across all unit tests in the codebase:
// Let all your test classes extend this class
public class OryonUnitTest {
    @BeforeClass
    public static void installF7Logger() {
        System.setProperty("oryon.f7log", "E");
    }
}