Merge pull request #240 from pdowler/master

cadc-log: hard code cadc-log.properties config file

cadc-log/README.md

@@ -1,10 +1,49 @@
 # cadc-log
 
-The `cadc-log` library provides a single servlet to initialize logging using
-the log4j framework. The idea is to include this servlet in the web.xml with
-`load-on-startup` of 1 (first) and configure standard logging there.
+The `cadc-log` library provides a single servlet to initialize logging using the log4j framework. 
 
-It is highly recommended that the default log level in web.xml be at `info` level.
+## REST API
+Services may include `servlet-mapping` so that HTTP GET and POST requests can
+be sent to the log control endpoint. All services in OpenCADC use `/logControl`
+for consistency but this is not required. Permission to access the log control
+endpoint are configured with a `cadc-log.properties` file at runtime.
+
+## cadc-log.properties (optional)
+
+This file can be added to service config to grant perrmission to use the LogControlServlet at runtime.
+```properties
+user = {X509 distinguished name}
+user = {X509 distinguished name}
+
+group = {IVOA GMS group identifier}
+group = {IVOA GMS group identifier}
+```
+Both the `user` and `group` properties are optional and support multiple values. The specified
+users are granted permission to view (GET) and change (POST) log levels in the running service.
+
+## log control REST API
+
+This is a very simple explanation; TODO: document with OpenAI so it can be included in service API docs.
+
+view current log levels: `GET {base URL}/logControl`
+
+change current log levels to debug: `POST level=DEBUG {base URL}/logControl`
+
+change log levels back to info: `POST level=INFO {base URL}/logControl`
+
+change log to debug for a specific package (prefix): `POST level=DEBUG&package=ca.nrc.cadc.auth {base URL}/logControl`
+
+The `package` parameter can add new packages to the logging config that were not included by the service. These
+packages become "tracked" and are subject to later log level changes that change the level for all packages. If 
+the caller does not want that package to be tracked, they can include `notrack=1` to prevent and retain manual 
+control. 
+
+All changes to logging (level and tracked packages are lost if the service is restarted.
+
+## developer usage
+Developers include this servlet in the web.xml with `load-on-startup` of 1 (first) 
+and configure standard logging there. It is highly recommended that the default log 
+level in web.xml be at `info` level.
 
 Example:
 ```xml
@@ -18,51 +57,22 @@ Example:
     <init-param>
       <param-name>logLevelPackages</param-name>
       <param-value>
-      <!-- whitespace separated list of packages for INFO level -->
+        <!-- whitespace separated list of packages for INFO level -->
         ca.nrc.cadc.auth
         ca.nrc.cadc.net
         ca.nrc.cadc.vosi
-        ca.nrc.cadc.db
       </param-value>
     </init-param>
-    <!-- optional hard coded group permission -->
-    <init-param>
-        <param-name>logAccessGroup</param-name>
-        <param-value>ivo://cadc.nrc.ca/gms?CADC</param-value>
-    </init-param>
-    <init-param>
-        <param-name>groupAuthorizer</param-name>
-        <param-value>ca.nrc.cadc.ac.client.GroupAuthorizer</param-value>
-    </init-param>
-    <!-- optional runtime user and group permissions -->
-    <init-param>
-        <param-name>logControlProperties</param-name>
-        <param-value>example-logControl.properties</param-value>
-    </init-param>
     <load-on-startup>1</load-on-startup>
 </servlet>
+
+<!-- optional servlet mapping to expose REST API -->
+<servlet-mapping>
+    <servlet-name>logControl</servlet-name>
+    <url-pattern>/logControl</url-pattern>
+</servlet-mapping>
 ```
 The servlet will configure a default logging at `warn` level and the specified packages at
 `info` level.
 
-The LogControlServlet supports GET and POST requests to view and change the current log levels and/or
-configured packages. This requires permission using either of the optional init params in the example
-above. The latter runtime configuration of permissions is preferred because then configuration ends 
-up in the config dir instead of hard coded inside the application (war file).
-
-## example-logControl.properties
 
-This file allows granting permission to use the LogControlServlet at runtime.
-```properties
-user = {X509 distinguished name}
-user = {X509 distinguished name}
-
-group = {IVOA GMS group identifier}
-group = {IVOA GMS group identifier}
-```
-Both the `user` and `group` properties are optional and support multiple values. The simplest example 
-used at CADC is:
-```properties
-group = ivo://cadc.nrc.ca/gms?CADC
-```
-which allows members of the CADC staff group to view and change log levels.

cadc-log/build.gradle

@@ -14,7 +14,7 @@ sourceCompatibility = 1.8
 
 group = 'org.opencadc'
 
-version = '1.1.7'
+version = '1.2.0'
 
 description = 'OpenCADC Logging Init server library'
 def git_url = 'https://github.com/opencadc/core'
@@ -24,9 +24,6 @@ dependencies {
     compile 'org.opencadc:cadc-util:[1.6,2.0)'
     compile 'org.opencadc:cadc-gms:[1.0,2.0)'
     compile 'org.opencadc:cadc-cdp:[1.3,2.0)'
-
-    testCompile 'junit:junit:4.13'
-    testCompile 'org.easymock:easymock:3.6'
 }
 
 apply from: '../opencadc.gradle'

cadc-log/scripts/cadc-log-set

@@ -0,0 +1,91 @@
+#!/bin/bash
+
+## dynamically set the log level of a web service
+CURL="curl -v --cert $HOME/.ssl/cadcproxy.pem"
+#CURL="curl -n"
+
+function usage() {
+    echo "usage cadc-log-set --get <URL>"
+    echo "      cadc-log-set --set <URL> <level> [<package> [notrack]]"
+    echo ""
+    echo "     --get : get current log config"
+    echo "     --set : set log config"
+    echo "     URL   : URL to the LogControl resource (e.g. https://localhost/srv/logControl)"
+    echo "     level : ERROR, WARN, INFO, DEBUG"
+    echo "   package : (optional) package name (default: all currently configured packages get the specified level)"
+    echo "   notrack : (optional) disable further tracking of this package"
+    echo ""
+    echo "Examples:"
+    echo ""
+    echo "1. increase log level of all configured packages to DEBUG:"
+    echo "    cadcLogSet --set https://myServer/myApp/myLogControlServlet DEBUG"
+    echo ""
+    echo "2. increase log level of a specific package to DEBUG (adds it to list of configured packages):"
+    echo "    cadcLogSet --set https://myServer/myApp/myLogControlServlet DEBUG my.package"
+    echo ""
+    echo "3. change log level of a specific package but not add it to list as in Example 1 and 2:"
+    echo "    cadcLogSet --set https://myServer/myApp/myLogControlServlet INFO some.other.package notrack"
+    echo ""
+    echo "4. enable the Profiler class (recommend: notrack):"
+    echo "    cadcLogSet --set https://myServer/myApp/myLogControlServlet INFO ca.nrc.cadc.profiler notrack"
+    echo ""
+    echo "5. disable the Profiler class (recommend: notrack):"
+    echo "    cadcLogSet --set https://myServer/myApp/myLogControlServlet ERROR ca.nrc.cadc.profiler notrack"
+}
+
+## command-line args
+ACTION=$1
+URL=$2
+LEVEL=$3
+PKG=$4
+DNT=$5
+
+if [ -z $ACTION ]; then
+    usage
+    exit 1
+fi
+
+if [ -z $URL ]; then
+    echo "error: missing URL"
+    usage
+    exit 1
+fi
+
+if [ $ACTION == "--get" ]; then
+    if [ ! -z $LEVEL ]; then
+        echo "error: extra arguments not usable by --get: $LEVEL $PKG"
+        usage
+        exit 1
+    fi
+elif [ $ACTION == "--set" ]; then
+    if [ -z $LEVEL ]; then
+        echo "error: missing level"
+        usage
+        exit 1
+    fi
+
+    CONTENT="level=$LEVEL"
+
+    if [ ! -z $PKG ]; then
+        CONTENT="${CONTENT}&package=${PKG}"
+        if [ ! -z $DNT ]; then
+            if [ $DNT == "notrack" ]; then
+                CONTENT="${CONTENT}&notrack=1"
+            fi
+        fi
+    fi
+else
+    usage
+    exit 1
+fi
+
+
+## end: command-line args
+
+if [ $ACTION == "--get" ]; then
+    $CURL $URL
+    exit $?
+elif [ $ACTION == "--set" ]; then
+    $CURL -d "${CONTENT}" $URL
+    exit $?
+fi