svn commit: r1356597 - in /incubator/stanbol/site/trunk/content/stanbol/docs/trunk/utils: ./ enhancerstresstest.mdtext

[rw...@apache.org]

Author: rwesten
Date: Tue Jul  3 07:51:32 2012
New Revision: 1356597

URL: http://svn.apache.org/viewvc?rev=1356597&view=rev
Log:
Documentation for the Stanbol Enhancer Stress Test Utility

Added:
    incubator/stanbol/site/trunk/content/stanbol/docs/trunk/utils/
    incubator/stanbol/site/trunk/content/stanbol/docs/trunk/utils/enhancerstresstest.mdtext

Added: incubator/stanbol/site/trunk/content/stanbol/docs/trunk/utils/enhancerstresstest.mdtext
URL: http://svn.apache.org/viewvc/incubator/stanbol/site/trunk/content/stanbol/docs/trunk/utils/enhancerstresstest.mdtext?rev=1356597&view=auto
==============================================================================
--- incubator/stanbol/site/trunk/content/stanbol/docs/trunk/utils/enhancerstresstest.mdtext (added)
+++ incubator/stanbol/site/trunk/content/stanbol/docs/trunk/utils/enhancerstresstest.mdtext Tue Jul  3 07:51:32 2012
@@ -0,0 +1,115 @@
+Title: Stanbol Enhancer Stres Test Utility
+
+As of [STANBOL-670](https://issues.apache.org/jira/browse/STANBOL-670) Apache Stanbol provides an utility that allows users to stress test the Stanbol Enhancer by using multiple concurrent requests. This might be useful for both: (1) Stanbol Users that want to check if their Stanbol installation can cope with those situations and how different [Enhancement Chain](../enhancer/chains) configurations do affect processing times. (2) [Enhancement Engine](../enhancer/engines) developers that want to test their engines and maybe also services called by those engines.
+
+In addition this Utility also provides some statistics including
+
+* __Round Trip Time__: The whole request/response time including sending - request transmission - server side parsing - processing - server side serialization - response transmission and client side parsing.
+* __Enhancement Chain processing__: This is the time needed by the [EnhancementJobManager](../engines/enhancementjobmanager.html) to process the [ContentItem](enhancer/contentitem.html). This data are provided by the [Execution Metadata](../enhancer/executionmetadata.html)
+* __EnhancementEngine processing__: Also the processing times of all [Enhancement Engines](../enhancer/engines) used in the tested [Enhancemet Chain](../enhancer/chain) are tracked. Those data are also provides by the [Execution Metadata](../enhancer/executionmetadata.html)
+
+## Usage
+
+This utility is part of the Apache Stanbol Integration tests and is also run during normal builds against the default chain of the Stanbol Enhancer. As any integration test it can be also run standalone and against Stanbol Servers running at a configured URL.
+
+To use this tool you need to [checkout and build](introduction.html) Apache Stanbol and than change to the <code>{stanbol-source}/integration-tests</code> directory. Within this directory one can now call this utility using
+
+    :::bash
+    mvn -o test -Dtest.server.url={stanbol-server} -Dtest=MultiThreadedTest
+
+this will make 500 requests with 5 concurrent threads on the {stanbol-server} using [DBpedia.org](http://dbpedia.org) abstracts as content. The integration-test includes up to 10000 those abstracts that can be used for testing.
+
+This utility can be configured using the following system properties:
+
+* __test.server.url__: The URL of the Apache Stanbol instance that will be used for testing (e.g. http://localhost:8080)
+* __test__: The simple class name of the integration test to run. To use this tool this MUST BE set to '<code> MultiThreadedTest</code>'.
+*__stanbol.it.multithreadtest.chain__: The name of the enhancement chain to test. If not present the default chain will be tested.
+* __stanbol.it.multithreadtest.data__: Allows to specify the data used for the tests. Files, Resources available via the class path and URLs are supported. Referenced data may be compressed using 'gz' and 'bz2'. 'zip' is also supported however only the first entry of the ZIP file is processed. Supported data formats include plain text and RDF serializations supported by Apache Clerezza. See the section about Test Data for details.
+* __stanbol.it.multithreadtest.media-type__: While the Tool supports auto-detection of the 'Media-Type' for common file endings (e.g. *.txt, *.rdf, …) this property can be used to manually specify the media type. In addition it allows to parse the charset used for plain text files (e.g. "text/plain;charset=UTF-8) 
+* __stanbol.it.multithreadtest.data-property__: In case RDF is used for test data this can be used to specify the property of triples their values are used as test data. If '*' is parsed all triples with Literals as values will be used. '<code>http://dbpedia.org/ontology/abstract</code>' is used as default if this property is missing.
+* __stanbol.it.multithreadtest.threads__: The number of concurrent threads used during stress testing. The default is 5.
+* __stanbol.it.multithreadtest.requests__: The maximum number of requests. This only applies if the configured data set would provide more data items. By default this is set to 500. This can be deactivated by setting to values less equals than 0.
+* __stanbol.it.multithreadtest.rdf-format__: The RDF serialization used for the '<code>Accept</code>' header in enhancement requests. Apache Stanbol will send Enhancement Results using this format. The default is '<code>application/rdf+json</code>'
+
+Here is an example that makes extensive use of custom options:
+
+    :::bash
+    mvn -o test -Dtest=MultiThreadedTest \
+        -Dstanbol.it.multithreadtest.data=/stanbol/test/data/stanbol-test-data.txt.gz \
+        -Dstanbol.it.multithreadtest.requests=10000 \
+        -Dstanbol.it.multithreadtest.threads=20 \
+        -Dstanbol.it.multithreadtest.rdf-format=text/turtle \
+        -Dtest.server.url=http://www.example.org:8080/stanbol
+
+_NOTES:_
+
+* With Java System properties are parsed using '<code>-D{property}={value}</code>'
+* If you get OutOfMemory errors you might need to increase the memory of the '<code>Xmx</code>' parameter of the '<code>MAVEN_OPTS</code>' system variable. This might especially happen if you use RDF data for your test as those are loaded into memory.
+
+## Test Data
+
+Thie tool supports two different test data formats
+
+### Plain Text Files
+
+All test data are within a single text file. Single texts are separated by two (or more) empty lines.
+
+The following example includes three content items:
+
+    :::text
+    Astronomers discover largest star on record
+    
+    European astronomers have discovered the largest star yet on record; it is 300 times the mass of our sun, beyond the previously accepted limit of 150 solar masses.
+
+    Paul Crowther, professor of astrophysics at […]
+    
+    
+    Australian election debate moved to avoid clash with cookery show
+
+    A televised debate between Australia's candidates for Prime Minister […]
+    
+    
+    The Only Joy In Town
+
+    by Joni Mitchell   
+
+    I want to paint a picture
+    Botticelli * style
+    Instead of Venus on a clam *
+    I'd paint this flower child
+
+Plain text test data are read sequentially from the provided source. This ensures that only ~100 content items are loaded into memory at any given time. So this is the preferred option for large test data sets.
+
+Text files can recognized by the file ending "txt" to the parsed resource. For resources with other engines the property '<code>stanbol.it.multithreadtest.media-type=text/plain</code>' must be specified. If the test data are not encoded using '<code>UTF-8</code>' the charset MUST BE parsed by using the '<code>charset</code>' parameter (e.g. '<code>stanbol.it.multithreadtest.media-type=text/plain;charset=iso-8859-7</code>').
+
+### RDF data
+
+The tool also allows to use RDF graphs as test data. This is mainly because in a lot of cases it is the easiest to use RDF dumps of public datasets - such as DBpedia.org - for testing. Users need to be aware that RDF data are imported into an in-memory graph.
+
+Content Items are extracted by
+
+* Filtering Triples that use the value configured by '<code>stanbol.it.multithreadtest.data-property</code>' as property ('<code>{prefix}:{local-name}</code>' is supported for registered prefixes). As default '<code>http://dbpedia.org/ontology/abstract</code>' is used. If '<code>*</code>' is configured than all triples are taken into account.
+* Filter Triples that have a Literal value as Object
+
+Supported RDF formats and mapped file endings:
+
+* '<code>application/rdf+xml</code>' - file endings '<code>.rdf</code>' and '<code>.xml</code>'
+* '<code>text/turtle</code>' - file ending '<code>.ttl</code>'
+* '<code>application/x-turtle</code>' - no file endings
+* '<code>text/rdf+nt</code>' - file endings '<code>.nt</code>'
+* '<code>text/rdf+n3</code>' - file endings '<code>.n3</code>'
+* '<code>application/rdf+json</code>' - file endings '<code>.json</code>'
+
+If you want to use a different file ending you need to parse the Media-Type using the '<code>stanbol.it.multithreadtest.media-type</code>' property
+
+### Support for compressed test data
+
+Bot plain text and RDF data can be efficiently compressed. Because of that this utility also supports compressed files. The compression format is detected by the file ending.
+
+Supported are
+
+* '<code>.gz</code>'
+* '<code>.bz2</code>'
+* '<code>.zip</code>' - only the first entry in the ZIP archive is processed
+
+Compressed files need to use double endings (e.g. '<code>test-data.txt.gz</code>' or '<code>test-data.rdf.bz2</code>').
\ No newline at end of file