dashboard/lib/static/doc/_sources/server.txt

Logging Server Implementation Details
=====================================

JSON messages using HTTP POST requests.
---------------------------------------

The Draper Activity Logging Server accepts log messages as json strings in HTTP POST requests. We hope that the vast majority developers have no need to know about these implementation details, as they will use one of the helper libraries provided by Draper Laboratory to automatically encode and transmit log messages. See section 3 above for information about these helper libraries. 

Why JSON + HTTP?
----------------
Leveraging HTTP to transmit log messages will allow us to transmit messages even when code is executed in a highly restricted runtime, such as client-side javascript code. It also offers maximum compatibility with current and future network topologies, since any network allowing web traffic will allow for HTTP communication. In addition, a natural path to encrypting activity log transmission exists in the form of HTTPS. 

Encoding log messages as JSON strings allows for relatively human-readable log messages, a flexible data format that allows for transmission of complex, nested data structures, and excellent encoding support in a wide variety of programming languages. 


Messaging Diagram

Activity Log Data as JSON Strings
--------------------------------------
The specific fields to be included in each log message were described earlier in this document (see :ref:`message-reqs`). A JSON string is generated with this information by the following steps: 

1. The values of componentName and componentVersion as defined in Section 2.1 of this document are stored in the keys component.name and component.value, respectively. 
2. The value of desc is stored in the key params.desc
3. All other values specified in Section 2.1 are stored using their title as a key.
4. All the values specific to one kind of log message for example, activity and wf_state in the case of User Activity log messages, are stored in the key params. 
5.  Any optional metadata is stored as a JSON object in the meta. 
Example encoded log messages: 

A System Activity message with metadata

.. code-block:: json

   {
	   "timestamp":"2013-09-21T19:29Z",
	   "client":"xDATAClient23",
	   "component":{
	      "name":"pyTestComp",
	      "version":"34.87"
	   },
	   "sessionID":4593,
	   "impLanguage":"Java",
	   "apiVersion":2,
	   "type":"SYSACTION",
	   "params":{
	      "desc":"TEST SYSTEM MESSAGE"
	   },
	   "meta":{
	      "testQual":"quall",
	      "testQuant":3
	   }
	}

A User Activity message

.. code-block:: json
	
	{
	   "timestamp":"2013-09-21T19:29Z",
	   "client":" xDATAClient23",
	   "component":{
	      "name":"pyTestComp",
	      "version":"34.87"
	   },
	   "sessionID":4593,
	   "impLanguage":"Java",
	   "apiVersion":2,
	   "type":"USERACTION",
	   "params":{
	      "desc":"TEST USER MESSAGE",
	      "activity":"scaleHistogram",
	      "wf_state":6,
	      "wfCodeVersion":1
	   }
	}

A User Activity message with metadata

.. code-block:: json

	{
	   "timestamp":"2013-09-21T19:29Z",
	   "client":"xDataClient23",
	   "component":{
	      "name":"pyTestComp",
	      "version":"34.87"
	   },
	   "sessionID":4593,
	   "impLanguage":"Java",
	   "apiVersion":2,
	   "type":"USERACTION",
	   "params":{
	      "desc":"TEST USER MESSAGE",
	      "activity":"scaleHistogram",
	      "wf_state":4,
	      "wfCodeVersion":1
	   },
	   "meta":{
	      "testQual":"quall",
	      "testQuant":3
	   }
	}