Orion/How Tos/How to enable log service support in Orion

Orion log service support is a group of built-in extensions, which enable you to manage server logs using Orion itself. Beside updating Orion logger levels with immediate effect, you may require file-based logs from a running Orion instance, process them in your plugins, save them in the cloud, or directly download them to your local machine. Since the log service is disabled by default, special configuration is required to enable this feature.

Local instance configuration

By default, Orion uses a console-based log appender. To change this behavior, edit your run configuration and provide a custom logback configuration file using the

-Dlogback.configurationFile=/path/to/my/custom/logback-configuration.xml

argument. This will override Orion log configuration and get you full access to your Orion instance log strategy. The log service feature supports only file-based appenders, so you have to ensure there's at least one file appender present. One example file-based logback configuration may be found in the org.eclipse.orion.server.logback.config server bundle. For more logback documentation, please visit [1].

Another simple example configuration file:

<configuration>
  <!-- See documentation at http://logback.qos.ch/manual/joran.html -->
  <appender name="FILE" class="ch.qos.logback.core.FileAppender">
    <file>/opt/logs/orion.log</file>
    <append>true</append>
    <encoder>
      <pattern>%-4relative [%thread] %-5level %logger{35} - %msg%n</pattern>
    </encoder>
  </appender>
  
  <!-- Prints successful and failed logins -->
  <logger name="org.eclipse.orion.server.login" level="INFO"/>

  <!-- Prints user account creations and deletions -->
  <logger name="org.eclipse.orion.server.account" level="INFO"/>

  <!-- Prints information on locating and reading the server configuration file -->
  <logger name="org.eclipse.orion.server.config" level="INFO"/>

  <root level="WARN">
    <appender-ref ref="FILE" />
  </root>
</configuration>

In order to use the log service feature, one more configuration step is required. Uncomment the

orion.logs.logProviderEnabled=true

entry in the Orion configuration file. Please note this configuration entry is most likely to change and be replaced with a more user-role-based solution. The server side should now be configured and ready to use.

Pre-buit instance

Please follow the instructions in the Local instance configuration using the orion.ini file to configure Orion run arguments.

Client UI configuration

The client side UI gives you a shell plugin to manage basic log service features. By default, the plugin is not present in your default plugin set list, so you have to install it manually using the shell/plugins/shellLogProviderPlugin.html plugin link. For more information on how to install Orion plugins, please see: Orion/How_Tos/Installing_A_Plugin.

Basic usage

Go to your shell and type help to view all available plugins:

You are given two command groups: logs and loggers. The first one is responsible for providing log-files and appenders metadata. You may list all file-based appenders in the current logger context using logs show, download a specific active log-file using logs download, or view the log-file archive using logs history.

The loggers group is responsible for managing loggers and their log-levels. To list all loggers in the current logger context, use loggers show. To dynamically change the log-level of a particular logger, use loggers update. Effective log-levels are surrounded in brackets, explicit levels are printed without. For detailed info on logger level inheritance, please visit: [2].

Security awareness

Please be aware, that the log directory location should be unique per Orion instance. In other words, you should not log to one directory location from different Orion instances. If you do, log-files might be visible from different Orion instances, although they do not share the same source.