Skip to content
develop
Switch branches/tags
Code

Latest commit

 

Git stats

Files

Permalink
Failed to load latest commit information.
Type
Name
Latest commit message
Commit time
 
 
 
 
 
 
 
 

Addon: exo-analytics

An addon that provide tools to display platform usage statistics using charts.

Compatibility

The exo-analytics addon is compatible on the following dependencies versions :

Addon version JDK Elasticsearch eXo Platform
exo-addons:1.0.0-M01 8 5.6 6.0

Prerequisites

The addon requires eXo Platform with embedded Elasticsearch version inside eXo Platform (default configuration) or in a standalone Elasticsearch server configured. See Elasticsearch configuration in eXo Platform

How to install

  1. Go to eXo Platform Tomcat server Home
  2. Install exo-analytics addon using command line:
# Replace version by the needed version of addon, like 1.0.x-SNAPSHOT or 1.0.0-M01
./addon install exo-analytics:VERSION
  1. Start eXo Platform

Configuration options

You can can change some options of the addon using properties that you can add into exo.properties file

VARIABLE MANDATORY DEFAULT VALUE DESCRIPTION
exo.analytics.admin.permission NO *:/platform/analytics Group of users that can modify Charts application settings. All other users, even members of /platform/administrators will not be able to modify charts settings
exo.analytics.viewall.permission NO *:/platform/administrators Group of users that can consult all data in Graphs.
exo.analytics.view.permission NO *:/platform/users Group of users that can consult their personal and their spaces Graphs.
exo.analytics.aggregation.terms.doc_size NO 200 Limit of number of resturned documents in aggregations result of type 'terms' (not used for aggregations of type : sum, avg, date_histogram, histogram and cardinality)
exo.addon.analytics.es.mapping.path NO jar:/analytics-es-mapping.json Initial ES mapping that will be used to generate daily ES index
exo.cache.analytics.queue.MaxNodes NO 2000 Number of maximum entries in in-memory cached Analytics Queue that is processed each 10 seconds
exo.cache.analytics.queue.TimeToLive NO -1 lifetime of entries in Analytics Queue. Default: infinite.
exo.es.analytics.index.server.url NO Same as used ES for eXo Elasticsearch server URL used for indexing and searching analytics content
exo.es.analytics.index.server.username NO Same as used ES for eXo Elasticsearch server username used for indexing and searching analytics content
exo.es.analytics.index.server.password NO Same as used ES for eXo Elasticsearch server password used for indexing and searching analytics content
exo.es.analytics.index.per.day YES true Whether create one index per day or not. You can switch this flag to true or false whener you want, it will not affect retrieved data result. In fact, the Analytics engine searches in all present indexes in server by including systematically a documents field filter that is added automatically to all statistics data : isAnalytics = true
exo.es.analytics.index.prefix YES analytics Elasticsearch index names prefix. IT will be exactly equals to this value when exo.es.analytics.index.per.day=false, else the index names will be of pattern ${exo.es.analytics.index.prefix}_NUMBER_OF_DAYS

How to build addon

  1. install Apache maven 3.5+
  2. Go to Home path of addon
  3. Execute the following command :
mvn clean verify -Prun-its

How to use it

Once the addon installed and eXo Platform started, and after logged-in on eXo, you can follow those steps:

  1. Add a user into analytics administrators (Under Platform => Analytics) group using group managment UI
  2. Go to application registry and add Analytics portlet in an application category
  3. Go to home page and add a new page in current site
  4. You can add multiple instances of analytics portlet inside the page to show multiple statistics data
  5. Save the page

You will see the analytics application added in your page and displaying by default a default chart including all statistics data. You can change settings of each application to show you different charts type, title and statistics data.

By default, the user root is a member of /platform/*analytics* group, so he can see the charts, while for other users (if you added right access permissions on page and added portlets in page), he will see only his data without being able to change charts settings. In fact, the user and space filtering on statistics data is made automatically switch loggedin user and page context (inside a space or in public page)

The default collected statistics data are:

Technical note: By default, the produced and persisted statistic samples/data by those listeners has basic properties stored into it and that could be extended any time because a dynamic mapping is used on each daily created Elasticsearch index.

The default produced data for all events in general:

  • id : Technical id of statistics sample
  • spaceId : Technical id of space (space name is displayed in UI in list of samples) (Perspective: could be retrieved using suggester for data filtering and charts setttings)
  • userId : Technical id of user making the event (user display name is displayed in UI in list of samples) (Perspective: could be retrieved using suggester for data filtering and charts setttings)
  • module : eXo project name: social, portal...
  • subModule : activity, space, login, relationship, profile, relationship...
  • operation : type of made operation, like createActivity, login, logout, login, confirmed...
  • status : status of operation OK if operation succeeded else KO
  • timestamp : time of statistic event in ms

Specifically for each listener, it has default produced data are: (data can be extend, like adding number of likes, comments...)

  • Activity statistic data:
    • module = social
    • subModule = activity
    • operation =
      • createActivity
      • updateActivity
      • createComment
      • updateComment
      • likeActivity
      • likeComment
    • streamIdentityId : Technical identity ID of stream owner (Space ID or User ID) (Perspective: could be retrieved using suggester for data filtering and charts setttings)
    • activityId : Technical activity ID
    • commentId : Technical comment ID
    • subCommentId : Technical sub comment ID
    • activityType : activity type, like : exosocial:people, USER_PROFILE_ACTIVITY... (See complete list of actitivy types)
  • Space statistic data:
    • module = social
    • subModule = space
    • operation =
      • spaceAccessEdited
      • spaceBannerEdited
      • spaceCreated
      • spaceRemoved
      • spaceRenamed
      • spaceDescriptionEdited
      • spaceRegistrationEdited
      • spaceAvatarEdited
      • applicationActivated
      • applicationDeactivated
      • applicationRemoved
      • grantedLead
      • joined
      • revokedLead
      • addInvitedUser
      • addPendingUser
    • modifierUserId: Technical identity ID of user having modified portlet (Perspective: could be retrieved using suggester for data filtering and charts setttings)
    • spaceTemplate: space template name
  • Login statistic data:
    • module = portal
    • subModule = login
    • operation =
      • login
      • logout
  • User statistic data:
    • module = organization
    • subModule = user
    • operation =
      • createUser
      • saveUser
      • enableUser
      • deleteUser
    • isEnabled : if user is enabled
  • Profile statistic data:
    • module = social
    • subModule = profile
    • operation =
      • avatar
      • banner
      • contactSection
      • experienceSection
      • createProfile
  • Relationship statistic data:
    • module = social
    • subModule = relationship
    • operation =
      • avatar
      • banner
      • contactSection
      • experienceSection
      • createProfile
    • from: Technical identity ID of user (Perspective: could be retrieved using suggester for data filtering and charts setttings)
    • to : Technical identity ID of user (Perspective: could be retrieved using suggester for data filtering and charts setttings)
  • Displayed page statistics data
    • module = portal
    • subModule =
      • webui (in case of WebUI ajax query)
      • page (in case of page display)
    • operation =
      • ajaxRequest (in case of WebUI ajax query)
      • pageDisplay (in case of page display)
    • spaceTemplate = Current space template
    • userLocale = Current user locale
    • portalOwner = Current PORTAL site (dw, intranet, ...)
    • portalUri = Current URI
    • pageUri = Current page URI (without portal URI, like 'documents', 'activities', 'wiki/user/root' )
    • pageName = current page name/uri last part
    • httpRequestMethod
    • httpRequestUri
    • httpRequestProtocol
    • httpRequestMethod
    • httpRequestContentType
    • httpRequestContentLength
    • httpResponseContentType
    • httpResponseContentLength
    • httpResponseStatus
  • Extensible UI and DOM Events statistics data:
    • module = portal
    • subModule = ui
    • portalUri = current portal URI when user triggered the event
    • For DOM event Home page link :
      • watcher = Home page link (defined by configuration)
      • ui = toolbar (defined by configuration)
      • application = NavigationToolbarPortlet (defined by configuration)
      • operation = click (defined by configuration)
      • dom-href = link of target page (defined by configuration)
      • dom-class = DOM class value of element having triggered the event(defined by configuration)
      • dom-id = DOM class value of element having triggered the event(defined by configuration)
      • event-type = event type having triggered the event (defined by configuration)
      • event-pageX: horizontal coordinate of Element having triggered the event (defined by configuration)
      • event-pageY: vertical coordinate of Element having triggered the event (defined by configuration)
    • For DOM event Hamburger menu icon :
      • watcher = Hamburger menu icon (defined by configuration)
      • ui = toolbar (defined by configuration)
      • application = HamburgerNavigationMenuLink (defined by configuration)
      • operation = click (defined by configuration)
      • event-type = event type having triggered the event (defined by configuration)
      • event-pageX: horizontal coordinate of Element having triggered the event (defined by configuration)
      • event-pageY: vertical coordinate of Element having triggered the event (defined by configuration)
    • For DOM event Hamburger menu site navigation link :
      • watcher = Hamburger menu site navigation link (defined by configuration)
      • ui = HamburgerMenu (defined by configuration)
      • application = SiteHamburgerNavigation (defined by configuration)
      • operation = click (defined by configuration)
      • dom-href = link of target page (defined by configuration)
      • dom-data-aria-selected = DOM aria-selected data value, used to determine whether the element is current page or not. (defined by configuration)
      • event-type = event type having triggered the event (defined by configuration)
      • event-pageX: horizontal coordinate of Element having triggered the event (defined by configuration)
      • event-pageY: vertical coordinate of Element having triggered the event (defined by configuration)
    • For DOM event Hamburger menu spaces navigation link :
      • watcher = Hamburger menu spaces navigation link (defined by configuration)
      • ui = HamburgerMenu (defined by configuration)
      • application = SpacesHamburgerNavigation (defined by configuration)
      • operation = click (defined by configuration)
      • dom-href = link of target page (defined by configuration)
      • dom-data-aria-selected = DOM aria-selected data value, used to determine whether the element is current page or not. (defined by configuration)
      • event-type = event type having triggered the event (defined by configuration)
      • event-pageX: horizontal coordinate of Element having triggered the event (defined by configuration)
      • event-pageY: vertical coordinate of Element having triggered the event (defined by configuration)
    • For DOM event Activities refresh button :
    • For DOM event Post activity using Composer Drawer :
    • For DOM event Post activity using legacy Composer :

You can consult the data used to display analytics chart using View samples button on each portlet. By viewing samples, you will be able to know what fields to use in settings to :

  • choose X Axis field (date by default)
    • Per day
    • Per week
    • Per month
    • Per quarter
    • Per year
    • Per custom field : you can choose a custom field from the selectbox: for now, the fields are retrieved without name, just its technical name that you can find in displayed statistic samples/data in drawer. For example, if you choose spaceId, then in the X Axis, you will get the space name.
  • choose Y Axis:
    • count of statistic samples/data per choosen X Axis field (date period or custom field)
    • count samples with distinct fields. For example, to get the number logins per 'unique users' per day, you will choose Per day as X Axis and this option as Y Axis.
    • sum of statistic samples/data numeric field : this will display in Y Axis the sum of a specific Numeric field.
    • average of statistic samples/data numeric field : this will display in Y Axis the average rate of a specific Numeric field.
  • Data filters : a list of conditions on to filter on used data in computing results
  • Multiple charts :
    • When enabled, this will display multiple charts in one single.

Examples of settings

For example, if you want to display the number of created activities per day and per space (pay attention to the number of spaces).

ou can choose the following parameters:

  • X Axis = Per day
  • Y Axis = count samples
  • Multiple charts = true, in addition choose field spaceId (a chart will be retrieved per spaceId)
  • Data filters : ** operation (equals) createActivity ** spaceId (greater) 1 (or if you have a lot of spaces, you will have to choose a set of spaceId, like : spaceId (in set) 1,2,3,895)

DOM Events configuration plugin

In order to add new DOM Event watcher, you can add a component-plugin to inject into Service org.exoplatform.analytics.api.service.AnalyticsService. (You can follow some example from here)

The DOM statistic data are collected in a sync way, but sent to server in async way in a dedicated Process using Cometd Worker (used parameter: useWorkerScheduler)

To understand more about properties of plugin, please read the commented description in the following example:

    <component-plugin>
      <name>Home page link</name>
      <set-method>addUIWatcherPlugin</set-method>
      <type>org.exoplatform.analytics.api.service.StatisticUIWatcherPlugin</type>
      <init-params>
        <object-param>
          <name>watcher</name>
          <object type="org.exoplatform.analytics.api.service.StatisticWatcher">
            <!-- CLIENT SIDE: DOM jquery selector, used to install watcher in UI to trigger new statistic data item to server -->
            <field name="domSelector">
              <string>#brandingTopBar a</string>
            </field>
            <!-- CLIENT SIDE: DOM jquery event that will be used to listen on selected element -->
            <field name="domEvent">
              <string>mousedown</string>
            </field>
            <!-- GENERATED STATISTIC DATA PROPERTY: `name` field -->
            <field name="name">
              <string>Home page link</string>
            </field>
            <!-- GENERATED STATISTIC DATA PROPERTY: `operation` field -->
            <field name="operation">
              <string>click</string>
            </field>
            <!-- GENERATED STATISTIC DATA PROPERTY: additional embedded parameters to include in generated statistic data. This can be useful to classify triggired event by category, sub-category... This will help to make easier aggregations on data -->
            <field name="parameters">
              <map type="java.util.HashMap">
                <entry>
                  <key>
                    <string>ui</string>
                  </key>
                  <value>
                    <string>toolbar</string>
                  </value>
                </entry>
                <entry>
                  <key>
                    <string>application</string>
                  </key>
                  <value>
                    <string>NavigationToolbarPortlet</string>
                  </value>
                </entry>
              </map>
            </field>
            <!-- GENERATED STATISTIC DATA PROPERTY: used to store additional information in generated statistic data. This will get the following properties of `DOM event` object -->
            <field name="domEventProperties">
              <collection type="java.util.ArrayList" item-type="java.lang.String">
                <value>
                  <string>type</string>
                </value>
                <value>
                  <string>pageX</string>
                </value>
                <value>
                  <string>pageY</string>
                </value>
              </collection>
            </field>
            <!-- GENERATED STATISTIC DATA PROPERTY: used to store additional information in generated statistic data. This list of DOM properties will be retrieved using jQuery(...).attr(), else if not exists, jQuery(...).data() will be used -->
            <field name="domProperties">
              <collection type="java.util.ArrayList" item-type="java.lang.String">
                <value>
                  <string>href</string>
                </value>
                <value>
                  <string>class</string>
                </value>
                <value>
                  <string>id</string>
                </value>
              </collection>
            </field>
          </object>
        </object-param>
      </init-params>
    </component-plugin>

Issues

If you have an issue with the addon, you can ask your question in eXo Tribe or report your issue in current github repository.

About

An addon that provide tools to display platform usage statistics using charts.

Resources

License

Packages

No packages published