Revision as of 07:59, 22 July 2013 (view source) Maciej.bendkowski.gmail.com (Talk | contribs) (→‎Local instance configuration) ← Older edit		Latest revision as of 14:46, 7 November 2013 (view source) Curtis.windatt.public.gmail.com (Talk | contribs)
(11 intermediate revisions by one other user not shown)
Line 1:		Line 1:
−	Orion '''log provider support''' is a group of built-in extensions, which enable you to request server logs using Orion itself. 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 provider''' is disabled by default, special configuration is required to enable this feature.	+	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 =		= 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 provider 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 [[http://logback.qos.ch/manual/appenders.html#FileAppender http://logback.qos.ch/manual/appenders.html#FileAppender]].	+	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 <pre>-Dlogback.configurationFile=/path/to/my/custom/logback-configuration.xml</pre> 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 [http://logback.qos.ch/manual/appenders.html#FileAppender].
	Another simple example configuration file:		Another simple example configuration file:
Line 33:		Line 33:
	</pre>		</pre>
−	In order to use the log provider 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.	+	In order to use the log service feature, one more configuration step is required. Uncomment the <pre>orion.logs.logProviderEnabled=true</pre> 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 =		= Pre-buit instance =
Line 39:		Line 39:
	= Client UI configuration =		= Client UI configuration =
−	The client side UI gives you a shell plugin to manage basic log provider 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]].	+	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 =		= Basic usage =
	Go to your shell and type ''help'' to view all available plugins:		Go to your shell and type ''help'' to view all available plugins:
−	[[Image:Log-provider-ui-1.png]]
−	To list all file-based appenders in the current logger context type ''logs'':	+	[[Image:Log-provider-help.png]]
−	[[Image:Log-provider-ui-2.png]]	+	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''.
−	To get the log file content for a given appender, type ''logs {appenderName}'':	+	[[Image:Log-provider-logs.png]]
−	[[Image:Log-provider-ui-3.png]]	+
−	To get more verbose info on a particular log file type ''logs true {appenderName}'':	+	[[Image:Log-provider-logs-history.png]]
−	[[Image:Log-provider-ui-4.png]]	+
−	= Download logs =	+	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: [http://logback.qos.ch/manual/architecture.html#effectiveLevel].
−	If you wish to download your log file content, you may save the ''logs {appenderName}'' command result in a file within the Orion workspace and then download it in a raw form to your local machine. Another approach would be to use the server side API directly from your browser.	+
		+	[[Image:Log-provider-loggers.png]]
		+
		+	= 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.
		+
		+	[[Category:Orion|How To]]
		+	[[Category:Orion/How To|Log service]]

---

Latest revision as of 14:46, 7 November 2013

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.