13 Managing the Analytics Service

This chapter describes how to configure and manage the Analytics service for WebCenter Spaces and for WebCenter Portal applications. The Analytics service enables you to display usage and performance metrics for WebCenter applications.

Always use Fusion Middleware Control or the WLST command-line tool to review and configure back-end services for WebCenter applications. Any changes that you make to WebCenter applications, post deployment, are stored in MDS metadata store as customizations. See Section 1.3.5, "WebCenter Configuration Considerations." Any changes that you make to Analytics Collector configuration are stored in the Analytics database.

Note:

Changes that you make to Analytics service configuration, through Fusion Middleware Control or using WLST, is not dynamic so you must restart the managed server on which the Analytics Collector or the WebCenter application is deployed for your changes to take effect. See Section 8.2, "Starting and Stopping Managed Servers for WebCenter Application Deployments."

This chapter includes the following sections:

Audience

The content of this chapter is intended for Fusion Middleware administrators who are responsible for setting up Oracle WebCenter Analytics, and configuring Analytics Collector details for WebCenter Spaces or WebCenter Portal applications.

13.1 What You Should Know About Oracle WebCenter Analytics

Analytics allows WebCenter administrators and business users to track and analyze portal usage. Analytics provides the following basic functionality:

  • Usage Tracking Metrics: Analytics collects and reports metrics for common portal functions, including community, page, portlet, and document visits.

  • Behavior Tracking: Users can analyze portal metrics to determine usage patterns, such as portal visit duration and usage over time.

  • User Profile Correlation: Users can correlate metric information with user profile information. Usage tracking reports can be viewed and filtered by user profile data such as country, company, or state. For more details, see "Query Options" in the Oracle Fusion Middleware User's Guide for Oracle WebCenter.

An overview of WebCenter Analytics components and ready-to-use task flow flows are described in the following sections:

13.1.1 WebCenter Analytics Components

Figure 13-1 illustrates Oracle WebCenter Analytics components:

  • WC_Spaces - The Managed Server in which WebCenter Spaces is deployed. The managed server name is different for other WebCenter Portal application deployments.

    (Other WebCenter Portal applications are deployed on different Managed Servers.)

  • WC_Utilities - The Managed Server in which the Analytics Collector is deployed.

  • Event Data - WebCenter analytics tracks and collects a defined set of events. A comprehensive set of the most common events are provided out-of-the-box.

  • Open Usage API - The OpenUsage API sends metrics to the Analytics Collector using UDP (User Datagram Protocol).

  • Analytics Collector - The Analytics Collector component gathers event data.

    Analytics Collectors can be clustered to provide increased scalability and reliability.

  • Analytics Database - The Analytics database (ACTIVITIES) stores metrics gathered from portal and non-portal events.

  • Analytics Task Flows - WebCenter provides a series of analytics task flows to report metrics for common portal functions.

  • MDS - The Oracle Metadata Services (MDS) repository that stores task flow customizations.

Figure 13-1 Oracle WebCenter Analytics Components

Analytics Components

13.1.2 WebCenter Analytics Task Flows

Table 13-1 lists the Analytics task flows available with Oracle WebCenter. For detailed information about these task flows and how to use them in WebCenter applications, see "Understanding Analytics Task Flows in WebCenter Spaces" in Oracle Fusion Middleware User's Guide for Oracle WebCenter.

Table 13-1 WebCenter Analytics Task Flows

WebCenter Analytics Task Flows Description

WebCenter Traffic

A summarized view for common events within the portal.

Page Traffic

Displays the number of page visits and the number of unique users that visited any page within the portal.

Login Metrics

Reports portal logins.

Portlet Traffic

Displays usage data for a portlet.

Portlet Response Time

Displays performance data for a portlet.

Portlet Instance Traffic

Displays usage data for a portlet instance.

When the same portlet displays on several different pages, each placement is considered as a portlet instance.

Portlet Instance Response Time

Displays performance data for a portlet instance.

Search Metrics

Tracks portal searches.

Document Metrics

Tracks document views.

Wiki Metrics

Tracks most popular/least popular wikis.

Blog Metrics

Tracks most popular/least popular blogs.

Discussion Metrics

Tracks most popular/least popular discussions.

Space Traffic*

(WebCenter Spaces only) Displays usage data for a Space.

Space Response Time*

(WebCenter Spaces only) Displays page performance data for a Space.

* Task flows specific to WebCenter Spaces. These task flows are not available to WebCenter Portal applications that you create using JDeveloper.

13.2 Configuration Roadmap for the Analytics Service

The flow chart depicted in Figure 13-2 and Table 13-2 in this section provide an overview of the prerequisites and tasks required to get the Analytics service working in WebCenter Spaces.

Figure 13-2 Configuring the Analytics Service for WebCenter Spaces

Configuring the Analytics Service for WebCenter Spaces Install WebCenter Spaces and the back-end components for the Analytics service Configure the Analytics Collector Use the System MBean Browser Use WLST Configure a connection between WebCenter Spaces and the Analytics Collector Use Fusion Middleware Control Use WLST Log in to WebCenter Spaces with administrator privileges Open the main Analytics business role page to see live data

Table 13-2 Configuring the Analytics Service for WebCenter Spaces

Actor Task Sub-task

Administrator

1. Install WebCenter Spaces and the back-end components for the Analytics service

  

Administrator

2. (Optional) Configure the Analytics Collector using either of the following tools:

  

Administrator

3. Configure a connection between WebCenter Spaces and the Analytics Collector using either of the following tools:

  

WebCenter Spaces Administrator

4. Test that analytics data is available in WebCenter Spaces

4.a Log in to WebCenter Spaces with administrator privileges

4.b Open the main Analytics business role page to see live data: http://host:port/webcenter/spaces/page/Analytics

13.3 Analytics Prerequisites

This section includes the following subsections:

13.3.1 Analytics - Installation

The Analytics Collector is an optional installation option for Oracle WebCenter. To install this product, select Oracle WebCenter Analytics Collector in the Fusion Middleware Configuration Wizard. For detailed installation instructions, see Oracle Fusion Middleware Installation Guide for Oracle WebCenter.

The Analytics schema (ACTIVITIES) and the WebCenter schema can be installed on the same database or on separate databases.

13.3.2 Analytics - Configuration

The Analytics Collector is configured to receive events out-of-the-box, using installation defaults. If the default values are not suitable for your installation or you have a cluster, you may configure different values using WLST or MBeans Browser. For more details, Section 13.4, "Configuring Analytics Collector Settings".

Out-of-the-box, WebCenter Spaces is not configured to send events to the Analytics Collector. If you want to collect usage and performance metrics for WebCenter Spaces (or any WebCenter Portal application) you must register the Analytics Collector and enable event collection. For more details, Section 13.5, "Registering an Analytics Collector for Your Application". Once connected, analytics data is collected and displays in your application (through analytics task flows) without further configuration.

13.3.3 Analytics - Security Considerations

In WebCenter Spaces, Resource Catalogs only display Analytics task flows to users with appropriate permissions:

  • Administrators - Users with the Administrator role have access to all Analytics task flows

  • Moderators - Within a Space, members with the Moderator role have access to Analytics task flows that display usage data for that Space only

Analytics usage data is valuable for portal analysis but might be regarded as private or sensitive to portal users. To protect security and privacy interests associated with usage metrics WebCenter Spaces administrators and individual Space moderators must manage page security such that only appropriate, specified users have access to pages that expose analytics data. See also, "Securing Pages and Components" in Oracle Fusion Middleware User's Guide for Oracle WebCenter.

Similarly, developers building WebCenter Portal applications must set up a suitable security model for exposing Analytics task flows and data. For details, see "Setting up Security for Analytics Task Flows and Usage Data" in Oracle Fusion Middleware Developer's Guide for Oracle WebCenter.

13.3.4 Analytics - Limitations

Analytics task flows do not display custom event information.

13.4 Configuring Analytics Collector Settings

During installation, the Analytics Collector is configured to receive events using the following default values:

  • Collector Host Name - localhost

  • Default Port - 31314

  • Maximum Port Number - 31314

  • Broadcast Type - Multicast

  • Clustering - Disabled

    • Cluster Name - null

    • Cluster Broadcast Frequency - 10 seconds

If these default values are not suitable for your installation or you have a cluster, you can configure suitable values using WLST or the MBeans Browser in Fusion Middleware Control:

These Analytics Collector configuration settings are stored in the Analytics database (ACTIVITIES).

13.4.1 Setting Analytics Collector Properties Using WLST

Use the WLST command setAnalyticsCollectorConfig to set event collection properties for the Analytics Collector. For command syntax and examples, see the section, "setAnalyticsCollectorConfig" in the Oracle Fusion Middleware WebLogic Scripting Tool Command Reference.

For information on how to run WLST commands, see Section 1.13.3.1, "Running Oracle WebLogic Scripting Tool (WLST) Commands."

Note:

To start using the property values you must restart the managed server on which the Analytics Collector application is deployed (WC_Utilities). For more information, see the section, "Starting and Stopping WebLogic Managed Servers Using the Command Line" in the Oracle Fusion Middleware Administrator's Guide.

13.4.2 Setting Analytics Collector Properties Using Fusion Middleware Control

Use the Systems MBeans Browser in Fusion Middleware Control to set event collection properties for the Analytics Collector:

To configure the Analytics Collector (deployed on the WC_Utilities managed server):

  1. Log in to Fusion Middleware Control and navigate to the home page for WebCenter Spaces or WebCenter Portal application. For more information, see:

  2. Open the System MBean Browser:

    • For WebCenter Spaces - From the WebCenter menu, choose System MBean Browser.

    • For WebCenter Portal applications - From the Application Deployment menu, choose System MBean Browser.

  3. Navigate to: Application Defined MBeans >oracle.webcenter.analytics >Server: WC_Utilities >Application: analytics-collector >CollectorConfiguration >Configuration

    Alternatively, search for CollectorConfiguration or filter the System MBean Browser tree using the MBean pattern: oracle.webcenter.analytics:*

    Figure 13-3 System MBeans Browser - Analytics Collector Properties

    Analytics Collector - MBeans Browser

  4. Modify configuration properties for the Analytics Collector. For details, see Table 13-3.

    Table 13-3 Analytics Collector - Configuration Properties

    Field Description

    BroadcastType

    Specify the network channel on which the Analytics Collector broadcasts a 'heartbeat' to advertise its location to event producers. Valid values are Broadcast and Multicast:

    Broadcast - use the standard network broadcast channel.

    Multicast - use a special fixed multicast address.

    CollectorHostName

    Enter the name of the host on which the Analytics Collector is running.

    The default setting is localhost.

    CollectorDefaultPort

    Enter the default port number on which the Analytics Collector listens. The default value is 31314.

    CollectorMaximumPort

    Enter the highest port number that an Analytics Collector can use when allocating a listener.

    This property is mostly used in a clustered environment where multiple collectors run in the same box. Each collector listens for incoming UDP messages on a free port within a given port range. The range is from the default port number to the maxPort number.

    ClusterEnabled

    Specify whether the Analytics Collector is deployed in a cluster. Valid values are true and false. If set to true, clusterName must also be defined.

    ClusterName

    Enter the name of the Analytics Collector cluster. This property is only required when clusterEnabled=1.

    ClusterBroadcastFrequency

    Specify that the Analytics Collector broadcasts listening information every 'n' seconds. The default frequency is 10 seconds.

    The Analytics Collector periodically broadcasts a 'heartbeat' to advertise its location (CollectorHostname). In a clustered environment, WebCenter applications use the heartbeat to determine which Analytics Collectors are available.

  5. To start using the new settings you must restart the managed server on which the Analytics Collector application is deployed (WC_Utilities). For more information, see Section 8.2, "Starting and Stopping Managed Servers for WebCenter Application Deployments."

13.5 Registering an Analytics Collector for Your Application

Events raised in WebCenter applications using OpenUsage APIs can be sent to an Analytics Collector for use by the Analytics service, Recommendations service, and the Activity Graph Engine. If your WebCenter application intends to use any of the features or task flows provided by these services you must connect the application to an Analytics Collector.

While you can register multiple Analytics Collector connections for a WebCenter application, only one Analytics Collector is used - the default (or active) connection.

To start using a new configuration you must restart the managed server on which the WebCenter application is deployed.

This section includes the following subsections:

13.5.1 Registering an Analytics Collector Using Fusion Middleware Control

To register an Analytics Collector for a WebCenter application:

  1. Log in to Fusion Middleware Control and navigate to the home page for WebCenter Spaces or the WebCenter Portal application. For more information, see:

  2. Open the Service Configuration page:

    • For WebCenter Spaces - From the WebCenter menu, choose Settings > Service Configuration.

    • For WebCenter Portal applications - From the Application Deployment menu, choose WebCenter > Service Configuration.

  3. From the list of services on the WebCenter Service Configuration page, select Analytics and Activity Graph.

  4. To connect to an Analytics Collector, click Add (Figure 13-4).

    Figure 13-4 Configuring Analytics Collector Connections

    Configuring a Content Repository

  5. Enter a unique name for this connection.

    The name must be unique (across all connection types) within the WebCenter application.

  6. Select Active Connection to use this connection for Analytics and Activity Graph services.

    While you can register multiple Analytics Collector connections for a WebCenter application, only one connection is used—the default (or active) connection.

  7. Select Enable WebCenter Event Collection to send analytics events raised using OpenUsage APIs to the Analytics Collector.

    Deselect this option if you do not want to collect analytics data.

  8. Enter connection details for the Analytics Collector. For details, see Table 13-4.

    Table 13-4 Analytics Collector Connection - Connection Details

    Field Description

    Messaging Mode

    Specify whether to send events to a clustered Analytics Collector in multicast mode or a single Analytics Collector using unicast communication. Valid values are Unicast and Multicast.

    The default setting is Unicast.

    Collector Host Name

    If the messaging mode is set to Unicast, enter the host name where the Analytics Collector is running.

    The default setting is localhost.

    Collector Port

    Enter the port on which the Analytics Collector listens for events. The default value is 31314.

    Cluster Name

    If the messaging mode is set to Multicast, enter the name of the cluster where a clustered Analytics Collector is running.

    Timeout (Seconds)

    If the messaging mode is set to Multicast, enter the length of time (in seconds) to wait for a response from the Analytics Collector.

    The default value is 30 seconds.

  9. Click OK to save.

  10. To start using the new (active) connection you must restart the managed server on which the WebCenter application is deployed. For more information, see Section 8.2, "Starting and Stopping Managed Servers for WebCenter Application Deployments."

13.5.2 Registering an Analytics Collector Using WLST

Use the WLST command createAnalyticsCollectorConnection to create an Analytics Collector connection for a WebCenter application. To update an existing connection, use setAnalyticsCollectorConnection. For command syntax and examples, see the section, "createAnalyticsCollectorConnection" and "setAnalyticsCollectorConnection" in the Oracle Fusion Middleware WebLogic Scripting Tool Command Reference.

For information on how to run WLST commands, see Section 1.13.3.1, "Running Oracle WebLogic Scripting Tool (WLST) Commands."

Note:

To start using the new connection, ensure that isEnabled=1 and default=1, and then restart the managed server on which the WebCenter application is deployed. See, "Starting and Stopping WebLogic Managed Servers Using the Command Line" in the Oracle Fusion Middleware Administrator's Guide.

13.5.3 Disabling WebCenter Event Collection

If you do not want to collect events raised using OpenUsage APIs, you can stop event transmission temporarily or permanently.

This section includes the following subsections:

13.5.3.1 Disabling WebCenter Event Collection Using Fusion Middleware Control

To disable event collection for a WebCenter application:

  1. Log in to Fusion Middleware Control and navigate to the home page for WebCenter Spaces or the WebCenter Portal application. For more information, see:

  2. Open the Service Configuration page:

    • For WebCenter Spaces - From the WebCenter menu, choose Settings > Service Configuration.

    • For WebCenter Portal applications - From the Application Deployment menu, choose WebCenter > Service Configuration.

  3. From the list of services on the WebCenter Service Configuration page, select Analytics and Activity Graph.

  4. Select the connection in the table, and then click Edit.

  5. Deselect Enable WebCenter Event Collection (Figure 13-5).

    Figure 13-5 Disabling Analytics Event Collection

    Disabling Analytics Collection

  6. To effect this change you must restart the managed server on which the WebCenter application is deployed. For more information, see Section 8.2, "Starting and Stopping Managed Servers for WebCenter Application Deployments."

13.5.3.2 Disabling WebCenter Event Collection Using WLST

To disable event collection using WLST, run the setAnalyticsCollectorConnection command with the isEnabled argument set to 0 (false). For command syntax and examples, see the section, "setAnalyticsCollectorConnection" in the Oracle Fusion Middleware WebLogic Scripting Tool Command Reference.

For information on how to run WLST commands, see Section 1.13.3.1, "Running Oracle WebLogic Scripting Tool (WLST) Commands."

13.6 Validating Analytic Event Collection

You can check whether events reach the Analytics Collector by checking the trace log at:

<base_domain_name>/servers/WC_Utilities/logs/analytics-collector/collector.trc

Event messages are similar to the following:

[2010-09-16T07:13:56.906-07:00] [WC_Utilities] [TRACE] []  [SRC_METHOD: OnMessageReceived] Event = [[EVENT_TYPE: {http://www.myorg.com/videoapp}VIDEOVIEWSVERSION: 3.0.XXXXAS_DIMENSION_USER.USERID: testuser01VIDEO.RESOURCEID: video8736VIDEO.TITLE: Project Kick OffVIDEO.LOOP: falseQUALITY: 720PROPERTY_VERSION: 3.0.XXXX

13.7 Viewing the Current WebCenter Analytic Event List

Use the Systems MBeans Browser in Fusion Middleware Control to see which events that an Analytics Collector is configured to collect.

To display the current list of analytics events:

  1. Log in to Fusion Middleware Control and navigate to the home page for WebCenter Spaces or WebCenter Portal application. For more information, see:

  2. Open the System MBean Browser:

    • For WebCenter Spaces - From the WebCenter menu, choose System MBean Browser.

    • For WebCenter Portal applications - From the Application Deployment menu, choose System MBean Browser.

  3. Navigate to: Application Defined MBeans> oracle.webcenter.analytics Server: WC_Utilities> Application: analytics-collector> CollectorServices> Services

    Alternatively, search for CollectorServices or filter the System MBean Browser tree using the MBean pattern: oracle.webcenter.analytics:*

  4. Select the Operations tab.

    Figure 13-6 System MBeans Browser - Register Analytics Events

    Analytics Collector - MBeans Browser

  5. Click listRegisteredEventTypes.

  6. Click Invoke.

Alternatively, use the WLST command listAnalyticsEventTypes. For command syntax and examples, see the section, "listAnalyticsEventTypes" in the Oracle Fusion Middleware WebLogic Scripting Tool Command Reference.

13.8 Purging Analytics Data

For more information, see "Purging Oracle WebCenter Analytics Data" in the Oracle Fusion Middleware Administrator's Guide.

13.9 Partitioning Analytics Data

For more information, see "Partitioning Oracle WebCenter Analytics Data" in the Oracle Fusion Middleware Administrator's Guide.

13.10 Troubleshooting Issues with Analytics

If users cannot see analytics in their WebCenter application, verify the following:

  • Check that the Analytics Collector configuration is correct and in particular that both Enable WebCenter Event Collection and Active Connection are both set (Figure 13-7). See Registering an Analytics Collector for Your Application.

    Figure 13-7 Enabling the Connection and Analytics Collection

    Enabling the Connection and Analytics Collection

    If you make changes to the connection you must restart the managed server on which the WebCenter application is deployed. For more information, see Section 8.2, "Starting and Stopping Managed Servers for WebCenter Application Deployments."

  • If the WebCenter application was recently upgraded, verify that the domain startup script does not contain legacy Analytics Collector settings as these values override any connection details that you specify through Fusion MIddleware Control or using WLST.

    1. Shutdown the managed server on which WebCenter application is deployed.

    2. Edit the domain startup script setDomainEnv located at:

      UNIX: DOMAIN_HOME/bin/setDomainEnv.sh

      Windows: DOMAIN_HOME\bin\setDomainEnv.cmd

    3. Remove Analytics Collector settings.

    4. Restart the managed server.