diff options
Diffstat (limited to 'src/site-docs/adoc/fragments/howto-logging')
8 files changed, 438 insertions, 0 deletions
diff --git a/src/site-docs/adoc/fragments/howto-logging/example-logic.adoc b/src/site-docs/adoc/fragments/howto-logging/example-logic.adoc new file mode 100644 index 000000000..788894572 --- /dev/null +++ b/src/site-docs/adoc/fragments/howto-logging/example-logic.adoc @@ -0,0 +1,64 @@ +// +// ============LICENSE_START======================================================= +// Copyright (C) 2016-2018 Ericsson. All rights reserved. +// ================================================================================ +// This file is licensed under the CREATIVE COMMONS ATTRIBUTION 4.0 INTERNATIONAL LICENSE +// Full license text at https://creativecommons.org/licenses/by/4.0/legalcode +// +// SPDX-License-Identifier: CC-BY-4.0 +// ============LICENSE_END========================================================= +// +// @author Sven van der Meer (sven.van.der.meer@ericsson.com) +// + +== Example Configuration for Logging Logic + +The following example shows a configuration that logs policy logic to standard out (__info__) and a file (__debug__) +All other APEX components are logging to a file (__debug__) and standard out (__error__). +This configuration an be used in a pre-production phase with the APEX engine still running in a separate terminal to monitor policy execution. +This logback configuration is in the APEX installation as `etc/logback-logic.xml` + +[source%nowrap,xml] +---- +<configuration debug="false"> + <statusListener class="ch.qos.logback.core.status.NopStatusListener" /> + + <contextName>Apex</contextName> + <property name="VAR_LOG" value="/var/log/ericsson/apex/" /> + + <appender name="STDOUT" class="ch.qos.logback.core.ConsoleAppender"> + <encoder> + <Pattern>%d %contextName [%t] %level %logger{36} - %msg%n</Pattern> + </encoder> + </appender> + + <appender name="FILE" class="ch.qos.logback.core.FileAppender"> + <file>${VAR_LOG}/apex.log</file> + <encoder> + <pattern> + %d %-5relative [procId=${processId}] [%thread] %-5level%logger{26} - %msg %n %ex{full} + </pattern> + </encoder> + </appender> + + <appender name="POLICY_APPENDER_STDOUT" class="ch.qos.logback.core.ConsoleAppender"> + <encoder> + <pattern>policy: %msg\n</pattern> + </encoder> + </appender> + + <root level="error"> + <appender-ref ref="STDOUT" /> + </root> + +<logger name="org.onap.policy.apex" level="debug" additivity="false"> + <appender-ref ref="FILE" /> +</logger> + + <logger name="org.onap.policy.apex.executionlogging" level="debug" additivity="false"> + <appender-ref ref="POLICY_APPENDER_STDOUT" /> + <appender-ref ref="FILE" /> + </logger> +</configuration> +---- + diff --git a/src/site-docs/adoc/fragments/howto-logging/example-server.adoc b/src/site-docs/adoc/fragments/howto-logging/example-server.adoc new file mode 100644 index 000000000..b438bd4a7 --- /dev/null +++ b/src/site-docs/adoc/fragments/howto-logging/example-server.adoc @@ -0,0 +1,46 @@ +// +// ============LICENSE_START======================================================= +// Copyright (C) 2016-2018 Ericsson. All rights reserved. +// ================================================================================ +// This file is licensed under the CREATIVE COMMONS ATTRIBUTION 4.0 INTERNATIONAL LICENSE +// Full license text at https://creativecommons.org/licenses/by/4.0/legalcode +// +// SPDX-License-Identifier: CC-BY-4.0 +// ============LICENSE_END========================================================= +// +// @author Sven van der Meer (sven.van.der.meer@ericsson.com) +// + +== Example Configuration for a Production Server + +The following example shows a configuration that logs all APEX components, including policy logic, to a file (__debug__). +This configuration an be used in a production phase with the APEX engine being executed as a service on a system without console output. +This logback configuration is in the APEX installation as `logback-server.xml` + +[source%nowrap,xml] +---- +<configuration debug="false"> + <statusListener class="ch.qos.logback.core.status.NopStatusListener" /> + + <contextName>Apex</contextName> + <property name="VAR_LOG" value="/var/log/ericsson/apex/" /> + + <appender name="FILE" class="ch.qos.logback.core.FileAppender"> + <file>${VAR_LOG}/apex.log</file> + <encoder> + <pattern> + %d %-5relative [procId=${processId}] [%thread] %-5level%logger{26} - %msg %n %ex{full} + </pattern> + </encoder> + </appender> + + <root level="debug"> + <appender-ref ref="FILE" /> + </root> + + <logger name="org.onap.policy.apex.executionlogging" level="debug" additivity="false"> + <appender-ref ref="FILE" /> + </logger> +</configuration> +---- + diff --git a/src/site-docs/adoc/fragments/howto-logging/introduction.adoc b/src/site-docs/adoc/fragments/howto-logging/introduction.adoc new file mode 100644 index 000000000..0bc37c58d --- /dev/null +++ b/src/site-docs/adoc/fragments/howto-logging/introduction.adoc @@ -0,0 +1,39 @@ +// +// ============LICENSE_START======================================================= +// Copyright (C) 2016-2018 Ericsson. All rights reserved. +// ================================================================================ +// This file is licensed under the CREATIVE COMMONS ATTRIBUTION 4.0 INTERNATIONAL LICENSE +// Full license text at https://creativecommons.org/licenses/by/4.0/legalcode +// +// SPDX-License-Identifier: CC-BY-4.0 +// ============LICENSE_END========================================================= +// +// @author Sven van der Meer (sven.van.der.meer@ericsson.com) +// + +== Introduction to APEX Logging + +All APEX components make extensive use of logging using the logging façade link:https://www.slf4j.org/[SLF4J] with the backend link:https://logback.qos.ch/[Logback]. +Both are used off-the-shelve, so the standard documentation and configuration apply to APEX logging. +For details on how to work with logback please see the link:https://logback.qos.ch/manual/index.html[logback manual]. + +The APEX applications is the logback configuration file `$APEX_HOME/etc/logback.xml` (Windows: `%APEX_HOME%\etc\logback.xml`). +The logging backend is set to no debug, i.e. logs from the logging framework should be hidden at runtime. + +The configurable log levels work as expected: + +- __error__ (or __ERROR__) is used for serious errors in the APEX runtime engine +- __warn__ (or __WARN__) is used for warnings, which in general can be ignored but might indicate some deeper problems +- __info__ (or __INFO__) is used to provide generally interesting messages for startup and policy execution +- __debug__ (or __DEBUG__) provides more details on startup and policy execution +- __trace__ (or __TRACE__) gives full details on every aspect of the APEX engine from start to end + +The loggers can also be configured as expected. +The standard configuration (after installing APEX) uses log level __info__ on all APEX classes (components). + +The applications and scripts in `$APEX_HOME/bin` (Windows: `%APEX_HOME\bin`) are configured to use the logback configuration `$APEX_HOME/etc/logback.xml` (Windows: `%APEX_HOME\etc\logback.xml`). +There are multiple ways to use different logback configurations, for instance: + +- Maintain multiple configurations in `etc`, for instance a `logback-debug.xml` for deep debugging and a `logback-production.xml` for APEX in production mode, then copy the required configuration file to the used `logback.xml` prior starting APEX +- Edit the scripts in `bin` to use a different logback configuration file (only recommended if you are familiar with editing bash scripts or windows batch files) + diff --git a/src/site-docs/adoc/fragments/howto-logging/logback-status.adoc b/src/site-docs/adoc/fragments/howto-logging/logback-status.adoc new file mode 100644 index 000000000..985fa6dac --- /dev/null +++ b/src/site-docs/adoc/fragments/howto-logging/logback-status.adoc @@ -0,0 +1,31 @@ +// +// ============LICENSE_START======================================================= +// Copyright (C) 2016-2018 Ericsson. All rights reserved. +// ================================================================================ +// This file is licensed under the CREATIVE COMMONS ATTRIBUTION 4.0 INTERNATIONAL LICENSE +// Full license text at https://creativecommons.org/licenses/by/4.0/legalcode +// +// SPDX-License-Identifier: CC-BY-4.0 +// ============LICENSE_END========================================================= +// +// @author Sven van der Meer (sven.van.der.meer@ericsson.com) +// + +== Adding Logback Status and Debug + +To activate logback status messages change the status listener from 'NOP' to for instance console. + +[source%nowrap,xml] +---- +<statusListener class="ch.qos.logback.core.status.OnConsoleStatusListener" /> +---- + +To activate all logback debugging, for instance to debug a new logback configuration, activate the debug attribute in the configuration. + +[source%nowrap,xml] +---- +<configuration debug="true"> +... +</configuration> +---- + diff --git a/src/site-docs/adoc/fragments/howto-logging/logging-3pps.adoc b/src/site-docs/adoc/fragments/howto-logging/logging-3pps.adoc new file mode 100644 index 000000000..be2b9af38 --- /dev/null +++ b/src/site-docs/adoc/fragments/howto-logging/logging-3pps.adoc @@ -0,0 +1,37 @@ +// +// ============LICENSE_START======================================================= +// Copyright (C) 2016-2018 Ericsson. All rights reserved. +// ================================================================================ +// This file is licensed under the CREATIVE COMMONS ATTRIBUTION 4.0 INTERNATIONAL LICENSE +// Full license text at https://creativecommons.org/licenses/by/4.0/legalcode +// +// SPDX-License-Identifier: CC-BY-4.0 +// ============LICENSE_END========================================================= +// +// @author Sven van der Meer (sven.van.der.meer@ericsson.com) +// + +== Logging External Components + +Logback can also be configured to log any other, external components APEX is using, if they are using the common logging framework. + +For instance, the context component of APEX is using __Infinispan__ and one can add a logger for this external component. +The following example adds a logger for __Infinispan__ using the standard output appender. + +[source%nowrap,xml] +---- +<logger name="org.infinispan" level="INFO" additivity="false"> + <appender-ref ref="STDOUT" /> +</logger> +---- + +Another example is Apache Zookeeper. +The following example adds a logger for Zookeeper using the standard outout appender. + +[source%nowrap,xml] +---- +<logger name="org.apache.zookeeper.ClientCnxn" level="INFO" additivity="false"> + <appender-ref ref="STDOUT" /> +</logger> +---- + diff --git a/src/site-docs/adoc/fragments/howto-logging/logging-policy-logic.adoc b/src/site-docs/adoc/fragments/howto-logging/logging-policy-logic.adoc new file mode 100644 index 000000000..779e45458 --- /dev/null +++ b/src/site-docs/adoc/fragments/howto-logging/logging-policy-logic.adoc @@ -0,0 +1,54 @@ +// +// ============LICENSE_START======================================================= +// Copyright (C) 2016-2018 Ericsson. All rights reserved. +// ================================================================================ +// This file is licensed under the CREATIVE COMMONS ATTRIBUTION 4.0 INTERNATIONAL LICENSE +// Full license text at https://creativecommons.org/licenses/by/4.0/legalcode +// +// SPDX-License-Identifier: CC-BY-4.0 +// ============LICENSE_END========================================================= +// +// @author Sven van der Meer (sven.van.der.meer@ericsson.com) +// + +== Configuring loggers for Policy Logic + +The logging for the logic inside a policy (task logic, task selection logic, state finalizer logic) can be configured separate from standard logging. +The logger for policy logic is `org.onap.policy.apex.executionlogging`. +The following example defines + +- a new appender for policy logic logging to standard out using a very simple pattern (simply the actual message) +- a logger for policy logic to standard out using the new appender +- a logger for policy logic to the standard `FILE` appender + +[source%nowrap,xml] +---- +<appender name="POLICY_APPENDER_STDOUT" class="ch.qos.logback.core.ConsoleAppender"> + <encoder> + <pattern>policy: %msg\n</pattern> + </encoder> +</appender> + +<appender name="POLICY_APPENDER_STDOUT" class="ch.qos.logback.core.ConsoleAppender"> + <encoder> + <pattern>policy: %msg\n</pattern> + </encoder> +</appender> + +<logger name="org.onap.policy.apex.executionlogging" level="info" additivity="false"> + <appender-ref ref="POLICY_APPENDER_STDOUT" /> + <appender-ref ref="FILE" /> +</logger> + +---- + +It is also possible to use specific logging for parts of policy logic. +The following example defines a logger for task logic. + +[source%nowrap,xml] +---- +<logger name="org.onap.policy.apex.executionlogging.TaskExecutionLogging" level="TRACE" additivity="false"> + <appender-ref ref="STDOUT" /> +</logger> +---- + diff --git a/src/site-docs/adoc/fragments/howto-logging/rolling-file-appenders.adoc b/src/site-docs/adoc/fragments/howto-logging/rolling-file-appenders.adoc new file mode 100644 index 000000000..68a6d1cba --- /dev/null +++ b/src/site-docs/adoc/fragments/howto-logging/rolling-file-appenders.adoc @@ -0,0 +1,71 @@ +// +// ============LICENSE_START======================================================= +// Copyright (C) 2016-2018 Ericsson. All rights reserved. +// ================================================================================ +// This file is licensed under the CREATIVE COMMONS ATTRIBUTION 4.0 INTERNATIONAL LICENSE +// Full license text at https://creativecommons.org/licenses/by/4.0/legalcode +// +// SPDX-License-Identifier: CC-BY-4.0 +// ============LICENSE_END========================================================= +// +// @author Sven van der Meer (sven.van.der.meer@ericsson.com) +// + +== Rolling File Appenders + +Rolling file appenders are a good option for more complex logging of a production or complex testing APEX installation. +The standard logback configuration can be used for these use cases. +This section gives two examples for the standard logging and for context logging. + +First the standard logging. +The following example defines a rolling file appender. +The appender rolls over on a daily basis. +It allows for a file size of 100 MB. + +[source%nowrap,xml] +---- +<appender name="FILE" class="ch.qos.logback.core.rolling.RollingFileAppender"> + <file>${VAR_LOG}/apex.log</file> + <rollingPolicy class="ch.qos.logback.core.rolling.TimeBasedRollingPolicy"> + <!-- rollover daily --> + <!-- <fileNamePattern>xstream-%d{yyyy-MM-dd}.%i.txt</fileNamePattern> --> + <fileNamePattern>${VAR_LOG}/apex_%d{yyyy-MM-dd}.%i.log.gz + </fileNamePattern> + <maxHistory>4</maxHistory> + <timeBasedFileNamingAndTriggeringPolicy class="ch.qos.logback.core.rolling.SizeAndTimeBasedFNATP"> + <!-- or whenever the file size reaches 100MB --> + <maxFileSize>100MB</maxFileSize> + </timeBasedFileNamingAndTriggeringPolicy> + </rollingPolicy> + <encoder> + <pattern> + %d %-5relative [procId=${processId}] [%thread] %-5level %logger{26} - %msg %ex{full} %n + </pattern> + </encoder> +</appender> +---- + +A very similar configuration can be used for a rolling file appender logging APEX context. + +[source%nowrap,xml] +---- +<appender name="CTXT-FILE" + class="ch.qos.logback.core.rolling.RollingFileAppender"> + <file>${VAR_LOG}/apex_ctxt.log</file> + <rollingPolicy class="ch.qos.logback.core.rolling.TimeBasedRollingPolicy"> + <fileNamePattern>${VAR_LOG}/apex_ctxt_%d{yyyy-MM-dd}.%i.log.gz + </fileNamePattern> + <maxHistory>4</maxHistory> + <timeBasedFileNamingAndTriggeringPolicy + class="ch.qos.logback.core.rolling.SizeAndTimeBasedFNATP"> + <maxFileSize>100MB</maxFileSize> + </timeBasedFileNamingAndTriggeringPolicy> + </rollingPolicy> + <encoder> + <pattern> + %d %-5relative [procId=${processId}] [%thread] %-5level %logger{26} - %msg %ex{full} %n + </pattern> + </encoder> +</appender> +---- + diff --git a/src/site-docs/adoc/fragments/howto-logging/standard-configuration.adoc b/src/site-docs/adoc/fragments/howto-logging/standard-configuration.adoc new file mode 100644 index 000000000..a09b3d27e --- /dev/null +++ b/src/site-docs/adoc/fragments/howto-logging/standard-configuration.adoc @@ -0,0 +1,96 @@ +// +// ============LICENSE_START======================================================= +// Copyright (C) 2016-2018 Ericsson. All rights reserved. +// ================================================================================ +// This file is licensed under the CREATIVE COMMONS ATTRIBUTION 4.0 INTERNATIONAL LICENSE +// Full license text at https://creativecommons.org/licenses/by/4.0/legalcode +// +// SPDX-License-Identifier: CC-BY-4.0 +// ============LICENSE_END========================================================= +// +// @author Sven van der Meer (sven.van.der.meer@ericsson.com) +// + +== Standard Logging Configuration + +The standard logging configuration defines a context __APEX__, which is used in the standard output pattern. +The location for log files is defined in the property `VAR_LOG` and set to `/var/log/apex`. +The standard status listener is set to __NOP__ and the overall logback configuration is set to no debug. + +[source%nowrap,xml,numbered] +---- +<configuration debug="false"> + <statusListener class="ch.qos.logback.core.status.NopStatusListener" /> + + <contextName>Apex</contextName> + <property name="VAR_LOG" value="/var/log/ericsson/apex/" /> + + ...appenders + ...loggers +</configuration> +---- + +The first appender defined is called `STDOUT` for logs to standard out. + +[source%nowrap,xml,numbered] +---- +<appender name="STDOUT" class="ch.qos.logback.core.ConsoleAppender"> + <encoder> + <Pattern>%d %contextName [%t] %level %logger{36} - %msg%n</Pattern> + </encoder> +</appender> +---- + +The root level logger then is set to the level __info__ using the standard out appender. +[source%nowrap,xml,numbered] +---- +<root level="info"> + <appender-ref ref="STDOUT" /> +</root> +---- + +The first appender is called `FILE`. +It writes logs to a file `apex.log`. +[source%nowrap,xml,numbered] +---- +<appender name="FILE" class="ch.qos.logback.core.FileAppender"> + <file>${VAR_LOG}/apex.log</file> + <encoder> + <pattern> + %d %-5relative [procId=${processId}] [%thread] %-5level%logger{26} - %msg %n %ex{full} + </pattern> + </encoder> +</appender> +---- + +The first appender is called `CTXT_FILE`. +It writes logs to a file `apex_ctxt.log`. +[source%nowrap,xml,numbered] +---- +<appender name="CTXT_FILE" class="ch.qos.logback.core.FileAppender"> + <file>${VAR_LOG}/apex_ctxt.log</file> + <encoder> + <pattern> + %d %-5relative [procId=${processId}] [%thread] %-5level%logger{26} - %msg %n %ex{full} + </pattern> + </encoder> +</appender> +---- + +The last definitions are for specific loggers. +The first logger captures all standard APEX classes, appends logs to `STDOUT` with the log level __info__. +The second logger capture all standard APEX classes, appends logs to `FILE` with log level __info__. +The third logger captures context monitoring classes, appends logs to `CTXT_FILE` with log level __trace__. + +[source%nowrap,xml,numbered] +---- +<logger name="org.onap.policy.apex" level="info" additivity="false"> + <appender-ref ref="STDOUT" /> + <appender-ref ref="FILE" /> +</logger> + +<logger name="org.onap.policy.apex.core.context.monitoring" level="TRACE" additivity="false"> + <appender-ref ref="CTXT_FILE" /> +</logger> +---- + |