You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@knox.apache.org by mo...@apache.org on 2017/09/05 15:45:56 UTC
svn commit: r1807366 - in /knox: site/ site/books/knox-0-10-0/
site/books/knox-0-11-0/ site/books/knox-0-12-0/ site/books/knox-0-13-0/
site/books/knox-0-4-0/ site/books/knox-0-5-0/ site/books/knox-0-6-0/
site/books/knox-0-7-0/ site/books/knox-0-8-0/ si...
Author: more
Date: Tue Sep 5 15:45:55 2017
New Revision: 1807366
URL: http://svn.apache.org/viewvc?rev=1807366&view=rev
Log:
KNOX-953 - Document KNOX health metrics REST API (Mohammad Kamrul Islam via Sandeep More)
Added:
knox/trunk/books/0.13.0/dev-guide/knox_monitoring_api.md
Modified:
knox/site/books/knox-0-10-0/deployment-overview.png
knox/site/books/knox-0-10-0/deployment-provider.png
knox/site/books/knox-0-10-0/deployment-service.png
knox/site/books/knox-0-10-0/general_saml_flow.png
knox/site/books/knox-0-10-0/runtime-overview.png
knox/site/books/knox-0-10-0/runtime-request-processing.png
knox/site/books/knox-0-11-0/deployment-overview.png
knox/site/books/knox-0-11-0/deployment-provider.png
knox/site/books/knox-0-11-0/deployment-service.png
knox/site/books/knox-0-11-0/general_saml_flow.png
knox/site/books/knox-0-11-0/runtime-overview.png
knox/site/books/knox-0-11-0/runtime-request-processing.png
knox/site/books/knox-0-12-0/deployment-overview.png
knox/site/books/knox-0-12-0/deployment-provider.png
knox/site/books/knox-0-12-0/deployment-service.png
knox/site/books/knox-0-12-0/general_saml_flow.png
knox/site/books/knox-0-12-0/runtime-overview.png
knox/site/books/knox-0-12-0/runtime-request-processing.png
knox/site/books/knox-0-13-0/deployment-overview.png
knox/site/books/knox-0-13-0/deployment-provider.png
knox/site/books/knox-0-13-0/deployment-service.png
knox/site/books/knox-0-13-0/dev-guide.html
knox/site/books/knox-0-13-0/general_saml_flow.png
knox/site/books/knox-0-13-0/runtime-overview.png
knox/site/books/knox-0-13-0/runtime-request-processing.png
knox/site/books/knox-0-4-0/deployment-overview.png
knox/site/books/knox-0-4-0/deployment-provider.png
knox/site/books/knox-0-4-0/deployment-service.png
knox/site/books/knox-0-4-0/runtime-overview.png
knox/site/books/knox-0-4-0/runtime-request-processing.png
knox/site/books/knox-0-5-0/deployment-overview.png
knox/site/books/knox-0-5-0/deployment-provider.png
knox/site/books/knox-0-5-0/deployment-service.png
knox/site/books/knox-0-5-0/runtime-overview.png
knox/site/books/knox-0-5-0/runtime-request-processing.png
knox/site/books/knox-0-6-0/deployment-overview.png
knox/site/books/knox-0-6-0/deployment-provider.png
knox/site/books/knox-0-6-0/deployment-service.png
knox/site/books/knox-0-6-0/runtime-overview.png
knox/site/books/knox-0-6-0/runtime-request-processing.png
knox/site/books/knox-0-7-0/deployment-overview.png
knox/site/books/knox-0-7-0/deployment-provider.png
knox/site/books/knox-0-7-0/deployment-service.png
knox/site/books/knox-0-7-0/general_saml_flow.png
knox/site/books/knox-0-7-0/runtime-overview.png
knox/site/books/knox-0-7-0/runtime-request-processing.png
knox/site/books/knox-0-8-0/deployment-overview.png
knox/site/books/knox-0-8-0/deployment-provider.png
knox/site/books/knox-0-8-0/deployment-service.png
knox/site/books/knox-0-8-0/general_saml_flow.png
knox/site/books/knox-0-8-0/runtime-overview.png
knox/site/books/knox-0-8-0/runtime-request-processing.png
knox/site/books/knox-0-9-0/deployment-overview.png
knox/site/books/knox-0-9-0/deployment-provider.png
knox/site/books/knox-0-9-0/deployment-service.png
knox/site/books/knox-0-9-0/general_saml_flow.png
knox/site/books/knox-0-9-0/runtime-overview.png
knox/site/books/knox-0-9-0/runtime-request-processing.png
knox/site/books/knox-0-9-1/deployment-overview.png
knox/site/books/knox-0-9-1/deployment-provider.png
knox/site/books/knox-0-9-1/deployment-service.png
knox/site/books/knox-0-9-1/general_saml_flow.png
knox/site/books/knox-0-9-1/runtime-overview.png
knox/site/books/knox-0-9-1/runtime-request-processing.png
knox/site/index.html
knox/site/issue-tracking.html
knox/site/license.html
knox/site/mail-lists.html
knox/site/project-info.html
knox/site/team-list.html
knox/trunk/books/0.13.0/dev-guide/book.md
Modified: knox/site/books/knox-0-10-0/deployment-overview.png
URL: http://svn.apache.org/viewvc/knox/site/books/knox-0-10-0/deployment-overview.png?rev=1807366&r1=1807365&r2=1807366&view=diff
==============================================================================
Binary files - no diff available.
Modified: knox/site/books/knox-0-10-0/deployment-provider.png
URL: http://svn.apache.org/viewvc/knox/site/books/knox-0-10-0/deployment-provider.png?rev=1807366&r1=1807365&r2=1807366&view=diff
==============================================================================
Binary files - no diff available.
Modified: knox/site/books/knox-0-10-0/deployment-service.png
URL: http://svn.apache.org/viewvc/knox/site/books/knox-0-10-0/deployment-service.png?rev=1807366&r1=1807365&r2=1807366&view=diff
==============================================================================
Binary files - no diff available.
Modified: knox/site/books/knox-0-10-0/general_saml_flow.png
URL: http://svn.apache.org/viewvc/knox/site/books/knox-0-10-0/general_saml_flow.png?rev=1807366&r1=1807365&r2=1807366&view=diff
==============================================================================
Binary files - no diff available.
Modified: knox/site/books/knox-0-10-0/runtime-overview.png
URL: http://svn.apache.org/viewvc/knox/site/books/knox-0-10-0/runtime-overview.png?rev=1807366&r1=1807365&r2=1807366&view=diff
==============================================================================
Binary files - no diff available.
Modified: knox/site/books/knox-0-10-0/runtime-request-processing.png
URL: http://svn.apache.org/viewvc/knox/site/books/knox-0-10-0/runtime-request-processing.png?rev=1807366&r1=1807365&r2=1807366&view=diff
==============================================================================
Binary files - no diff available.
Modified: knox/site/books/knox-0-11-0/deployment-overview.png
URL: http://svn.apache.org/viewvc/knox/site/books/knox-0-11-0/deployment-overview.png?rev=1807366&r1=1807365&r2=1807366&view=diff
==============================================================================
Binary files - no diff available.
Modified: knox/site/books/knox-0-11-0/deployment-provider.png
URL: http://svn.apache.org/viewvc/knox/site/books/knox-0-11-0/deployment-provider.png?rev=1807366&r1=1807365&r2=1807366&view=diff
==============================================================================
Binary files - no diff available.
Modified: knox/site/books/knox-0-11-0/deployment-service.png
URL: http://svn.apache.org/viewvc/knox/site/books/knox-0-11-0/deployment-service.png?rev=1807366&r1=1807365&r2=1807366&view=diff
==============================================================================
Binary files - no diff available.
Modified: knox/site/books/knox-0-11-0/general_saml_flow.png
URL: http://svn.apache.org/viewvc/knox/site/books/knox-0-11-0/general_saml_flow.png?rev=1807366&r1=1807365&r2=1807366&view=diff
==============================================================================
Binary files - no diff available.
Modified: knox/site/books/knox-0-11-0/runtime-overview.png
URL: http://svn.apache.org/viewvc/knox/site/books/knox-0-11-0/runtime-overview.png?rev=1807366&r1=1807365&r2=1807366&view=diff
==============================================================================
Binary files - no diff available.
Modified: knox/site/books/knox-0-11-0/runtime-request-processing.png
URL: http://svn.apache.org/viewvc/knox/site/books/knox-0-11-0/runtime-request-processing.png?rev=1807366&r1=1807365&r2=1807366&view=diff
==============================================================================
Binary files - no diff available.
Modified: knox/site/books/knox-0-12-0/deployment-overview.png
URL: http://svn.apache.org/viewvc/knox/site/books/knox-0-12-0/deployment-overview.png?rev=1807366&r1=1807365&r2=1807366&view=diff
==============================================================================
Binary files - no diff available.
Modified: knox/site/books/knox-0-12-0/deployment-provider.png
URL: http://svn.apache.org/viewvc/knox/site/books/knox-0-12-0/deployment-provider.png?rev=1807366&r1=1807365&r2=1807366&view=diff
==============================================================================
Binary files - no diff available.
Modified: knox/site/books/knox-0-12-0/deployment-service.png
URL: http://svn.apache.org/viewvc/knox/site/books/knox-0-12-0/deployment-service.png?rev=1807366&r1=1807365&r2=1807366&view=diff
==============================================================================
Binary files - no diff available.
Modified: knox/site/books/knox-0-12-0/general_saml_flow.png
URL: http://svn.apache.org/viewvc/knox/site/books/knox-0-12-0/general_saml_flow.png?rev=1807366&r1=1807365&r2=1807366&view=diff
==============================================================================
Binary files - no diff available.
Modified: knox/site/books/knox-0-12-0/runtime-overview.png
URL: http://svn.apache.org/viewvc/knox/site/books/knox-0-12-0/runtime-overview.png?rev=1807366&r1=1807365&r2=1807366&view=diff
==============================================================================
Binary files - no diff available.
Modified: knox/site/books/knox-0-12-0/runtime-request-processing.png
URL: http://svn.apache.org/viewvc/knox/site/books/knox-0-12-0/runtime-request-processing.png?rev=1807366&r1=1807365&r2=1807366&view=diff
==============================================================================
Binary files - no diff available.
Modified: knox/site/books/knox-0-13-0/deployment-overview.png
URL: http://svn.apache.org/viewvc/knox/site/books/knox-0-13-0/deployment-overview.png?rev=1807366&r1=1807365&r2=1807366&view=diff
==============================================================================
Binary files - no diff available.
Modified: knox/site/books/knox-0-13-0/deployment-provider.png
URL: http://svn.apache.org/viewvc/knox/site/books/knox-0-13-0/deployment-provider.png?rev=1807366&r1=1807365&r2=1807366&view=diff
==============================================================================
Binary files - no diff available.
Modified: knox/site/books/knox-0-13-0/deployment-service.png
URL: http://svn.apache.org/viewvc/knox/site/books/knox-0-13-0/deployment-service.png?rev=1807366&r1=1807365&r2=1807366&view=diff
==============================================================================
Binary files - no diff available.
Modified: knox/site/books/knox-0-13-0/dev-guide.html
URL: http://svn.apache.org/viewvc/knox/site/books/knox-0-13-0/dev-guide.html?rev=1807366&r1=1807365&r2=1807366&view=diff
==============================================================================
--- knox/site/books/knox-0-13-0/dev-guide.html (original)
+++ knox/site/books/knox-0-13-0/dev-guide.html Tue Sep 5 15:45:55 2017
@@ -28,6 +28,7 @@
<li><a href="#Rewrite+Provider">Rewrite Provider</a></li>
<li><a href="#Gateway+Services">Gateway Services</a></li>
<li><a href="#KnoxSSO+Integration">KnoxSSO Integration</a></li>
+ <li><a href="#Health+Monitoring+API">Health Monitoring API</a></li>
<li><a href="#Auditing">Auditing</a></li>
<li><a href="#Logging">Logging</a></li>
<li><a href="#Internationalization">Internationalization</a></li>
@@ -1506,6 +1507,322 @@ public class CaseShifterIdentityAssertio
return (RSAPublicKey) key;
}
}
+</code></pre><h3><a id="Health+Monitoring+API">Health Monitoring API</a> <a href="#Health+Monitoring+API"><img src="markbook-section-link.png"/></a></h3><h1>Health Monitoring REST API</h1><p>Knox provides REST-ful API for monitoring the core service. It primarily exposes the health of the Knox service that includes service status (up/down) as well as other health metrics. This is a work-in-progress feature, which started with an extensible framework to support basic functionalities. In particular, it currently supports the API to A) <em>ping</em> the service and B) time-based statistics related to all API calls.</p><h4><a id="Health+Monitoring+Setup">Health Monitoring Setup</a> <a href="#Health+Monitoring+Setup"><img src="markbook-section-link.png"/></a></h4><p>The basic setup includes two major steps A) add configurations to enable the metrics collection and reporting B) write a topology file and upload it into <em>topologies</em> directory.</p><h5><a id="Service+Configurations">Se
rvice Configurations</a> <a href="#Service+Configurations"><img src="markbook-section-link.png"/></a></h5><p>At first, we need to make sure the gateway configurations to gather and report to JMX are turned on in <em>gateway-site.xml</em>. The following two configurations into <em>gateway-site.xml</em> will serve the purpose.</p>
+<pre><code><property>
+ <name>gateway.metrics.enabled</name>
+ <value>true</value>
+ <description>Boolean flag indicates whether to enable the metrics collection</description>
+</property>
+<property>
+ <name>gateway.jmx.metrics.reporting.enabled</name>
+ <value>true</value>
+ <description>Boolean flag indicates whether to enable the metrics reporting using JMX</description>
+</property>
+
+</code></pre><h5><a id="health.xml+Topology">health.xml Topology</a> <a href="#health.xml+Topology"><img src="markbook-section-link.png"/></a></h5><p>In order to enable health monitoring REST service, you need to add a new topology file (i.e. <em>health.xml</em>). The following is an example that is configured to test the basic functionalities of Knox service. It is highly recommended using more restricted authentication mechanism.</p>
+<pre><code><topology>
+
+ <gateway>
+
+ <provider>
+ <role>authentication</role>
+ <name>ShiroProvider</name>
+ <enabled>true</enabled>
+ <param>
+ <!--
+ session timeout in minutes, this is really idle timeout,
+ defaults to 30 mins, if the property value is not defined,,
+ current client authentication would expire if client idles continuously for more than this value
+ -->
+ <name>sessionTimeout</name>
+ <value>30</value>
+ </param>
+ <param>
+ <name>main.ldapRealm</name>
+ <value>org.apache.hadoop.gateway.shirorealm.KnoxLdapRealm</value>
+ </param>
+ <param>
+ <name>main.ldapContextFactory</name>
+ <value>org.apache.hadoop.gateway.shirorealm.KnoxLdapContextFactory</value>
+ </param>
+ <param>
+ <name>main.ldapRealm.contextFactory</name>
+ <value>$ldapContextFactory</value>
+ </param>
+ <param>
+ <name>main.ldapRealm.userDnTemplate</name>
+ <value>uid={0},ou=people,dc=hadoop,dc=apache,dc=org</value>
+ </param>
+ <param>
+ <name>main.ldapRealm.contextFactory.url</name>
+ <value>ldap://localhost:33389</value>
+ </param>
+ <param>
+ <name>main.ldapRealm.contextFactory.authenticationMechanism</name>
+ <value>simple</value>
+ </param>
+ <param>
+ <name>urls./**</name>
+ <value>authcBasic</value>
+ </param>
+ </provider>
+
+ <provider>
+ <role>authorization</role>
+ <name>AclsAuthz</name>
+ <enabled>false</enabled>
+ <param>
+ <name>knox.acl</name>
+ <value>admin;*;*</value>
+ </param>
+ </provider>
+
+ <provider>
+ <role>identity-assertion</role>
+ <name>Default</name>
+ <enabled>false</enabled>
+ </provider>
+
+ <provider>
+ <role>hostmap</role>
+ <name>static</name>
+ <enabled>true</enabled>
+ <param><name>localhost</name><value>sandbox,sandbox.hortonworks.com</value></param>
+ </provider>
+
+ </gateway>
+
+ <service>
+ <role>HEALTH</role>
+ </service>
+
+</topology>
+</code></pre><p>Just as with any Knox service, the gateway providers protect the health monitoring REST service defined above it. In this case, the ShiroProvider is taking care of HTTP Basic Auth using LDAP. Once the user authenticates with LDAP, the request processing continues to the <em>Health</em> service that will perform the necessary actions.</p><p>The authenticate/federation provider can be swapped out to fit your deployment environment.</p><p>After creating the file health.xml with above contents, you need to copy the file to <em>KNOX_HOME/conf/topologies</em> directory. If Knox/gateway service is not running, you can start it using “<em>bin/gateway.sh start</em>”. Otherwise the service would automatically pick this new ‘<em>health</em>’ service. When gateway service registers the new service, it displays the following log messages in <em>log/gateway.log</em>.</p>
+<pre><code>2017-08-22 03:44:25,045 INFO hadoop.gateway (GatewayServer.java:handleCreateDeployment(677)) - Deploying topology health to /home/joe/knox/knox-0.12.0/bin/../data/deployments/health.topo.15e080a91c0
+2017-08-22 03:44:25,045 INFO hadoop.gateway (GatewayServer.java:internalDeactivateTopology(596)) - Deactivating topology health
+2017-08-22 03:44:25,119 INFO hadoop.gateway (DefaultGatewayServices.java:initializeContribution(197)) - Creating credential store for the cluster: health
+2017-08-22 03:44:25,142 INFO hadoop.gateway (GatewayServer.java:internalActivateTopology(566)) - Activating topology health
+2017-08-22 03:44:25,142 INFO hadoop.gateway (GatewayServer.java:internalActivateArchive(576)) - Activating topology health archive %2F
+
+</code></pre><h5><a id="Verify">Verify</a> <a href="#Verify"><img src="markbook-section-link.png"/></a></h5><p>Once the health service is active, you can verify it by using the following <em>curl</em> command. The ‘<em>ping</em>’ end point displays if the service is up. This end point can be utilized for monitoring the basic health of a Knox service.</p>
+<pre><code>$ curl -i -k -u guest:guest-password -X GET 'https://localhost:8445/gateway/health/v1/ping'
+HTTP/1.1 200 OK
+Date: Tue, 22 Aug 2017 07:09:37 GMT
+Set-Cookie: JSESSIONID=1o82bcvoqbhbb1apt7zs8ubybb;Path=/gateway/health;Secure;HttpOnly
+Expires: Thu, 01 Jan 1970 00:00:00 GMT
+Set-Cookie: rememberMe=deleteMe; Path=/gateway/health; Max-Age=0; Expires=Mon, 21-Aug-2017 07:09:37 GMT
+Cache-Control: must-revalidate,no-cache,no-store
+Content-Type: text/plain; charset=ISO-8859-1
+Content-Length: 3
+Server: Jetty(9.2.15.v20160210)
+
+OK
+</code></pre><p>To retrieve the meaningful metrics details of various service calls, you may need to run multiple REST calls such as the followings. After that, execute the metrics REST call as shown below with a sample output. As shown, metrics output is returned in JSON format.</p>
+<pre><code>curl -i -k -u guest:guest-password -X GET 'https://localhost:8445/gateway/sandbox/webhdfs/v1/?op=LISTSTATUS'
+</code></pre>
+<pre><code>$ curl -i -k -u guest:guest-password -X GET 'https://localhost:8445/gateway/health/v1/metrics?pretty=true'
+HTTP/1.1 200 OK
+Date: Tue, 22 Aug 2017 07:10:44 GMT
+Set-Cookie: JSESSIONID=kqntcdaje9uai3pup7ffvfw4;Path=/gateway/health;Secure;HttpOnly
+Expires: Thu, 01 Jan 1970 00:00:00 GMT
+Set-Cookie: rememberMe=deleteMe; Path=/gateway/health; Max-Age=0; Expires=Mon, 21-Aug-2017 07:10:44 GMT
+Content-Type: application/json
+Cache-Control: must-revalidate,no-cache,no-store
+Transfer-Encoding: chunked
+Server: Jetty(9.2.15.v20160210)
+
+{
+ "version" : "3.0.0",
+ "gauges" : { },
+ "counters" : { },
+ "histograms" : { },
+ "meters" : { },
+ "timers" : {
+ "client./gateway/health/v1/metrics.GET-requests" : {
+ "count" : 5,
+ "max" : 0.624587973,
+ "mean" : 0.027655743001736188,
+ "min" : 0.006145587,
+ "p50" : 0.010020548,
+ "p75" : 0.010020548,
+ "p95" : 0.074454725,
+ "p98" : 0.624587973,
+ "p99" : 0.624587973,
+ "p999" : 0.624587973,
+ "stddev" : 0.0929226225229978,
+ "m15_rate" : 2.657500857422334E-7,
+ "m1_rate" : 5.770087852901534E-89,
+ "m5_rate" : 4.769163772973399E-19,
+ "mean_rate" : 4.0952378345310894E-4,
+ "duration_units" : "seconds",
+ "rate_units" : "calls/second"
+ },
+ "client./gateway/health/v1/ping.GET-requests" : {
+ "count" : 1,
+ "max" : 0.017257638000000002,
+ "mean" : 0.017257638000000002,
+ "min" : 0.017257638000000002,
+ "p50" : 0.017257638000000002,
+ "p75" : 0.017257638000000002,
+ "p95" : 0.017257638000000002,
+ "p98" : 0.017257638000000002,
+ "p99" : 0.017257638000000002,
+ "p999" : 0.017257638000000002,
+ "stddev" : 0.0,
+ "m15_rate" : 0.18710139700632353,
+ "m1_rate" : 0.0735758882342885,
+ "m5_rate" : 0.1637461506155964,
+ "mean_rate" : 0.014990517517814805,
+ "duration_units" : "seconds",
+ "rate_units" : "calls/second"
+ },
+ "client./gateway/sandbox/health/v1/.GET-requests" : {
+ "count" : 1,
+ "max" : 4.01873E-4,
+ "mean" : 4.01873E-4,
+ "min" : 4.01873E-4,
+ "p50" : 4.01873E-4,
+ "p75" : 4.01873E-4,
+ "p95" : 4.01873E-4,
+ "p98" : 4.01873E-4,
+ "p99" : 4.01873E-4,
+ "p999" : 4.01873E-4,
+ "stddev" : 0.0,
+ "m15_rate" : 2.536740427767808E-7,
+ "m1_rate" : 7.074903404511115E-90,
+ "m5_rate" : 4.081014139447941E-19,
+ "mean_rate" : 8.179827684854002E-5,
+ "duration_units" : "seconds",
+ "rate_units" : "calls/second"
+ },
+ "client./gateway/sandbox/v1/health/.GET-requests" : {
+ "count" : 1,
+ "max" : 5.470700000000001E-4,
+ "mean" : 5.470700000000001E-4,
+ "min" : 5.470700000000001E-4,
+ "p50" : 5.470700000000001E-4,
+ "p75" : 5.470700000000001E-4,
+ "p95" : 5.470700000000001E-4,
+ "p98" : 5.470700000000001E-4,
+ "p99" : 5.470700000000001E-4,
+ "p999" : 5.470700000000001E-4,
+ "stddev" : 0.0,
+ "m15_rate" : 2.413022137213267E-7,
+ "m1_rate" : 3.341947732164585E-90,
+ "m5_rate" : 3.512561421726287E-19,
+ "mean_rate" : 8.149518570285245E-5,
+ "duration_units" : "seconds",
+ "rate_units" : "calls/second"
+ },
+ "client./gateway/sandbox/webhdfs/v1/.GET-requests" : {
+ "count" : 4,
+ "max" : 0.463745401,
+ "mean" : 0.024924118143299912,
+ "min" : 0.016542244,
+ "p50" : 0.024799078000000002,
+ "p75" : 0.033933548,
+ "p95" : 0.033933548,
+ "p98" : 0.033933548,
+ "p99" : 0.033933548,
+ "p999" : 0.033933548,
+ "stddev" : 0.007284773511002474,
+ "m15_rate" : 2.120680068580741E-8,
+ "m1_rate" : 4.7541228609699333E-91,
+ "m5_rate" : 1.5806080232092864E-20,
+ "mean_rate" : 2.7314359915623396E-4,
+ "duration_units" : "seconds",
+ "rate_units" : "calls/second"
+ },
+ "service./gateway/sandbox/webhdfs/v1/.get-requests" : {
+ "count" : 3,
+ "max" : 0.014635496000000001,
+ "mean" : 0.00342438191233768,
+ "min" : 0.0020088890000000002,
+ "p50" : 0.0020088890000000002,
+ "p75" : 0.005144646,
+ "p95" : 0.005144646,
+ "p98" : 0.005144646,
+ "p99" : 0.005144646,
+ "p999" : 0.005144646,
+ "stddev" : 0.0015604555820128599,
+ "m15_rate" : 1.9913776931949195E-8,
+ "m1_rate" : 3.1334281325640874E-91,
+ "m5_rate" : 1.055281734633953E-20,
+ "mean_rate" : 2.0486339070804923E-4,
+ "duration_units" : "seconds",
+ "rate_units" : "calls/second"
+ }
+ }
+}
+</code></pre><h4><a id="REST+End+Points">REST End Points</a> <a href="#REST+End+Points"><img src="markbook-section-link.png"/></a></h4><p>As mentioned above, currently Knox provides a few monitoring APIs to start with. The list will gradually grow to support new use-cases.</p><h5><a id="/ping">/ping</a> <a href="#/ping"><img src="markbook-section-link.png"/></a></h5><p>This end-point can be used to determine if a Knox gateway service is alive or not. It is useful for basic health monitoring of the core service. Although most of the results of REST calls are in JSON format, this one (*/ping*) is in plain text. </p><p>Sample response</p>
+<pre><code>OK
+</code></pre><h5><a id="/metrics">/metrics</a> <a href="#/metrics"><img src="markbook-section-link.png"/></a></h5><p>This end-point returns all Knox metrics grouped by individual call type. For example, timer metrics for all <em>webhdfs</em> calls are aggregated into one set of metrics and then returned in a separate JSON element. This end-point also supports an option (*/metrics?pretty=true*) to pretty print the metrics output.</p><p>A sample response with <em>pretty=true</em> is shown below:</p>
+<pre><code>{
+ "version" : "3.0.0",
+ "gauges" : { },
+ "counters" : { },
+ "histograms" : { },
+ "meters" : { },
+ "timers" : {
+ "client./gateway/health/v1/ping.GET-requests" : {
+ "count" : 1,
+ "max" : 0.017257638000000002,
+ "mean" : 0.017257638000000002,
+ "min" : 0.017257638000000002,
+ "p50" : 0.017257638000000002,
+ "p75" : 0.017257638000000002,
+ "p95" : 0.017257638000000002,
+ "p98" : 0.017257638000000002,
+ "p99" : 0.017257638000000002,
+ "p999" : 0.017257638000000002,
+ "stddev" : 0.0,
+ "m15_rate" : 0.18710139700632353,
+ "m1_rate" : 0.0735758882342885,
+ "m5_rate" : 0.1637461506155964,
+ "mean_rate" : 0.014990517517814805,
+ "duration_units" : "seconds",
+ "rate_units" : "calls/second"
+ },
+ "client./gateway/sandbox/v1/health/.GET-requests" : {
+ "count" : 1,
+ "max" : 5.470700000000001E-4,
+ "mean" : 5.470700000000001E-4,
+ "min" : 5.470700000000001E-4,
+ "p50" : 5.470700000000001E-4,
+ "p75" : 5.470700000000001E-4,
+ "p95" : 5.470700000000001E-4,
+ "p98" : 5.470700000000001E-4,
+ "p99" : 5.470700000000001E-4,
+ "p999" : 5.470700000000001E-4,
+ "stddev" : 0.0,
+ "m15_rate" : 2.413022137213267E-7,
+ "m1_rate" : 3.341947732164585E-90,
+ "m5_rate" : 3.512561421726287E-19,
+ "mean_rate" : 8.149518570285245E-5,
+ "duration_units" : "seconds",
+ "rate_units" : "calls/second"
+ },
+ "client./gateway/sandbox/webhdfs/v1/.GET-requests" : {
+ "count" : 4,
+ "max" : 0.463745401,
+ "mean" : 0.024924118143299912,
+ "min" : 0.016542244,
+ "p50" : 0.024799078000000002,
+ "p75" : 0.033933548,
+ "p95" : 0.033933548,
+ "p98" : 0.033933548,
+ "p99" : 0.033933548,
+ "p999" : 0.033933548,
+ "stddev" : 0.007284773511002474,
+ "m15_rate" : 2.120680068580741E-8,
+ "m1_rate" : 4.7541228609699333E-91,
+ "m5_rate" : 1.5806080232092864E-20,
+ "mean_rate" : 2.7314359915623396E-4,
+ "duration_units" : "seconds",
+ "rate_units" : "calls/second"
+ }
+ }
+}
</code></pre><h2><a id="Auditing">Auditing</a> <a href="#Auditing"><img src="markbook-section-link.png"/></a></h2>
<pre><code class="java">public class AuditingSample {
Modified: knox/site/books/knox-0-13-0/general_saml_flow.png
URL: http://svn.apache.org/viewvc/knox/site/books/knox-0-13-0/general_saml_flow.png?rev=1807366&r1=1807365&r2=1807366&view=diff
==============================================================================
Binary files - no diff available.
Modified: knox/site/books/knox-0-13-0/runtime-overview.png
URL: http://svn.apache.org/viewvc/knox/site/books/knox-0-13-0/runtime-overview.png?rev=1807366&r1=1807365&r2=1807366&view=diff
==============================================================================
Binary files - no diff available.
Modified: knox/site/books/knox-0-13-0/runtime-request-processing.png
URL: http://svn.apache.org/viewvc/knox/site/books/knox-0-13-0/runtime-request-processing.png?rev=1807366&r1=1807365&r2=1807366&view=diff
==============================================================================
Binary files - no diff available.
Modified: knox/site/books/knox-0-4-0/deployment-overview.png
URL: http://svn.apache.org/viewvc/knox/site/books/knox-0-4-0/deployment-overview.png?rev=1807366&r1=1807365&r2=1807366&view=diff
==============================================================================
Binary files - no diff available.
Modified: knox/site/books/knox-0-4-0/deployment-provider.png
URL: http://svn.apache.org/viewvc/knox/site/books/knox-0-4-0/deployment-provider.png?rev=1807366&r1=1807365&r2=1807366&view=diff
==============================================================================
Binary files - no diff available.
Modified: knox/site/books/knox-0-4-0/deployment-service.png
URL: http://svn.apache.org/viewvc/knox/site/books/knox-0-4-0/deployment-service.png?rev=1807366&r1=1807365&r2=1807366&view=diff
==============================================================================
Binary files - no diff available.
Modified: knox/site/books/knox-0-4-0/runtime-overview.png
URL: http://svn.apache.org/viewvc/knox/site/books/knox-0-4-0/runtime-overview.png?rev=1807366&r1=1807365&r2=1807366&view=diff
==============================================================================
Binary files - no diff available.
Modified: knox/site/books/knox-0-4-0/runtime-request-processing.png
URL: http://svn.apache.org/viewvc/knox/site/books/knox-0-4-0/runtime-request-processing.png?rev=1807366&r1=1807365&r2=1807366&view=diff
==============================================================================
Binary files - no diff available.
Modified: knox/site/books/knox-0-5-0/deployment-overview.png
URL: http://svn.apache.org/viewvc/knox/site/books/knox-0-5-0/deployment-overview.png?rev=1807366&r1=1807365&r2=1807366&view=diff
==============================================================================
Binary files - no diff available.
Modified: knox/site/books/knox-0-5-0/deployment-provider.png
URL: http://svn.apache.org/viewvc/knox/site/books/knox-0-5-0/deployment-provider.png?rev=1807366&r1=1807365&r2=1807366&view=diff
==============================================================================
Binary files - no diff available.
Modified: knox/site/books/knox-0-5-0/deployment-service.png
URL: http://svn.apache.org/viewvc/knox/site/books/knox-0-5-0/deployment-service.png?rev=1807366&r1=1807365&r2=1807366&view=diff
==============================================================================
Binary files - no diff available.
Modified: knox/site/books/knox-0-5-0/runtime-overview.png
URL: http://svn.apache.org/viewvc/knox/site/books/knox-0-5-0/runtime-overview.png?rev=1807366&r1=1807365&r2=1807366&view=diff
==============================================================================
Binary files - no diff available.
Modified: knox/site/books/knox-0-5-0/runtime-request-processing.png
URL: http://svn.apache.org/viewvc/knox/site/books/knox-0-5-0/runtime-request-processing.png?rev=1807366&r1=1807365&r2=1807366&view=diff
==============================================================================
Binary files - no diff available.
Modified: knox/site/books/knox-0-6-0/deployment-overview.png
URL: http://svn.apache.org/viewvc/knox/site/books/knox-0-6-0/deployment-overview.png?rev=1807366&r1=1807365&r2=1807366&view=diff
==============================================================================
Binary files - no diff available.
Modified: knox/site/books/knox-0-6-0/deployment-provider.png
URL: http://svn.apache.org/viewvc/knox/site/books/knox-0-6-0/deployment-provider.png?rev=1807366&r1=1807365&r2=1807366&view=diff
==============================================================================
Binary files - no diff available.
Modified: knox/site/books/knox-0-6-0/deployment-service.png
URL: http://svn.apache.org/viewvc/knox/site/books/knox-0-6-0/deployment-service.png?rev=1807366&r1=1807365&r2=1807366&view=diff
==============================================================================
Binary files - no diff available.
Modified: knox/site/books/knox-0-6-0/runtime-overview.png
URL: http://svn.apache.org/viewvc/knox/site/books/knox-0-6-0/runtime-overview.png?rev=1807366&r1=1807365&r2=1807366&view=diff
==============================================================================
Binary files - no diff available.
Modified: knox/site/books/knox-0-6-0/runtime-request-processing.png
URL: http://svn.apache.org/viewvc/knox/site/books/knox-0-6-0/runtime-request-processing.png?rev=1807366&r1=1807365&r2=1807366&view=diff
==============================================================================
Binary files - no diff available.
Modified: knox/site/books/knox-0-7-0/deployment-overview.png
URL: http://svn.apache.org/viewvc/knox/site/books/knox-0-7-0/deployment-overview.png?rev=1807366&r1=1807365&r2=1807366&view=diff
==============================================================================
Binary files - no diff available.
Modified: knox/site/books/knox-0-7-0/deployment-provider.png
URL: http://svn.apache.org/viewvc/knox/site/books/knox-0-7-0/deployment-provider.png?rev=1807366&r1=1807365&r2=1807366&view=diff
==============================================================================
Binary files - no diff available.
Modified: knox/site/books/knox-0-7-0/deployment-service.png
URL: http://svn.apache.org/viewvc/knox/site/books/knox-0-7-0/deployment-service.png?rev=1807366&r1=1807365&r2=1807366&view=diff
==============================================================================
Binary files - no diff available.
Modified: knox/site/books/knox-0-7-0/general_saml_flow.png
URL: http://svn.apache.org/viewvc/knox/site/books/knox-0-7-0/general_saml_flow.png?rev=1807366&r1=1807365&r2=1807366&view=diff
==============================================================================
Binary files - no diff available.
Modified: knox/site/books/knox-0-7-0/runtime-overview.png
URL: http://svn.apache.org/viewvc/knox/site/books/knox-0-7-0/runtime-overview.png?rev=1807366&r1=1807365&r2=1807366&view=diff
==============================================================================
Binary files - no diff available.
Modified: knox/site/books/knox-0-7-0/runtime-request-processing.png
URL: http://svn.apache.org/viewvc/knox/site/books/knox-0-7-0/runtime-request-processing.png?rev=1807366&r1=1807365&r2=1807366&view=diff
==============================================================================
Binary files - no diff available.
Modified: knox/site/books/knox-0-8-0/deployment-overview.png
URL: http://svn.apache.org/viewvc/knox/site/books/knox-0-8-0/deployment-overview.png?rev=1807366&r1=1807365&r2=1807366&view=diff
==============================================================================
Binary files - no diff available.
Modified: knox/site/books/knox-0-8-0/deployment-provider.png
URL: http://svn.apache.org/viewvc/knox/site/books/knox-0-8-0/deployment-provider.png?rev=1807366&r1=1807365&r2=1807366&view=diff
==============================================================================
Binary files - no diff available.
Modified: knox/site/books/knox-0-8-0/deployment-service.png
URL: http://svn.apache.org/viewvc/knox/site/books/knox-0-8-0/deployment-service.png?rev=1807366&r1=1807365&r2=1807366&view=diff
==============================================================================
Binary files - no diff available.
Modified: knox/site/books/knox-0-8-0/general_saml_flow.png
URL: http://svn.apache.org/viewvc/knox/site/books/knox-0-8-0/general_saml_flow.png?rev=1807366&r1=1807365&r2=1807366&view=diff
==============================================================================
Binary files - no diff available.
Modified: knox/site/books/knox-0-8-0/runtime-overview.png
URL: http://svn.apache.org/viewvc/knox/site/books/knox-0-8-0/runtime-overview.png?rev=1807366&r1=1807365&r2=1807366&view=diff
==============================================================================
Binary files - no diff available.
Modified: knox/site/books/knox-0-8-0/runtime-request-processing.png
URL: http://svn.apache.org/viewvc/knox/site/books/knox-0-8-0/runtime-request-processing.png?rev=1807366&r1=1807365&r2=1807366&view=diff
==============================================================================
Binary files - no diff available.
Modified: knox/site/books/knox-0-9-0/deployment-overview.png
URL: http://svn.apache.org/viewvc/knox/site/books/knox-0-9-0/deployment-overview.png?rev=1807366&r1=1807365&r2=1807366&view=diff
==============================================================================
Binary files - no diff available.
Modified: knox/site/books/knox-0-9-0/deployment-provider.png
URL: http://svn.apache.org/viewvc/knox/site/books/knox-0-9-0/deployment-provider.png?rev=1807366&r1=1807365&r2=1807366&view=diff
==============================================================================
Binary files - no diff available.
Modified: knox/site/books/knox-0-9-0/deployment-service.png
URL: http://svn.apache.org/viewvc/knox/site/books/knox-0-9-0/deployment-service.png?rev=1807366&r1=1807365&r2=1807366&view=diff
==============================================================================
Binary files - no diff available.
Modified: knox/site/books/knox-0-9-0/general_saml_flow.png
URL: http://svn.apache.org/viewvc/knox/site/books/knox-0-9-0/general_saml_flow.png?rev=1807366&r1=1807365&r2=1807366&view=diff
==============================================================================
Binary files - no diff available.
Modified: knox/site/books/knox-0-9-0/runtime-overview.png
URL: http://svn.apache.org/viewvc/knox/site/books/knox-0-9-0/runtime-overview.png?rev=1807366&r1=1807365&r2=1807366&view=diff
==============================================================================
Binary files - no diff available.
Modified: knox/site/books/knox-0-9-0/runtime-request-processing.png
URL: http://svn.apache.org/viewvc/knox/site/books/knox-0-9-0/runtime-request-processing.png?rev=1807366&r1=1807365&r2=1807366&view=diff
==============================================================================
Binary files - no diff available.
Modified: knox/site/books/knox-0-9-1/deployment-overview.png
URL: http://svn.apache.org/viewvc/knox/site/books/knox-0-9-1/deployment-overview.png?rev=1807366&r1=1807365&r2=1807366&view=diff
==============================================================================
Binary files - no diff available.
Modified: knox/site/books/knox-0-9-1/deployment-provider.png
URL: http://svn.apache.org/viewvc/knox/site/books/knox-0-9-1/deployment-provider.png?rev=1807366&r1=1807365&r2=1807366&view=diff
==============================================================================
Binary files - no diff available.
Modified: knox/site/books/knox-0-9-1/deployment-service.png
URL: http://svn.apache.org/viewvc/knox/site/books/knox-0-9-1/deployment-service.png?rev=1807366&r1=1807365&r2=1807366&view=diff
==============================================================================
Binary files - no diff available.
Modified: knox/site/books/knox-0-9-1/general_saml_flow.png
URL: http://svn.apache.org/viewvc/knox/site/books/knox-0-9-1/general_saml_flow.png?rev=1807366&r1=1807365&r2=1807366&view=diff
==============================================================================
Binary files - no diff available.
Modified: knox/site/books/knox-0-9-1/runtime-overview.png
URL: http://svn.apache.org/viewvc/knox/site/books/knox-0-9-1/runtime-overview.png?rev=1807366&r1=1807365&r2=1807366&view=diff
==============================================================================
Binary files - no diff available.
Modified: knox/site/books/knox-0-9-1/runtime-request-processing.png
URL: http://svn.apache.org/viewvc/knox/site/books/knox-0-9-1/runtime-request-processing.png?rev=1807366&r1=1807365&r2=1807366&view=diff
==============================================================================
Binary files - no diff available.
Modified: knox/site/index.html
URL: http://svn.apache.org/viewvc/knox/site/index.html?rev=1807366&r1=1807365&r2=1807366&view=diff
==============================================================================
--- knox/site/index.html (original)
+++ knox/site/index.html Tue Sep 5 15:45:55 2017
@@ -1,13 +1,13 @@
<!DOCTYPE html>
<!--
- | Generated by Apache Maven Doxia at 2017-08-28
+ | Generated by Apache Maven Doxia at 2017-09-05
| Rendered using Apache Maven Fluido Skin 1.3.0
-->
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
<meta charset="UTF-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
- <meta name="Date-Revision-yyyymmdd" content="20170828" />
+ <meta name="Date-Revision-yyyymmdd" content="20170905" />
<meta http-equiv="Content-Language" content="en" />
<title>Knox Gateway – REST API and Application Gateway for the Apache Hadoop Ecosystem</title>
<link rel="stylesheet" href="./css/apache-maven-fluido-1.3.0.min.css" />
@@ -58,7 +58,7 @@
- <li id="publishDate" class="pull-right">Last Published: 2017-08-28</li>
+ <li id="publishDate" class="pull-right">Last Published: 2017-09-05</li>
</ul>
</div>
Modified: knox/site/issue-tracking.html
URL: http://svn.apache.org/viewvc/knox/site/issue-tracking.html?rev=1807366&r1=1807365&r2=1807366&view=diff
==============================================================================
--- knox/site/issue-tracking.html (original)
+++ knox/site/issue-tracking.html Tue Sep 5 15:45:55 2017
@@ -1,13 +1,13 @@
<!DOCTYPE html>
<!--
- | Generated by Apache Maven Doxia at 2017-08-28
+ | Generated by Apache Maven Doxia at 2017-09-05
| Rendered using Apache Maven Fluido Skin 1.3.0
-->
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
<meta charset="UTF-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
- <meta name="Date-Revision-yyyymmdd" content="20170828" />
+ <meta name="Date-Revision-yyyymmdd" content="20170905" />
<meta http-equiv="Content-Language" content="en" />
<title>Knox Gateway – Issue Tracking</title>
<link rel="stylesheet" href="./css/apache-maven-fluido-1.3.0.min.css" />
@@ -58,7 +58,7 @@
- <li id="publishDate" class="pull-right">Last Published: 2017-08-28</li>
+ <li id="publishDate" class="pull-right">Last Published: 2017-09-05</li>
</ul>
</div>
Modified: knox/site/license.html
URL: http://svn.apache.org/viewvc/knox/site/license.html?rev=1807366&r1=1807365&r2=1807366&view=diff
==============================================================================
--- knox/site/license.html (original)
+++ knox/site/license.html Tue Sep 5 15:45:55 2017
@@ -1,13 +1,13 @@
<!DOCTYPE html>
<!--
- | Generated by Apache Maven Doxia at 2017-08-28
+ | Generated by Apache Maven Doxia at 2017-09-05
| Rendered using Apache Maven Fluido Skin 1.3.0
-->
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
<meta charset="UTF-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
- <meta name="Date-Revision-yyyymmdd" content="20170828" />
+ <meta name="Date-Revision-yyyymmdd" content="20170905" />
<meta http-equiv="Content-Language" content="en" />
<title>Knox Gateway – Project License</title>
<link rel="stylesheet" href="./css/apache-maven-fluido-1.3.0.min.css" />
@@ -58,7 +58,7 @@
- <li id="publishDate" class="pull-right">Last Published: 2017-08-28</li>
+ <li id="publishDate" class="pull-right">Last Published: 2017-09-05</li>
</ul>
</div>
Modified: knox/site/mail-lists.html
URL: http://svn.apache.org/viewvc/knox/site/mail-lists.html?rev=1807366&r1=1807365&r2=1807366&view=diff
==============================================================================
--- knox/site/mail-lists.html (original)
+++ knox/site/mail-lists.html Tue Sep 5 15:45:55 2017
@@ -1,13 +1,13 @@
<!DOCTYPE html>
<!--
- | Generated by Apache Maven Doxia at 2017-08-28
+ | Generated by Apache Maven Doxia at 2017-09-05
| Rendered using Apache Maven Fluido Skin 1.3.0
-->
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
<meta charset="UTF-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
- <meta name="Date-Revision-yyyymmdd" content="20170828" />
+ <meta name="Date-Revision-yyyymmdd" content="20170905" />
<meta http-equiv="Content-Language" content="en" />
<title>Knox Gateway – Project Mailing Lists</title>
<link rel="stylesheet" href="./css/apache-maven-fluido-1.3.0.min.css" />
@@ -58,7 +58,7 @@
- <li id="publishDate" class="pull-right">Last Published: 2017-08-28</li>
+ <li id="publishDate" class="pull-right">Last Published: 2017-09-05</li>
</ul>
</div>
Modified: knox/site/project-info.html
URL: http://svn.apache.org/viewvc/knox/site/project-info.html?rev=1807366&r1=1807365&r2=1807366&view=diff
==============================================================================
--- knox/site/project-info.html (original)
+++ knox/site/project-info.html Tue Sep 5 15:45:55 2017
@@ -1,13 +1,13 @@
<!DOCTYPE html>
<!--
- | Generated by Apache Maven Doxia at 2017-08-28
+ | Generated by Apache Maven Doxia at 2017-09-05
| Rendered using Apache Maven Fluido Skin 1.3.0
-->
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
<meta charset="UTF-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
- <meta name="Date-Revision-yyyymmdd" content="20170828" />
+ <meta name="Date-Revision-yyyymmdd" content="20170905" />
<meta http-equiv="Content-Language" content="en" />
<title>Knox Gateway – Project Information</title>
<link rel="stylesheet" href="./css/apache-maven-fluido-1.3.0.min.css" />
@@ -58,7 +58,7 @@
- <li id="publishDate" class="pull-right">Last Published: 2017-08-28</li>
+ <li id="publishDate" class="pull-right">Last Published: 2017-09-05</li>
</ul>
</div>
Modified: knox/site/team-list.html
URL: http://svn.apache.org/viewvc/knox/site/team-list.html?rev=1807366&r1=1807365&r2=1807366&view=diff
==============================================================================
--- knox/site/team-list.html (original)
+++ knox/site/team-list.html Tue Sep 5 15:45:55 2017
@@ -1,13 +1,13 @@
<!DOCTYPE html>
<!--
- | Generated by Apache Maven Doxia at 2017-08-28
+ | Generated by Apache Maven Doxia at 2017-09-05
| Rendered using Apache Maven Fluido Skin 1.3.0
-->
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
<meta charset="UTF-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
- <meta name="Date-Revision-yyyymmdd" content="20170828" />
+ <meta name="Date-Revision-yyyymmdd" content="20170905" />
<meta http-equiv="Content-Language" content="en" />
<title>Knox Gateway – Team list</title>
<link rel="stylesheet" href="./css/apache-maven-fluido-1.3.0.min.css" />
@@ -58,7 +58,7 @@
- <li id="publishDate" class="pull-right">Last Published: 2017-08-28</li>
+ <li id="publishDate" class="pull-right">Last Published: 2017-09-05</li>
</ul>
</div>
@@ -493,7 +493,14 @@
<td>Colm O hEigeartaigh</td>
<td>coheigea(at)apache(dot)org</td>
<td>Talend</td>
-<td>Committer</td></tr></table></div>
+<td>Committer</td></tr>
+<tr class="a">
+<td><img src="http://www.gravatar.com/avatar/9c160b755fa13b1574d9c214cf216657?d=mm&s=60" alt="" /></td>
+<td><a name="jeffreyr"></a>jeffreyr</td>
+<td>Jeffrey E Rodriguez</td>
+<td>jeffreyr(at)us(dot)ibm(dot)com</td>
+<td>IBM</td>
+<td>PMC</td></tr></table></div>
<div class="section">
<h3><a name="Contributors"></a>Contributors</h3><a name="Contributors"></a>
<p>The following additional people have contributed to this project through the way of suggestions, patches or documentation.</p>
@@ -529,48 +536,42 @@
<td>Huawei</td>
<td>Contributor</td></tr>
<tr class="b">
-<td><img src="http://www.gravatar.com/avatar/9c160b755fa13b1574d9c214cf216657?d=mm&s=60" alt="" /></td>
-<td>Jeffrey E Rodriguez</td>
-<td>jeffreyr(at)us(dot)ibm(dot)com</td>
-<td>IBM</td>
-<td>Contributor</td></tr>
-<tr class="a">
<td><img src="http://www.gravatar.com/avatar/b43882c4f565165cc1de6ae1305620b8?d=mm&s=60" alt="" /></td>
<td>Jérôme Leleu</td>
<td>leleuj(at)gmail(dot)com</td>
<td>Unknown</td>
<td>Contributor</td></tr>
-<tr class="b">
+<tr class="a">
<td><img src="http://www.gravatar.com/avatar/1a7dc8da4d6349fc13adcf7bbb8f092a?d=mm&s=60" alt="" /></td>
<td>Kristopher Kane</td>
<td>kristopherr(dot)kane(at)gmail(dot)com</td>
<td>Unknown</td>
<td>Contributor</td></tr>
-<tr class="a">
+<tr class="b">
<td><img src="http://www.gravatar.com/avatar/482d8b5aa0deb516b044de5096f95529?d=mm&s=60" alt="" /></td>
<td>Lars Francke</td>
<td>apache(at)lars-francke(dot)de</td>
<td>Unknown</td>
<td>Contributor</td></tr>
-<tr class="b">
+<tr class="a">
<td><img src="http://www.gravatar.com/avatar/7a2bbb9f860901f579acf897175d7478?d=mm&s=60" alt="" /></td>
<td>Pascal Oliva</td>
<td>poliva(at)us(dot)ibm(dot)com</td>
<td>IBM</td>
<td>Contributor</td></tr>
-<tr class="a">
+<tr class="b">
<td><img src="http://www.gravatar.com/avatar/5965a6be87c83bae9366d1c90da591cd?d=mm&s=60" alt="" /></td>
<td>Vinay Shukla</td>
<td>vinayshukla(at)gmail(dot)com</td>
<td>Hortonworks</td>
<td>Contributor</td></tr>
-<tr class="b">
+<tr class="a">
<td><img src="http://www.gravatar.com/avatar/5e885fe00c129751fcc3eae9d40c6f7d?d=mm&s=60" alt="" /></td>
<td>Yu Gau</td>
<td>crystalgaoyu(at)gmail(dot)com</td>
<td>IBM</td>
<td>Contributor</td></tr>
-<tr class="a">
+<tr class="b">
<td><img src="http://www.gravatar.com/avatar/48ff40301bb833206ebfe9a30c1d91c8?d=mm&s=60" alt="" /></td>
<td>Mohammad Kamrul Islam</td>
<td>mislam77(at)yahoo(dot)com</td>
Modified: knox/trunk/books/0.13.0/dev-guide/book.md
URL: http://svn.apache.org/viewvc/knox/trunk/books/0.13.0/dev-guide/book.md?rev=1807366&r1=1807365&r2=1807366&view=diff
==============================================================================
--- knox/trunk/books/0.13.0/dev-guide/book.md (original)
+++ knox/trunk/books/0.13.0/dev-guide/book.md Tue Sep 5 15:45:55 2017
@@ -36,6 +36,7 @@
* #[Rewrite Provider]
* #[Gateway Services]
* #[KnoxSSO Integration]
+* #[Health Monitoring API]
* #[Auditing]
* #[Logging]
* #[Internationalization]
@@ -1483,6 +1484,10 @@ TODO
<<knoxsso_integration.md>>
+### Health Monitoring API ###
+
+<<knox_monitoring_api.md>>
+
## Auditing ##
```java
Added: knox/trunk/books/0.13.0/dev-guide/knox_monitoring_api.md
URL: http://svn.apache.org/viewvc/knox/trunk/books/0.13.0/dev-guide/knox_monitoring_api.md?rev=1807366&view=auto
==============================================================================
--- knox/trunk/books/0.13.0/dev-guide/knox_monitoring_api.md (added)
+++ knox/trunk/books/0.13.0/dev-guide/knox_monitoring_api.md Tue Sep 5 15:45:55 2017
@@ -0,0 +1,366 @@
+Health Monitoring REST API
+===
+
+Knox provides REST-ful API for monitoring the core service. It primarily exposes the health of the Knox service that includes service status (up/down) as well as other health metrics. This is a work-in-progress feature, which started with an extensible framework to support basic functionalities. In particular, it currently supports the API to A) *ping* the service and B) time-based statistics related to all API calls.
+
+#### Health Monitoring Setup
+The basic setup includes two major steps A) add configurations to enable the metrics collection and reporting B) write a topology file and upload it into *topologies* directory.
+
+##### Service Configurations
+At first, we need to make sure the gateway configurations to gather and report to JMX are turned on in *gateway-site.xml*. The following two configurations into *gateway-site.xml* will serve the purpose.
+
+```
+<property>
+ <name>gateway.metrics.enabled</name>
+ <value>true</value>
+ <description>Boolean flag indicates whether to enable the metrics collection</description>
+</property>
+<property>
+ <name>gateway.jmx.metrics.reporting.enabled</name>
+ <value>true</value>
+ <description>Boolean flag indicates whether to enable the metrics reporting using JMX</description>
+</property>
+
+```
+
+##### health.xml Topology
+In order to enable health monitoring REST service, you need to add a new topology file (i.e. *health.xml*). The following is an example that is configured to test the basic functionalities of Knox service. It is highly recommended using more restricted authentication mechanism.
+
+```
+<topology>
+
+ <gateway>
+
+ <provider>
+ <role>authentication</role>
+ <name>ShiroProvider</name>
+ <enabled>true</enabled>
+ <param>
+ <!--
+ session timeout in minutes, this is really idle timeout,
+ defaults to 30 mins, if the property value is not defined,,
+ current client authentication would expire if client idles continuously for more than this value
+ -->
+ <name>sessionTimeout</name>
+ <value>30</value>
+ </param>
+ <param>
+ <name>main.ldapRealm</name>
+ <value>org.apache.hadoop.gateway.shirorealm.KnoxLdapRealm</value>
+ </param>
+ <param>
+ <name>main.ldapContextFactory</name>
+ <value>org.apache.hadoop.gateway.shirorealm.KnoxLdapContextFactory</value>
+ </param>
+ <param>
+ <name>main.ldapRealm.contextFactory</name>
+ <value>$ldapContextFactory</value>
+ </param>
+ <param>
+ <name>main.ldapRealm.userDnTemplate</name>
+ <value>uid={0},ou=people,dc=hadoop,dc=apache,dc=org</value>
+ </param>
+ <param>
+ <name>main.ldapRealm.contextFactory.url</name>
+ <value>ldap://localhost:33389</value>
+ </param>
+ <param>
+ <name>main.ldapRealm.contextFactory.authenticationMechanism</name>
+ <value>simple</value>
+ </param>
+ <param>
+ <name>urls./**</name>
+ <value>authcBasic</value>
+ </param>
+ </provider>
+
+ <provider>
+ <role>authorization</role>
+ <name>AclsAuthz</name>
+ <enabled>false</enabled>
+ <param>
+ <name>knox.acl</name>
+ <value>admin;*;*</value>
+ </param>
+ </provider>
+
+ <provider>
+ <role>identity-assertion</role>
+ <name>Default</name>
+ <enabled>false</enabled>
+ </provider>
+
+ <provider>
+ <role>hostmap</role>
+ <name>static</name>
+ <enabled>true</enabled>
+ <param><name>localhost</name><value>sandbox,sandbox.hortonworks.com</value></param>
+ </provider>
+
+ </gateway>
+
+ <service>
+ <role>HEALTH</role>
+ </service>
+
+</topology>
+```
+
+Just as with any Knox service, the gateway providers protect the health monitoring REST service defined above it. In this case, the ShiroProvider is taking care of HTTP Basic Auth using LDAP. Once the user authenticates with LDAP, the request processing continues to the *Health* service that will perform the necessary actions.
+
+The authenticate/federation provider can be swapped out to fit your deployment environment.
+
+After creating the file health.xml with above contents, you need to copy the file to *KNOX_HOME/conf/topologies* directory. If Knox/gateway service is not running, you can start it using "*bin/gateway.sh start*". Otherwise the service would automatically pick this new '*health*' service. When gateway service registers the new service, it displays the following log messages in *log/gateway.log*.
+
+```
+2017-08-22 03:44:25,045 INFO hadoop.gateway (GatewayServer.java:handleCreateDeployment(677)) - Deploying topology health to /home/joe/knox/knox-0.12.0/bin/../data/deployments/health.topo.15e080a91c0
+2017-08-22 03:44:25,045 INFO hadoop.gateway (GatewayServer.java:internalDeactivateTopology(596)) - Deactivating topology health
+2017-08-22 03:44:25,119 INFO hadoop.gateway (DefaultGatewayServices.java:initializeContribution(197)) - Creating credential store for the cluster: health
+2017-08-22 03:44:25,142 INFO hadoop.gateway (GatewayServer.java:internalActivateTopology(566)) - Activating topology health
+2017-08-22 03:44:25,142 INFO hadoop.gateway (GatewayServer.java:internalActivateArchive(576)) - Activating topology health archive %2F
+
+```
+##### Verify
+
+Once the health service is active, you can verify it by using the following *curl* command. The '*ping*' end point displays if the service is up. This end point can be utilized for monitoring the basic health of a Knox service.
+
+```
+$ curl -i -k -u guest:guest-password -X GET 'https://localhost:8445/gateway/health/v1/ping'
+HTTP/1.1 200 OK
+Date: Tue, 22 Aug 2017 07:09:37 GMT
+Set-Cookie: JSESSIONID=1o82bcvoqbhbb1apt7zs8ubybb;Path=/gateway/health;Secure;HttpOnly
+Expires: Thu, 01 Jan 1970 00:00:00 GMT
+Set-Cookie: rememberMe=deleteMe; Path=/gateway/health; Max-Age=0; Expires=Mon, 21-Aug-2017 07:09:37 GMT
+Cache-Control: must-revalidate,no-cache,no-store
+Content-Type: text/plain; charset=ISO-8859-1
+Content-Length: 3
+Server: Jetty(9.2.15.v20160210)
+
+OK
+```
+
+To retrieve the meaningful metrics details of various service calls, you may need to run multiple REST calls such as the followings. After that, execute the metrics REST call as shown below with a sample output. As shown, metrics output is returned in JSON format.
+
+```
+curl -i -k -u guest:guest-password -X GET 'https://localhost:8445/gateway/sandbox/webhdfs/v1/?op=LISTSTATUS'
+```
+```
+$ curl -i -k -u guest:guest-password -X GET 'https://localhost:8445/gateway/health/v1/metrics?pretty=true'
+HTTP/1.1 200 OK
+Date: Tue, 22 Aug 2017 07:10:44 GMT
+Set-Cookie: JSESSIONID=kqntcdaje9uai3pup7ffvfw4;Path=/gateway/health;Secure;HttpOnly
+Expires: Thu, 01 Jan 1970 00:00:00 GMT
+Set-Cookie: rememberMe=deleteMe; Path=/gateway/health; Max-Age=0; Expires=Mon, 21-Aug-2017 07:10:44 GMT
+Content-Type: application/json
+Cache-Control: must-revalidate,no-cache,no-store
+Transfer-Encoding: chunked
+Server: Jetty(9.2.15.v20160210)
+
+{
+ "version" : "3.0.0",
+ "gauges" : { },
+ "counters" : { },
+ "histograms" : { },
+ "meters" : { },
+ "timers" : {
+ "client./gateway/health/v1/metrics.GET-requests" : {
+ "count" : 5,
+ "max" : 0.624587973,
+ "mean" : 0.027655743001736188,
+ "min" : 0.006145587,
+ "p50" : 0.010020548,
+ "p75" : 0.010020548,
+ "p95" : 0.074454725,
+ "p98" : 0.624587973,
+ "p99" : 0.624587973,
+ "p999" : 0.624587973,
+ "stddev" : 0.0929226225229978,
+ "m15_rate" : 2.657500857422334E-7,
+ "m1_rate" : 5.770087852901534E-89,
+ "m5_rate" : 4.769163772973399E-19,
+ "mean_rate" : 4.0952378345310894E-4,
+ "duration_units" : "seconds",
+ "rate_units" : "calls/second"
+ },
+ "client./gateway/health/v1/ping.GET-requests" : {
+ "count" : 1,
+ "max" : 0.017257638000000002,
+ "mean" : 0.017257638000000002,
+ "min" : 0.017257638000000002,
+ "p50" : 0.017257638000000002,
+ "p75" : 0.017257638000000002,
+ "p95" : 0.017257638000000002,
+ "p98" : 0.017257638000000002,
+ "p99" : 0.017257638000000002,
+ "p999" : 0.017257638000000002,
+ "stddev" : 0.0,
+ "m15_rate" : 0.18710139700632353,
+ "m1_rate" : 0.0735758882342885,
+ "m5_rate" : 0.1637461506155964,
+ "mean_rate" : 0.014990517517814805,
+ "duration_units" : "seconds",
+ "rate_units" : "calls/second"
+ },
+ "client./gateway/sandbox/health/v1/.GET-requests" : {
+ "count" : 1,
+ "max" : 4.01873E-4,
+ "mean" : 4.01873E-4,
+ "min" : 4.01873E-4,
+ "p50" : 4.01873E-4,
+ "p75" : 4.01873E-4,
+ "p95" : 4.01873E-4,
+ "p98" : 4.01873E-4,
+ "p99" : 4.01873E-4,
+ "p999" : 4.01873E-4,
+ "stddev" : 0.0,
+ "m15_rate" : 2.536740427767808E-7,
+ "m1_rate" : 7.074903404511115E-90,
+ "m5_rate" : 4.081014139447941E-19,
+ "mean_rate" : 8.179827684854002E-5,
+ "duration_units" : "seconds",
+ "rate_units" : "calls/second"
+ },
+ "client./gateway/sandbox/v1/health/.GET-requests" : {
+ "count" : 1,
+ "max" : 5.470700000000001E-4,
+ "mean" : 5.470700000000001E-4,
+ "min" : 5.470700000000001E-4,
+ "p50" : 5.470700000000001E-4,
+ "p75" : 5.470700000000001E-4,
+ "p95" : 5.470700000000001E-4,
+ "p98" : 5.470700000000001E-4,
+ "p99" : 5.470700000000001E-4,
+ "p999" : 5.470700000000001E-4,
+ "stddev" : 0.0,
+ "m15_rate" : 2.413022137213267E-7,
+ "m1_rate" : 3.341947732164585E-90,
+ "m5_rate" : 3.512561421726287E-19,
+ "mean_rate" : 8.149518570285245E-5,
+ "duration_units" : "seconds",
+ "rate_units" : "calls/second"
+ },
+ "client./gateway/sandbox/webhdfs/v1/.GET-requests" : {
+ "count" : 4,
+ "max" : 0.463745401,
+ "mean" : 0.024924118143299912,
+ "min" : 0.016542244,
+ "p50" : 0.024799078000000002,
+ "p75" : 0.033933548,
+ "p95" : 0.033933548,
+ "p98" : 0.033933548,
+ "p99" : 0.033933548,
+ "p999" : 0.033933548,
+ "stddev" : 0.007284773511002474,
+ "m15_rate" : 2.120680068580741E-8,
+ "m1_rate" : 4.7541228609699333E-91,
+ "m5_rate" : 1.5806080232092864E-20,
+ "mean_rate" : 2.7314359915623396E-4,
+ "duration_units" : "seconds",
+ "rate_units" : "calls/second"
+ },
+ "service./gateway/sandbox/webhdfs/v1/.get-requests" : {
+ "count" : 3,
+ "max" : 0.014635496000000001,
+ "mean" : 0.00342438191233768,
+ "min" : 0.0020088890000000002,
+ "p50" : 0.0020088890000000002,
+ "p75" : 0.005144646,
+ "p95" : 0.005144646,
+ "p98" : 0.005144646,
+ "p99" : 0.005144646,
+ "p999" : 0.005144646,
+ "stddev" : 0.0015604555820128599,
+ "m15_rate" : 1.9913776931949195E-8,
+ "m1_rate" : 3.1334281325640874E-91,
+ "m5_rate" : 1.055281734633953E-20,
+ "mean_rate" : 2.0486339070804923E-4,
+ "duration_units" : "seconds",
+ "rate_units" : "calls/second"
+ }
+ }
+}
+```
+#### REST End Points
+As mentioned above, currently Knox provides a few monitoring APIs to start with. The list will gradually grow to support new use-cases.
+##### /ping
+This end-point can be used to determine if a Knox gateway service is alive or not. It is useful for basic health monitoring of the core service. Although most of the results of REST calls are in JSON format, this one (*/ping*) is in plain text.
+
+Sample response
+
+```
+OK
+```
+
+##### /metrics
+This end-point returns all Knox metrics grouped by individual call type. For example, timer metrics for all *webhdfs* calls are aggregated into one set of metrics and then returned in a separate JSON element. This end-point also supports an option (*/metrics?pretty=true*) to pretty print the metrics output.
+
+A sample response with *pretty=true* is shown below:
+
+```
+{
+ "version" : "3.0.0",
+ "gauges" : { },
+ "counters" : { },
+ "histograms" : { },
+ "meters" : { },
+ "timers" : {
+ "client./gateway/health/v1/ping.GET-requests" : {
+ "count" : 1,
+ "max" : 0.017257638000000002,
+ "mean" : 0.017257638000000002,
+ "min" : 0.017257638000000002,
+ "p50" : 0.017257638000000002,
+ "p75" : 0.017257638000000002,
+ "p95" : 0.017257638000000002,
+ "p98" : 0.017257638000000002,
+ "p99" : 0.017257638000000002,
+ "p999" : 0.017257638000000002,
+ "stddev" : 0.0,
+ "m15_rate" : 0.18710139700632353,
+ "m1_rate" : 0.0735758882342885,
+ "m5_rate" : 0.1637461506155964,
+ "mean_rate" : 0.014990517517814805,
+ "duration_units" : "seconds",
+ "rate_units" : "calls/second"
+ },
+ "client./gateway/sandbox/v1/health/.GET-requests" : {
+ "count" : 1,
+ "max" : 5.470700000000001E-4,
+ "mean" : 5.470700000000001E-4,
+ "min" : 5.470700000000001E-4,
+ "p50" : 5.470700000000001E-4,
+ "p75" : 5.470700000000001E-4,
+ "p95" : 5.470700000000001E-4,
+ "p98" : 5.470700000000001E-4,
+ "p99" : 5.470700000000001E-4,
+ "p999" : 5.470700000000001E-4,
+ "stddev" : 0.0,
+ "m15_rate" : 2.413022137213267E-7,
+ "m1_rate" : 3.341947732164585E-90,
+ "m5_rate" : 3.512561421726287E-19,
+ "mean_rate" : 8.149518570285245E-5,
+ "duration_units" : "seconds",
+ "rate_units" : "calls/second"
+ },
+ "client./gateway/sandbox/webhdfs/v1/.GET-requests" : {
+ "count" : 4,
+ "max" : 0.463745401,
+ "mean" : 0.024924118143299912,
+ "min" : 0.016542244,
+ "p50" : 0.024799078000000002,
+ "p75" : 0.033933548,
+ "p95" : 0.033933548,
+ "p98" : 0.033933548,
+ "p99" : 0.033933548,
+ "p999" : 0.033933548,
+ "stddev" : 0.007284773511002474,
+ "m15_rate" : 2.120680068580741E-8,
+ "m1_rate" : 4.7541228609699333E-91,
+ "m5_rate" : 1.5806080232092864E-20,
+ "mean_rate" : 2.7314359915623396E-4,
+ "duration_units" : "seconds",
+ "rate_units" : "calls/second"
+ }
+ }
+}
+```