Welcome to the Getting Started with the Analytics service. This page is the starting point for learning about the Analytics service. The following topics are covered:
The Analytics service application was created to complement the use of dojox.analytics and related plug-ins from the Dojo Toolkit for JavaScript. Analytics provides a way to track events (Dojo, mouse clicks, and so on) and generate logging from the client-side code. The analytics information is often managed on the client and sent to potentially several different analytics servers. This can be cumbersome and often requires communication with domains outside of the server that provided the application. The Analytics service provides a way to handle the multiplexing of analytics and logging on the server side. The existing dojox.analytics code on the client sends the events to the same server that provided the application, which eliminates any cross domain issues.
On the server, the Analytics service application includes a server-side JAX-RS resource that accepts the requests sent from the clients dojox.analytics code. Servlet initialization parameters can be set in the Analytics service application to configure how it handles the analytics events. By default, all events are sent to a single log file, analytics_default.log.
Product prerequisite | Version |
---|---|
Java Technology Edition | 5.0 and later |
Java Platform, Enterprise Edition 5 (Java EE) application server and later | WebSphere Application Server Version 6.1.0.x and later WebSphere Application Server Community Edition Version 2.X |
Web browser | Any modern web browser, such as Internet Explorer 7 and later, Mozilla Firefox 3.x and later, Google Chrome, Safari, Opera |
The Analytics service is only useful if the client side JavaScript is leveraging dojox.analytics. To access the tools from dojox.analytics, the client side JavaScript need only include the proper dojo.require statement. With that dependency pulled in, several options are available to generate events. See the following examples:
Enable the ability to generate events.
dojo.require("dojox.analytics.plugins.dojo");
Generate a dojox.analytics event with arbitrary text.
console.rlog("Any quoted string goes here.");
Log something with a high precision time stamp.
dojox.analytics.addData("timestamp", [new Date().getTime(), "on-load executed"]);
Beyond selecting which events will be tracked by dojox.analytics, configuration to identify the relative or absolute URL of the analytics service is required. You might also use the following parameters:
djConfig parameter meaning and possible values Required? analyticsUrl: URL of the analytics service, either fully qualified or relative to the current resource Yes sendMethod 'script' or 'xhrPost' (default) sendMethod: 'script' is required if analytics service is on a different domain than the referring page. sendInterval Number of milliseconds to accumulate events before sending to the analytics service No, defaults to 5000 milliseconds
The default configuration sends all events to a single log file, analytics_default.log, located in the directory defined by the server java.io.tmpdir system property from the server JVM. This output log file name and path can be customized via property settings in the web.xml file. To do so, you will need to specify the full path of the file where you would like events to be logged to, in the param-value for the param-name com.ibm.ws.mobile.appsvcs.analytics.logger.LocalFileLogger. You will also need to specify a value of '1.0' to identify the syntax version to be used by the service. This is required, and is simply to allow for versioning in the future.
The following portion of web.xml file demonstrates its use:
... <init-param> <param-name>com.ibm.ws.mobile.appsvcs.analytics.logger.LocalFileLogger</param-name> <param-value>1.0,/tmp/events.log</param-value> </init-param> ...
You can also further customize the format of the log by specifying what other information is recorded as part of each log entry. This can be done via property settings in the web.xml file. To do so, simply specify one or more of the predefined keywords in the param-value for the param-name com.ibm.ws.mobile.appsvcs.analytics.logger.LocalFileLogger.LogFormat.
The following portion of web.xml file demonstrates its use:
... <init-param> <param-name>com.ibm.ws.mobile.appsvcs.analytics.logger.LocalFileLogger.LogFormat</param-name> <param-value>CLIENT_IP,CLIENT_SESSION,HTTP_REFERER</param-value> </init-param> ...
You can choose from any of the following predefined keywords:
log format entry what is logged CLIENT_SESSION logs HttpServletRequest#getRequestedSessionId(), the request's session ID specified by the client CLIENT_SESSION_FORCED logs HttpServletRequest#getSession(true).getId(), forcing the creation of a HTTP session if it doesn't exist, and logging it's session id CLIENT_IP logs HttpServletRequest#getRemoteAddr(), the Internet Protocol (IP) address of the client HTTP_REFERER logs HttpServletRequest#getHeader(), the request header
The next step in using the Analytics Service is to start the application and configure it. Starting it only requires installing and deploying the .ear file.
When a client is using dojox.analytics, the events that it generates result in HTTP requests being sent to an analytics server. The Analytics service processes these requests by exposing a Representation State Transfer (REST) interface. See the following table, which describes the available operations.
The Analytics service will handle requests targeted at http://<server>:<port>/<context-root>/<url-pattern>/analytics/logger. The context root is defined by the application.xml file if your web archive file (.war) is packaged in an enterprise archive (.ear) file. If the .war is installed by itself, the context root is defined at install time by the user. The uri mapping is defined in the WEB-INF/web.xml in the .war file.
In the provided appsvcs-analytics.ear, the application.xml file specifies a context root of "/appsvcs-analytics" and the web.xml file specifies a URL pattern of "/rest/*".
Operation Description Method URI Parameters Report a list of events GET /appsvcs-analytics/rest/analytics/logger There are two required query parameters (id and data) and one that is optional (callback). Report a list of events POST /appsvcs-analytics/rest/analytics/logger The POST request uses the same parameters, but they are not part of the URI query. Rather, they are in the body of the HTTP request. Examples are provided below.
The following table provides a description for each of the parameters.
Query Parameter Description id Unique event identifier data JSON formatted array of events callback The name of the JavaScript method that should be included in the response. See the following information about the format of the response.
Responses to the POST and GET requests are no different. However, the format of the response is slightly different if the optional callback parameter is included in the request. The following examples below outline the format.
Description Sample Request Sample Response GET with callback GET /appsvcs-analytics/rest/analytics/logger?id=1&callback=method &data=[{"plugin":"dojo","data":{"locale":"en-us"}}] method({"eventsReceived":1,"id":"1"}) GET without callback GET /appsvcs-analytics/rest/analytics/logger?id=1 &data=[{"plugin":"dojo","data":{"locale":"en-us"}}] {"eventsReceived":1,"id":"1"} POST with callback POST /appsvcs-analytics/rest/analytics/logger, HTTP body: id=1&callback=method &data=[{"plugin":"dojo","data":{"locale":"en-us"}}] method({"eventsReceived":1,"id":"1"}) POST without callback POST /appsvcs-analytics/rest/analytics/logger, HTTP body: id=1 &data=[{"plugin":"dojo","data":{"locale":"en-us"}}] {"eventsReceived":1,"id":"1"}
Each requests sent to the REST service results in an HTTP response, which includes a status code to indicate the type of success or failure. These results map well with common HTTP status codes.
Status Code Description 200 The requested operation succeeded. 400 The request included incorrect values in the parameters or request body. 405 An unsupported URI is in the REST request. 406 The client does not support the required JSON format, per the request headers. 415 The client request includes an unsupported content type. 500 An unexpected error occurred in the server.
Refer to the following version-specific installation instructions:
This section describes the procedure for installing the Analytics service on Version 6.1.0.X and later of the IBM WebSphere Application Server. It is assumed that you are familiar with application installation and administration for the application server.
Locate the Analytics service enterprise archive (EAR) file that is provided with your product installation. You can find the EAR file in your installation tree where you installed the IBM WebSphere Application Server Feature Pack for Web 2.0 and Mobile. For example, if you installed the feature pack in the following location:
Platform Location Linux and UNIX: /opt/WebSphere/AppServer z/OS mount point: <install_root> Windows: c:\WebSphere\AppServer
Then you can find the EAR file at:
Platform Location Linux and UNIX: /opt/WebSphere/AppServer/web2mobilefep_1.1/installableApps/application_services/analytics/appsvcs-analytics.ear z/OS: <install_root>/web2mobilefep_1.1/installableApps/application_services/analytics/appsvcs-analytics.ear Windows: c:\WebSphere\AppServer\web2mobilefep_1.1\installableApps\application_services\analytics\appsvcs-analytics.ear
- Log into the administrative console for the application server.
- Navigate to Applications > New Application. (Note: In WebSphere Application Server Version 6.1, select Install New Application)
- Select New Enterprise Application. (Note: In WebSphere Application Server Version 6.1, skip this step)
- Browse your file system, and select the appsvcs-graphics.ear file that you located earlier. Click Next.
- Click Next to prepare for the application installation. (Note: In WebSphere Application Server Version 6.1, skip this step)
- Click Next to accept the default installation options.
- Click Next to accept the default options for map modules to servers.
- Click Next to accept the default options for Metadata for modules. (Note: In WebSphere Application Server Versions 6.1 and 7, skip this step)
- Click Next to accept the default options for map virtual hosts for web modules.
- Review the summary of the installation options.
- Click Finish.
- Click Save to the master configuration.
- Navigate to Applications > Application Types > WebSphere Enterprise Applications. (Note: In WebSphere Application Server Version 6.1, Navigate to Applications > Enterprise Applications)
- Select the IBM WebSphere Application Server - Analytics Service, and click Start.
Point your web browser to your application server installation: http://<application server hostname>:<port>/appsvcs-analytics/
The application server host name and port number are specific to your application server installation. An application server default installation web container port is 9080. If you are running your web browser on the same workstation as your application server installation and have taken all the default values, then use the following URL: http://localhost:9080/appsvcs-analytics/.
This section describes the procedure for installing the Analytics Service into Version 2.X of the IBM WebSphere Application Server Community Edition. It is assumed that you are familiar with application installation and administration for the application server.
Locate the Analytics Service enterprise archive (EAR) file that is provided with your product installation. You can find the EAR file in your installation tree where you installed the IBM WebSphere Application Server Feature Pack for Web 2.0 and Mobile. For example, if you installed the feature pack in the following location:
Platform Location Linux and UNIX: /opt/WebSphere/AppServerCommunityEdition Windows: c:\WebSphere\AppServerCommunityEdition
Then, you can find the EAR and library files at:
Platform Location Linux and UNIX: /opt/WebSphere/AppServerCommunityEdition/web2mobilefep_1.1/AppServices/installableApps/analytics/appsvcs-analytics.ear Windows: c:\WebSphere\AppServerCommunityEdition\web2mobilefep_1.1\AppServices\installableApps\analytics\appsvcs-analytics.ear
Log into the administrative console for the application server.
- Click Applications > Deployer in the left menu. (Note: In WebSphere Application Server Community Edition Version 2.0, click Applications > Deploy New)
- In the Archive field, browse your file system and select the appsvcs-analytics.ear file that you located earlier. Leave the Plan field empty and the default options selected. Then, click Install.
The application starts automatically, and installation is complete.
Point your Web browser to your application server installation: http://<application server hostname>:<port>/appsvcs-analytics/.
The application server host name and port is specific to your application server installation. The WebSphere Application Server Community Edition server default installation Web container port is 8080. If you are running your browser on the same workstation as your application server installation and have accepted all the default values, then use the following URL: