Skip to content

EEXCESS Logging

Jump to bottom Edit New page
Thomas Cerqueus edited this page Oct 13, 2015 · 10 revisions

Overview

The format described in the following will replace the old logging format mentioned here. The following interactions can be logged on the Privacy Proxy (all including a timestamp, userID and origin):

  • query/details query sent by the client (+ whole user profile as shown below)
  • response/details response from the federated recommender (+ weighted query keywords, federated response and queryID)
  • open/close a module (+ name and optionally duration)
  • Interactions with an item:
    • open/close an item (+ documentBadge, queryID and optionally duration)
    • cite an item (as image, text or hyperlink and queryID)
    • rate an item (+ documentBadge, rating value and queryID)

Notes:

  • A module refers to any self-contained component on the client, which allows user interactions. For example: SearchResultList, Dashboard, Facetscape, etc.
  • An item refers to any resource delivered by the EEXCESS-framework

Two types of logging are performed on the Privacy Proxy.

  1. Queries and responses are logged implicitly. This means, the Privacy Proxy logs all queries and responses that it forwards. This also applies to details-queries and details-responses.
  2. Any other information is logged by explicitly calling methods of the logging-API provided by the Privacy Proxy.

Main attributes

In the query and response format between a client and the Privacy Proxy, there are three attributes that are particularly important for the logging functionality. Developers are asked to provide these attributes when they send queries or make calls to the logging endpoints:

  • origin An object, identifying the client, module and user. Required for all queries and calls to logging endpoints.
    • clientType: A String that identifies the client.
      For example: "EEXCESS - Google Docs Plugin", "EEXCESS - Moodle Plugin", "EEXCESS - WordPress Plugin", etc. You are free to choose the name of your client.
    • clientVersion: A String for versioning the client.
    • module: A String that identifies the module.
      One of {"SearchResultList", "Dashboard", "Facetscape", "QueryCrumbs"}
    • userID: A string that identifies the user.
      To generate a globally unique ID for a user, compute a hash of (clientType + something that identifies a user on your client)
"origin": {
    "clientType": "EEXCESS - Google Chrome Extension",
    "clientVersion": "2.0",
    "module": "SearchResultList",
    "userID": "E993A29B-A063-426D-896E-131F85193EB7"
}
  • queryID A string identifying the query. The queryID is generated on the Privacy Proxy and returned as an attribute in the response format. Required for detailed-queries and calls to logging-endpoints. 
"queryID": "A33B29B-BC67-426B-786D-322F85182DA6"
  • loggingLevel An integer, specifying if the query should be logged. Optional for all queries. 
/* If the attribute is not provided or the value is set to 0, the query and response will be logged by default.*/
/* Logging can be disabled by explicitly setting loggingLevel = 1*/
"loggingLevel": 0

Client-developers need to provide a static origin-object for each module they use and include this object in all queries and logging-calls.
Client-developers need to keep track of the queryID returned in the response to each query. It must be included in all detailed-queries and logging-calls.
Client-developers can include loggingLevel in the query format to suppress implicit logging of queries.

Implicit Logging

Query Format

See the full documentation of the Privacy Proxy Query Format.

Response Format

See the full documentation of the Privacy Proxy Response Format

Explicit Logging

The API is accessible at

http://{SERVER}/eexcess-privacy-proxy-1.0-SNAPSHOT/api/v1

and it accepts parameters as application/json. The input format to the various API-endpoints looks like this:

{
    /* Mandatory for all logs */
    "origin": {
       "clientType": "EEXCESS - Google Chrome Extension",
       "clientVersion": "2.0",
       "module": "Facetscape",
       "userID": "E993A29B-A063-426D-896E-131F85193EB7"
    },
    /* The data to log is wrapped inside the ´content´ attribute */
    "content": {
       ...
    },
    /* Optional for some logs */
    "queryID": "A33B29B-BC67-426B-786D-322F85182DA6"
}

The expected format within the content attribute and the presence of the queryID depend on the type of interaction to log.

Endpoints

There are the following endpoints available:

  • /log/moduleOpened module opened by the user
    Method: POST
    Input: origin, content.name

  • /log/moduleClosed module closed by the user
    Method: POST
    Input: origin, content.name, content.duration

  • /log/moduleStatisticsCollected logs collected by a module. A module can collect usage statistics on its own responsibility and use this endpoint to log the data.
    Method: POST
    Input: origin, content.<various>

  • /log/itemOpened item opened by the user
    Method: POST
    Input: origin, queryID, content.documentBadge

  • /log/itemClosed item closed by the user
    Method: POST
    Input: origin, queryID, content.documentBadge, content.duration

  • /log/itemCitedAsImage item cited in a document as an image
    Method: POST
    Input: origin, queryID, content.documentBadge

  • /log/itemCitedAsText items are cited in a document as an text
    Method: POST
    Input: origin, queryID, content.documentBadge

  • /log/itemCitedAsHyperlink items are cited in a document as an hyperlink
    Method: POST
    Input: origin, queryID, content.documentBadge

  • /log/itemRated rating of an item
    Method: POST
    Input: origin, queryID, content.documentBadge, content.rating

As a client-developer you should not call these endpoints directly but use the client-logging API instead.

Input Formats

content.name

{
   ...,
   "content": {
       "name": "SearchResultList"
   }
}

content.duration

{
   ...,
   "content": {
       /* Duration indicates the number of milliseconds the user spent on watching */  
       /* the detailed view of an item or how long she used a module */
       "duration": 64095
   }
}

content.documentBadge

{
   ...,
   "content": {
       "documentBadge": {
            /*Document identifier*/
            /*Datatype: String*/
            "id":"sl23394330",
            /*Uri of the document*/
            /*Datatype: String*/
            "uri":"http://service.wissens-server.com/wissensserver/view.html?a=t&r=CURRENT&i=sl23394330&s=BEP&v=eexcess&w=EEXCESS",
            /*Source which produced the result./
            /*Datatype: String*/
            "provider":"Wissenmedia"
      }
   },
   ...
}

content.rating

{
   ...,
   "content": {
       "documentBadge": {
            "id":"sl23394330",
            "uri":"http://service.wissens-server.com/wissensserver/view.html?a=t&r=CURRENT&i=sl23394330&s=BEP&v=eexcess&w=EEXCESS",
            "provider":"Wissenmedia"
       },
       "rating": {
            "minRating": 1,
            "maxRating": 2,
            "rating": 2
       }
   },
   "queryID": "A33B29B-BC67-426B-786D-322F85182DA6"
}

Output Formats

The Privacy Proxy stores the log entries as json-objects. An entry in the log file has the format:

{
    “interactionType”: “...”,
    “timestamp”: “1234567890”, 
    “IP”: “132.231.111.197”,
    “origin”: {
        “userID”: “E993A29B-A063-426D-896E-131F85193EB7”, 
        “clientType”: “EEXCESS - Google Chrome Extension”, 
        “clientVersion”: “2beta”, 
        “module”: “facetScape”
    }, 
    “content”: { … }, 
    “queryID”: "A33B29B-BC67-426B-786D-322F85182DA6"
}

interactionType is a String indicating the type of interaction that was logged. The content of the content attribute is identical to the content you provided in the input format mentioned above. The following list shows the different interactionTypes and the content of the content attribute that is stored in the log-file:

  • "query": Query Format
  • "response": Response Format
  • "detailsQuery": Details Query
  • "detailsResponse": Details Response
  • "moduleOpened": content.name
  • "moduleClosed": content.name, content.duration
  • "moduleStatisticsCollected": content.<various>
  • "itemOpened": content.documentBadge
  • "itemClosed": content.documentBadge, content.duration
  • "itemCitedAsImage": content.documentBadge
  • "itemCitedAsText": content.documentBadge
  • "itemCitedAsHyperlink": content.documentBadge
  • "itemRated": content.documentBadge, content.rating

Client-API

As a client-developer you don't need to call the logging-endpoints yourself. EEXCESS provides a client-side logging-API which is part of the c4-repository. (available soon)

=== PRELIMINARY

A preliminary version is available in the 'develop'-branch of 'visualization-widgets'-repository.

visualization-widgets/examples/c4/logging.js provides methods to log the interactionTypes mentioned above. Please have a look at visualization-widgets/examples/loggingIndex.html to see a basic example of how logging can be integrated into a dummy client-application that embeds a dummy module 'LoggingTestModule'.

The example is already adjusted to the new query and response format. Once the servers adopt the new format as well, you should not see ServerErrors anymore.

Add a custom footer
Add a custom sidebar
Clone this wiki locally