feature/cli-runner - Update logging info in C++ and Python SDK docs. (#120)

* Update logging info in C++ and Python SDK docs.

Author: brosenberg42

docs/docs/CPP-Batch-Component-API.md

@@ -140,7 +140,6 @@ string GetRunDirectory()
 string run_dir = GetRunDirectory();
 string plugin_path = run_dir + "/SampleComponent";
 string config_path = plugin_path + "/config";
-string logconfig_file = config_path + "/Log4cxxConfig.xml";
 ```
 
 ### Init()
@@ -1051,7 +1050,7 @@ It is recommended that C++ components are organized according to the following d
 
 ```
 componentName
-├── config - Logging and other component-specific configuration
+├── config - Optional component-specific configuration files
 ├── descriptor
 │   └── descriptor.json
 └── lib
@@ -1062,41 +1061,25 @@ Once built, components should be packaged into a .tar.gz containing the contents
 
 
 ## Logging
+It is recommended to use [Apache log4cxx](https://logging.apache.org/log4cxx/index.html) for 
+OpenMPF Component logging. Components using log4cxx should not configure logging themselves. 
+The component executor will configure log4cxx globally. Components should call 
+`log4cxx::Logger::getLogger("<componentName>")` to a get a reference to the logger. If you 
+are using a different logging framework, you should make sure its behavior is similar to how
+the component executor configures log4cxx as described below. 
 
-It is recommended to use [Apache log4cxx](https://logging.apache.org/log4cxx/index.html) for OpenMPF Component logging.
+The following log LEVELs are supported: `FATAL, ERROR, WARN,  INFO,  DEBUG, TRACE`.
+The `LOG_LEVEL` environment variable can be set to one of the log levels to change the logging 
+verbosity. When `LOG_LEVEL` is absent, `INFO` is used.
 
-Note that multiple instances of the same component can log to the same file. Also, logging content can span multiple lines.
+Note that multiple instances of the same component can log to the same file. 
+Also, logging content can span multiple lines.
 
-Log files should be output to:
-`${MPF_LOG_PATH}/${THIS_MPF_NODE}/log/<componentName>.log`
+The logger will write to both standard error and 
+`${MPF_LOG_PATH}/${THIS_MPF_NODE}/log/<componentName>.log`.
 
-Each log statement must take the form:
+Each log statement will take the form:
 `DATE TIME LEVEL CONTENT`
 
-The following log LEVELs are supported:
-`FATAL, ERROR, WARN,  INFO,  DEBUG, TRACE`.
-
 For example:
 `2016-02-09 13:42:42,341 INFO - Starting sample-component: [  OK  ]`
-
-The following configuration can be used to match the format of other OpenMPF logs:
-
-```xml
-<log4j:configuration xmlns:log4j="http://jakarta.apache.org/log4j/">
-
-  <!-- Output the log message to log file-->
-  <appender name="SAMPLECOMPONENT-FILE" class="org.apache.log4j.DailyRollingFileAppender">
-    <param name="file" value="${MPF_LOG_PATH}/${THIS_MPF_NODE}/log/<componentName>.log" />
-    <param name="DatePattern" value="'.'yyyy-MM-dd" />
-    <layout class="org.apache.log4j.PatternLayout">
-      <param name="ConversionPattern" value="%d %p [%t] %c{36}:%L - %m%n" />
-    </layout>
-  </appender>
-
-  <logger name= "SampleComponent" additivity="false">
-    <level value="INFO"/>
-    <appender-ref ref="SAMPLECOMPONENT-FILE"/>
-  </logger>
-
-</log4j:configuration>
-```

docs/docs/CPP-Streaming-Component-API.md

@@ -137,7 +137,7 @@ MPFStreamingDetectionComponent(const MPFStreamingVideoJob &job)
 ```c++
 SampleComponent::SampleComponent(const MPFStreamingVideoJob &job)
         : MPFStreamingDetectionComponent(job)
-        , hw_logger_(GetLogger(job.run_directory))
+        , hw_logger_(log4cxx::Logger::getLogger("SampleComponent"))
         , job_name_(job.job_name) {
 
     LOG4CXX_INFO(hw_logger_, "[" << job_name_ << "] Initialized SampleComponent component.")
@@ -430,7 +430,7 @@ It is recommended that C++ components are organized according to the following d
 
 ```
 componentName
-├── config - Logging and other component-specific configuration
+├── config - Component-specific configuration files
 ├── descriptor
 │   └── descriptor.json
 └── lib
@@ -441,41 +441,25 @@ Once built, components should be packaged into a .tar.gz containing the contents
 
 
 ## Logging
+It is recommended to use [Apache log4cxx](https://logging.apache.org/log4cxx/index.html) for 
+OpenMPF Component logging. Components using log4cxx should not configure logging themselves. 
+The component executor will configure log4cxx globally. Components should call 
+`log4cxx::Logger::getLogger("<componentName>")` to a get a reference to the logger. If you 
+are using a different logging framework, you should make sure its behavior is similar to how
+the component executor configures log4cxx as described below. 
 
-It is recommended to use [Apache log4cxx](https://logging.apache.org/log4cxx/index.html) for OpenMPF Component logging.
+The following log LEVELs are supported: `FATAL, ERROR, WARN,  INFO,  DEBUG, TRACE`.
+The `LOG_LEVEL` environment variable can be set to one of the log levels to change the logging 
+verbosity. When `LOG_LEVEL` is absent, `INFO` is used.
 
-Note that multiple instances of the same component can log to the same file. Also, logging content can span multiple lines.
+Note that multiple instances of the same component can log to the same file. 
+Also, logging content can span multiple lines.
 
-Log files should be output to:
-`${MPF_LOG_PATH}/${THIS_MPF_NODE}/log/<componentName>.log`
+The logger will write to both standard error and 
+`${MPF_LOG_PATH}/${THIS_MPF_NODE}/log/<componentName>.log`.
 
-Each log statement must take the form:
+Each log statement will take the form:
 `DATE TIME LEVEL CONTENT`
 
-The following log LEVELs are supported:
-`FATAL, ERROR, WARN,  INFO,  DEBUG, TRACE`.
-
 For example:
 `2016-02-09 13:42:42,341 INFO - Starting sample-component: [  OK  ]`
-
-The following configuration can be used to match the format of other OpenMPF logs:
-
-```xml
-<log4j:configuration xmlns:log4j="http://jakarta.apache.org/log4j/">
-
-  <!-- Output the log message to log file-->
-  <appender name="SAMPLECOMPONENT-FILE" class="org.apache.log4j.DailyRollingFileAppender">
-    <param name="file" value="${MPF_LOG_PATH}/${THIS_MPF_NODE}/log/<componentName>.log" />
-    <param name="DatePattern" value="'.'yyyy-MM-dd" />
-    <layout class="org.apache.log4j.PatternLayout">
-      <param name="ConversionPattern" value="%d %p [%t] %c{36}:%L - %m%n" />
-    </layout>
-  </appender>
-
-  <logger name= "SampleComponent" additivity="false">
-    <level value="INFO"/>
-    <appender-ref ref="SAMPLECOMPONENT-FILE"/>
-  </logger>
-
-</log4j:configuration>
-```

docs/docs/Python-Batch-Component-API.md

@@ -221,12 +221,14 @@ Below is an example of the structure of a simple component. This component exten
 [`mpf_component_util.VideoCapture`](#mpf_component_utilvideocapture). You would replace the call to
 `run_detection_algorithm_on_frame` with your component-specific logic.
 ```python
+import logging
+
 import mpf_component_api as mpf
 import mpf_component_util as mpf_util
 
-logger = mpf.configure_logging('my-component.log', __name__ == '__main__')
+logger = logging.getLogger('MyComponent')
 
-class MyComponent(mpf_util.VideoCaptureMixin, object):
+class MyComponent(mpf_util.VideoCaptureMixin):
     detection_type = 'FACE'
 
     @staticmethod
@@ -314,11 +316,11 @@ Below is an example of the structure of a simple component that does not use
 [`mpf_component_util.VideoCaptureMixin`](#mpf_component_utilvideocapturemixin). You would replace the call to
 `run_detection_algorithm` with your component-specific logic.
 ```python
-import mpf_component_api as mpf
+import logging
 
-logger = mpf.configure_logging('my-component.log', __name__ == '__main__')
+logger = logging.getLogger('MyComponent')
 
-class MyComponent(object):
+class MyComponent:
     detection_type = 'FACE'
 
     @staticmethod
@@ -368,22 +370,22 @@ For example:
 
 instance method:
 ```python
-class MyComponent(object):
+class MyComponent:
     def get_detections_from_image(self, image_job):
         return [mpf_component_api.ImageLocation(...), ...]
 ```
 
 static method:
 ```python
-class MyComponent(object):
+class MyComponent:
     @staticmethod
     def get_detections_from_image(image_job):
         return [mpf_component_api.ImageLocation(...), ...]
 ```
 
 class method:
 ```python
-class MyComponent(object):
+class MyComponent:
     @classmethod
     def get_detections_from_image(cls, image_job):
         return [mpf_component_api.ImageLocation(...), ...]
@@ -399,7 +401,7 @@ but any iterable can be used.
 Examples include: `FACE`, `MOTION`, `PERSON`, `SPEECH`, `CLASS` (for object classification), or `TEXT`.
 * Example:
 ```python
-class MyComponent(object):
+class MyComponent:
     detection_type = 'FACE'
 
 ```
@@ -413,7 +415,7 @@ Used to detect objects in an image file.
 
 * Method Definition:
 ```python
-class MyComponent(object):
+class MyComponent:
     def get_detections_from_image(self, image_job):
         return [mpf_component_api.ImageLocation(...), ...]
 ```
@@ -548,7 +550,7 @@ cannot automatically perform the reverse transform for the developer.
 
 The general pattern for using `mpf_component_util.ImageReader` is as follows:
 ```python
-class MyComponent(object):
+class MyComponent:
 
     @staticmethod
     def get_detections_from_image(image_job):
@@ -583,7 +585,7 @@ There are some requirements to properly use `mpf_component_util.ImageReaderMixin
 
 The general pattern for using `mpf_component_util.ImageReaderMixin` is as follows:
 ```python
-class MyComponent(mpf_component_util.ImageReaderMixin, object):
+class MyComponent(mpf_component_util.ImageReaderMixin):
 
     @staticmethod # Can also be a regular instance method or a class method
     def get_detections_from_image_reader(image_job, image_reader):
@@ -612,7 +614,7 @@ request for frames 300-399 of a Video A, while the next request may cover frames
 
 * Method Definition:
 ```python
-class MyComponent(object):
+class MyComponent:
     def get_detections_from_video(self, video_job):
         return [mpf_component_api.VideoTrack(...), ...]
 ```
@@ -767,7 +769,7 @@ cannot automatically perform the reverse transform for the developer.
 
 The general pattern for using `mpf_component_util.VideoCapture` is as follows:
 ```python
-class MyComponent(object):
+class MyComponent:
 
     @staticmethod
     def get_detections_from_video(video_job):
@@ -804,7 +806,7 @@ There are some requirements to properly use `mpf_component_util.VideoCaptureMixi
 
 The general pattern for using `mpf_component_util.VideoCaptureMixin` is as follows:
 ```python
-class MyComponent(mpf_component_util.VideoCaptureMixin, object):
+class MyComponent(mpf_component_util.VideoCaptureMixin):
 
     @staticmethod # Can also be a regular instance method or a class method
     def get_detections_from_video_capture(video_job, video_capture):
@@ -824,7 +826,7 @@ from extending other classes. If a component supports both videos and images, an
 [`mpf_component_util.ImageReaderMixin`](#mpf_component_utilimagereadermixin).
 For example:
 ```python
-class MyComponent(mpf_component_util.VideoCaptureMixin, mpf_component_util.ImageReaderMixin, object):
+class MyComponent(mpf_component_util.VideoCaptureMixin, mpf_component_util.ImageReaderMixin):
 
     @staticmethod
     def get_detections_from_video_capture(video_job, video_capture):
@@ -845,7 +847,7 @@ Used to detect objects in an audio file.
 
 * Method Definition:
 ```python
-class MyComponent(object):
+class MyComponent:
     def get_detections_from_audio(self, audio_job):
         return [mpf_component_api.AudioTrack(...), ...]
 ```
@@ -970,7 +972,7 @@ handled generically.
 
 * Method Definition:
 ```python
-class MyComponent(object):
+class MyComponent:
     def get_detections_from_generic(self, generic_job):
         return [mpf_component_api.GenericTrack(...), ...]
 ```
@@ -1190,11 +1192,17 @@ OpenMPF components should be stateless in operation and give identical output fo
 
 
 ## Logging
-It recommended that components use the logger returned from:
-<br> `mpf_component_api.configure_logging(log_file_name, debug=False, replace_existing_config=True)`. 
-The logger will write log messages to standard out. When `debug` is false, the log messages will also be written to `${MPF_LOG_PATH}/${THIS_MPF_NODE}/log/<log_file_name>.log` Note that multiple instances of the same component 
-can log to the same file. Also, logging content can span multiple lines. The following log levels are supported: 
-`FATAL, ERROR, WARN, INFO, DEBUG`.
+It recommended that components use Python's built-in 
+[`logging` module.](https://docs.python.org/3/library/logging.html) The component should 
+`import logging` and call `logging.getLogger('<componentName>')` to get a logger instance. 
+The component should not configure logging itself. The component executor will configure the 
+`logging` module for the component. The logger will write log messages to standard error and 
+`${MPF_LOG_PATH}/${THIS_MPF_NODE}/log/<componentName>.log`. Note that multiple instances of the 
+same component can log to the same file. Also, logging content can span multiple lines. 
+
+The following log levels are supported: `FATAL, ERROR, WARN, INFO, DEBUG`. 
+The `LOG_LEVEL` environment variable can be set to one of the log levels to change the logging 
+verbosity. When `LOG_LEVEL` is absent, `INFO` is used.
 
 The format of the log messages is:
 ```

docs/docs/Release-Notes.md

@@ -1,5 +1,45 @@
 > **NOTICE:** This software (or technical data) was produced for the U.S. Government under contract, and is subject to the Rights in Data-General Clause 52.227-14, Alt. IV (DEC 2007). Copyright 2021 The MITRE Corporation. All Rights Reserved.
 
+# OpenMPF TBD: XXX
+
+<h2>OpenMPF Command Line Runner</h2>
+
+- The Command Line Runner allows users to run jobs with a single component without the 
+  Workflow Manager.
+- It outputs results in a JSON structure that is a subset of the regular OpenMPF output.
+- It only supports C++ and Python components.
+- See the 
+  [README](https://github.com/openmpf/openmpf-docker/blob/master/CLI_RUNNER.md)
+  for more information.
+
+<h2>C++ Batch Component API</h2>
+- Component code should no longer configure Log4CXX. The component executor now handles
+  configuring Log4CXX. Component code should call `log4cxx::Logger::getLogger("<component-name>")`
+  to get access to the logger. Calls to `log4cxx::xml::DOMConfigurator::configure(logconfig_file);`
+  should be removed.
+
+
+<h2>Python Batch Component API </h2>
+- Component code should no longer configure logging. The component executor now handles
+  configuring logging. Calls to `mpf.configure_logging` should be replaced with
+  `logging.getLogger('<component-name>')`.
+
+
+<h2>Docker Component Base Images</h2>
+- In order to support running a component through the CLI runner, C++ component developers should
+  set the `LD_LIBRARY_PATH` environment variable in the final stage of their Dockerfiles. It should
+  generally be set like: `ENV LD_LIBRARY_PATH $PLUGINS_DIR/<component-name>/lib`.
+
+- Because of the logging changes mentioned above, components no longer need to set the
+  `COMPONENT_LOG_NAME` environment variable in their Dockerfiles.
+
+- Added the 
+  [`openmpf_python_executor_ssb` base image](https://github.com/openmpf/openmpf-docker/blob/master/components/python/README.md#openmpf_python_executor_ssb). 
+  It can be used instead of `openmpf_python_component_build` and `openmpf_python_executor` to 
+  simplify Dockerfiles for Python components that are pure Python and have no build time 
+  dependencies.
+
+
 # OpenMPF 6.0.1: December 2020
 
 <h2>Bug Fixes</h2>

docs/docs/User-Guide.md

@@ -5,11 +5,18 @@ Copyright 2021 The MITRE Corporation. All Rights Reserved.
 
 # General
 
+The Open Media Processing Framework (OpenMPF) can be used in three ways:
+
+* Through the OpenMPF Web user interface (UI)
+* Through the [REST API endpoints](#rest-api)
+* Through the [CLI Runner](https://github.com/openmpf/openmpf-docker/blob/master/CLI_RUNNER.md)
+
+
 ## Accessing the Web UI
 
-On the server hosting the Open Media Processing Framework (OpenMPF), the Web UI is accessible at http://localhost:8080/workflow-manager. To access it from other machines, substitute the hostname or IP address of the master node server in place of "localhost".
+On the server hosting the Open Media Processing Framework, the Web UI is accessible at http://localhost:8080/workflow-manager. To access it from other machines, substitute the hostname or IP address of the master node server in place of "localhost".
 
-The OpenMPF user interface (UI) was designed and tested for use with Chrome and FireFox. It has not been tested with other browsers. Attempting to use an unsupported browser will result in a warning.
+The OpenMPF user interface was designed and tested for use with Chrome and FireFox. It has not been tested with other browsers. Attempting to use an unsupported browser will result in a warning.
 
 ## Logging In
 
@@ -190,7 +197,7 @@ The "Processes" tab on this page allows a user to view a table with information
 
 ## REST API
 
-This page allows a user to try out the various REST API endpoints provided by the workflow manager. It is intended to serve as a learning tool for technical users who wish to design and build systems that interact with the OpenMPF.
+This page allows a user to try out the [various REST API endpoints](REST-API) provided by the workflow manager. It is intended to serve as a learning tool for technical users who wish to design and build systems that interact with the OpenMPF.
 
 After selecting a functional category, such as "meta", "jobs", "statistics", "nodes", "pipelines", or "system-message", each REST endpoint for that category is shown in a list. Selecting one of them will cause it to expand and reveal more information about the request and response structures. If the request takes any parameters then a section will appear that allows the user to manually specify them.