Configuring Usage Tracking and Reporting

Contents


Running the Configuration Wizard

Upon activating CardioLog, the Configuration Wizard will be displayed. This wizard will help you configure the SharePoint Tracking Agent - a tool designed to monitor visitor behavior in SharePoint, and the SharePoint Adaptor - which provides the structure of your SharePoint portal.

Login to the CardioLog server with the CardioLog service account and verify that it has the required permissions before running the wizard.

Please review this entire section in order to determine the tracking mechanism that should be deployed. If you choose to deploy 'CardioLog Analytics' SharePoint feature, the wizard should run with SharePoint administrator privileges. 

  1. Launch CardioLog.
  2. In the Welcome dialog, select the desired UI language (including date format) and your SharePoint version, then click Next.

    wiz1.jpg

    Configuration Wizard
     
     

  3. This step can be performed in one of the following ways:

    (1) Automatically add the JavaScript tracking code to all SharePoint pages served by the WFE by deploying the CardioLog tracking code through a SharePoint solution.

    (2) Automatically add the JavaScript tracking code to all SharePoint pages served by the WFE by adding the tracking code to init.js in SharePoint 2010/13, and core.js in SharePoint 2007 (recommended for test environments only).

    (3) Manually add the JavaScript tracking code.

    Note: Please select one option only to configure the Tracking Agent.

    (1) Deploy 'CardioLog Analytics' SharePoint feature

    CardioLog provides a SharePoint solution (cardiologtrackingagentfeature.wsp)  for installing the JavaScript tracking code on all farm pages. This SharePoint solution includes a farm-scoped feature named CardioLog Analytics, which can be activated or deactivated through SharePoint’s Central Administration.
    Note: SharePoint farm administrator and local administrator roles on the SharePoint application server and WFEs are required.  

    1. In the Usage Tracking dialog, select "Yes, install and activate CardioLog Analytics SharePoint Feature" and enter the SharePoint application server machine name:

      wiz2.jpg
      Step 2 - Usage Tracking

    2. Click Next
    3. Wait while the wizard installs the cardiologtrackingagentfeature.wsp solution file, deploys the solution throughout all web front ends, and activates the CardioLog Analytics feature. If this step fails, please refer to the following article - how to install the CardioLog Analytics feature manually.

      wiz4.jpg


      To view the deployed solution in SharePoint 2013, go to Central Administration > System Settings > Manage farm solutions

      sp2013_solutions.jpg
      SharePoint 2013 - Solution Management

      In the Solution Properties, click cardiologtrackingagentfeature.wsp and verify that the solution was successfully deployed to all web front ends.

      sp2013_solution.jpg
      SharePoint 2013 - Solution Properties


      To view the deployed solution in SharePoint 2010, go to Central Administration > System Settings > Manage farm solutions

      solutions.png
      SharePoint 2010 - Solution Management


      In the Solution Properties, click cardiologtrackingagentfeature.wsp and verify that the solution was successfully deployed to all web front ends.

      soution_status.png
      SharePoint 2010 - Solution Properties


      To view the deployed solution in MOSS 2007, go to Central Administration > Operations > Solution Management

      Solution_Management-2007.png
      MOSS 2007 - Solution Management


      In the Solution Properties, click cardiologtrackingagentfeature.wsp and verify that the solution was successfully deployed to all web front ends.

      Solution_Properties-2007.png
      MOSS 2007 - Solution Properties


      Activate/Deactivate Data Collection

      Upon installation of the CardioLog Analytics feature, it is automatically activated and data is being collected.

      Warning
      : The deactivation operation will stop data collection

      To deactivate the CardioLog Analytics feature in SharePoint 2013, go to Central Administration > System Settings > Manage farm features

      sp2013_features.jpg
      SharePoint 2013 - Manage farm features


      To deactivate the CardioLog Analytics feature in SharePoint 2010, go to Central Administration > System Settings > Manage farm features


      feature_activate.png
      SharePoint 2010 - Manage farm features


      To deactivate the CardioLog Analytics feature in MOSS 2007, go to Central Administration > Operations > Manage farm features

      Manage_Farm_Features-2007.png
      MOSS 2007 - Manage farm features

      Note: The CardioLog Analytics SharePoint Feature will work only for master pages which contain the following control in the head section:
      <SharePoint:DelegateControl runat="server" ControlId="AdditionalPageHead" AllowMultipleControls="true"/>

      This control is included in the master pages for all SharePoint templates, except the MOSS 2007 Publishing Site master page. 
      Add this control to all MOSS 2007 Publishing Site master pages, right before the closing </HEAD> tag. Alternatively, you can also use a top master file which is included in all of the Publishing Sites master pages, in order to perform a single update.

     

    (2) Automatically add the JavaScript tracking code

    Notes: This step should be done for each WFE. The CardioLog service account must have write permissions to the SharePoint template directory: 
    [SharePoint 2013 Server]\%PROGRAMFILES%\Common Files\Microsoft Shared\web server extensions\15\TEMPLATE
    [SharePoint 2010 Server]\%PROGRAMFILES%\Common Files\Microsoft Shared\web server extensions\14\TEMPLATE
    [SharePoint 2007 Server]\%PROGRAMFILES%\Common Files\Microsoft Shared\web server extensions\12\TEMPLATE 

    1. In the Usage Tracking dialog, select "Yes, add the tracking code to my SharePoint INIT.JS files" and enter the SharePoint WFE server names, to allow CardioLog to automatically add the tracking code to all SharePoint pages served by the all the WFEs in your farm (the tracking code is added to init.js in SharePoint 2010 and SharePoint 2013, and core.js in SharePoint 2007).

      wiz_init.jpg

      Step 2 – Usage Tracking

      Note: If your SharePoint website runs on SSL
      , you will have to create a certificate for the CardioLog website and configure it to enable SSL. Alternatively, you can install the CardioLog Analytics SharePoint Feature
      See how to configure the Tracking Agent with SSL for more details.
       

    2. Click Next


    (3) Manually add a JavaScript tracking code

    If you wish to add the tracking code yourself - select "No, I will add the tracking code myself" and copy the JavaScript tracking code to a common page component of your choice - such as master pages, page toolbars, Web Parts, footer, etc. If you choose a common JavaScript (.js) file, verify you have removed the opening and closing <script> tags!

     

  4. Testing the tracking Agent:

    1. Open a new browser window and click Next Step.
    2. Delete your browser temporary internet files and click Next Step.
    3. Browse 3 pages on your SharePoint website and click Next Step.
    4. Click Test Event Collection.

     
     wiz6.jpg
    Step 2 – Usage Tracking 

     

  5. In the SharePoint Adaptor dialog, enter the SQL server instance name and the SharePoint configuration database name for your farm. Specify the authentication method used to connect to the database, then click Next.

    Note:
    Please confirm that the CardioLog service account has read permissions (data reader) for all SharePoint configuration and content databases.

    wiz8.jpg

    Step 3 – SharePoint Adaptor
     
     

  6. In the SharePoint Adaptor dialog, select the SharePoint website/s you wish to report on. Enter the name of one of your SharePoint WFE’s, then click Next.

    Note: Loading your SharePoint tree structure may take several minutes (depending on the number of items in the selected web sites).


    wiz9.jpg

    Step 3 – SharePoint Adaptor

     

  7. In the SharePoint Adaptor dialog, expand the web site tree and verify that it shows the desired SharePoint web application, then click Next.

    wiz11.jpg

    Step 3 – SharePoint Adaptor


  8. In the Usage Data Processing dialog, click Next.

    wiz12.jpg
    Step 4 – Usage Data Processing


  9. In the Finish dialog, click Finish. Click Show Raw Usage Data to view the usage events collected thus far. The data will be available in reports in the next hour.

    wiz13.jpg
    Step 5 – Finish 

  10. Assign roles for users.
  11. Configure email alerts for scheduled services and event collection thresholds that will be sent to the administrator.
  12. Configure the Active Directory Updates service in order to segment authenticated visitors by their user names and their groups.

Tracking Document Usage from within Office

By default, the CardioLog Tracking Agent tracks document usage for documents which are accessed through the browser. This is achieved by tracking browser clicks in document libraries (which are not displayed in Explorer view).
In order to track document access from non-browser sources - such as Windows Explorer or Office, you need to install the CardioLog HttpModule for SharePoint.
  1. In the SharePoint server, add CardioLogHttpModule.dll to the GAC (as detailed here:  https://msdn.microsoft.com/en-us/library/vstudio/dkkx7f79(v=vs.85).aspx). The dll can be found at the CardioLog installation folder:
    \CardioLog\CardioLogScheduleServices\CardioLogHttpModule.dll
  2. In the SharePoint server, for each web site, modify the SharePoint Web.config file:

    To register the module for IIS 6.0 and IIS 7.0 running in Classic Mode:
    <configuration>
      <system.web>
        <httpModules>
          <add name="CardioLogHttpModule" type="CardioLog.HttpModules.EventsModule,CardioLogHttpModule, Version=1.19.154.6, Culture=neutral, PublicKeyToken=56b51e29d93ab3fb" />

    To register the module for IIS 7.0 running in Integrated Mode:
    <configuration>
      <system.webServer>
        <modules>
          <add name="CardioLogHttpModule" type="CardioLog.HttpModules.EventsModule,CardioLogHttpModule, Version=1.19.154.6, Culture=neutral, PublicKeyToken=56b51e29d93ab3fb" />

    Add the following keys:
    <configuration>
      <appSettings>

        <add key="CardioLog.Events.DocExtensions" value=".doc*.docx*.ppt*.pptx*.pps*.ppsx*.txt*.pdf*.xlr*.xls*.xlsx*.log*.msg*.odt*.rtf*.csv*"/>
        <add key="CardioLog.Events.ExcludeUserAgents" value="Microsoft Office Existence Discovery*"/>
        <add key="CardioLog.API.EventsServiceUrl" value="http://<CardioLog server>:<port>/CardioLogAPI/Events.asmx"/>
        <add key="CardioLog.Events.LogFile" value="C:\CardioLogHttpModule.log"/>
        <add key="CardioLog.Events.LogLevel" value="None"/><!--None,Error,Message-->
        <add key="CardioLog.Events.SharePointVersion" value="2013"/>
    Optional keys:
    <!--  Support claims based authentication  -->   
    <add key="CardioLog.Events.SupportClaimsAuth" value="true"/>
    <add key="CardioLog.Events.ClaimsAuthRegex" value=""/>
    <add key="CardioLog.Events.ClaimsAuthRegexGroupMatch" value=""/>


    <!--  Ignore the event if a user already accessed the same document in the last 1000 milliseconds -->
    <add key="CardioLog.Events.CacheExpirationTimeoutInMs" value="1000"/>

    Edit the values for:
    - CardioLog.Events.SharePointVersion - the SharePoint version (2007/2010/2013)
    - CardioLog.Events.DocExtensions - a list of star separated file extensions to track
    Note: Make sure to enter all document types in the "CardioLog.Events.DocExtensions" key (".aspx", ".asp", ".php", ".htm" are included by default, no need to add them to the list).
    You can use the following CardioLog report to see all document types included in your SharePoint environment – Portal Growth > Document Types.
    - CardioLog.Events.LogFile - log file location
    - CardioLog.API.EventsServiceUrl -  modify the CardioLog server name and port

  3. Open this file for editing: [Installation directory]\CardioLogAgent\js\AgentEmbed.js
  4. In AgentEmbed.js, set element.HandleFileExtension to false:
    element.HandleFileExtension = false;

    In versions lower than 2.0.8.0, this file is located in [Installation directory]\CardioLogAgent\AgentEmbed.aspx
  5. Restart the SharePoint IIS server (iisreset).

[Installation directory] - by default, the CardioLogAgent folder is located in the CardioLog Installation folder. If the "CardioLog Analytics" SharePoint feature is installed, the CardioLogAgent folder is located on all SharePoint WFEs under the SharePoint website "_layouts" folder.

Note: In case of multiple servers in your SharePoint farm, consider using the HttpModule as a farm scoped SharePoint solution. SharePoint has a class that deals with Web.config issues and handles rollback and recovery and ensures that all sites are configured the same.

Configuring Multiple Web Applications

 In order to monitor an additional web application in your existing farm, please do the following:

  1. Add the required SQL permissions to the CardioLog service account - db_datareader for the SharePoint portal content database.
  2. In the Administration pane, click System Configuration, and then select SharePoint Tree Adaptor.
  3. Click on your SharePoint farm and select the web application/s you want to monitor.
  4. Click Save
  5. In versions lower than 2.0.8.0, add the portal root URL to the "includedWebApps" key in the <CardioLog Installation Folder>\SP20XXTree\web.config file (XX - 07 for MOSS 2007, 10 for SharePoint 2010, 13 for SharePoint 2013).
  6. Restart the CardioLog Scheduling Service. The tree structure will be refreshed the next day.
  7. If you are using the CardioLog Analytics tracking feature or if you have configured the CardioLogAgent web application on the SharePoint WFEs, open the new web application in IIS Manager and verify that the CardioLogAgent folder under the "_layouts" directory is configured as a web application (if not, right click on it and select "Convert to Application").
  8. Verify data collection from the new web application.

Configuring Multiple Farms

In order to monitor multiple SharePoint farms per adaptor, please do the following:

  1. Add the required SQL permissions to the CardioLog service account - db_datareader for the SharePoint portal content database, and read access to the SharePoint TEMPLATE folder.
  2. Configure event collection - deploy the JavaScript tracking code on all SharePoint WFEs by installing the CardioLog Analytics tracking agent feature or by inserting the code manually (to your master pages or to init.js in SharePoint 2010 and SharePoint 2013, core.js in SharePoint 2007)
  3. In the Administration pane, click System Configuration, and then select SharePoint Tree Adaptor.
  4. Click Add Farm, and then select your SharePoint version.
  5. In the SharePoint Tree Adaptor dialog, fill out the following fields:

    -      Name - this is the title of the farm folder which will be displayed in the CardioLog tree structure in the Analysis Center. Example: “SharePoint 2013”
    -      Database Server - the SharePoint database instance name.
    -      SharePoint Configuration Database Name - the SharePoint configuration database name. Example: “SharePoint_Config”
    -      Authentication - database authentication type (windows integrated or SQL authentication).
    -      SharePoint TEMPLATE Directory - this is the full path for the SharePoint 'TEMPLATE' directory. Example: "\\<sharepoint server name>\C$\Program Files\Common Files\Microsoft Shared\Web Server Extensions\XX\TEMPLATE\" (XX - 12 for MOSS 2007, 14 for SharePoint 2010, 15 for SharePoint 2013)
  6. Click Apply.
  7. Select the web application/s you want to monitor, then click Save.
  8. After the next run of Portal Tree Updates, the updated tree structure will be displayed in Analysis Center (Object Explorer).
sp_adaptor.jpg

System Configuration – SharePoint Tree Adaptor

In versions lower than 2.0.8.0, configure the tree service web.config file:

In <CardioLog Installation Folder>\SP20XXTree\web.config (XX - 07 for MOSS 2007, 10 for SharePoint 2010, 13 for SharePoint 2013), add the following keys to the <appSettings> section with the "profile_1_ " prefix (additional farms are considered additional profiles):

  • profile_1_includedWebApps - this is a star separated list of web applications (virtual servers) to include in the tree.
  • profile_1_SharePointTemplatePath - this is the full path for the SharePoint 'TEMPLATE' directory (XX - 12 for MOSS 2007, 14 for SharePoint 2010, 15 for SharePoint 2013)
  • profile_1_FarmFolderName - Optional. This is the title of the farm folder which will be displayed in the CardioLog tree structure in the Analysis Center.
  • profile_1_outputFilePath - this is the full path of the CardioLog installation folder 'Logs' directory which will store the tree structure output file (XX - 07 for MOSS 2007, 10 for SharePoint 2010, 13 for SharePoint 2013).

<appSettings>

<add key="profile_1_includedWebApps" value="http:// <sharepoint server name>:<port>*" />
<add key="profile_1_SharePointTemplatePath" value="\\<sharepoint server name>\C$\Program Files\Common Files\Microsoft Shared\Web Server Extensions\XX\TEMPLATE\" /> 

<add key="profile_1_FarmFolderName" value="SharePoint 2010" />

<add key="profile_1_outputFilePath" value="<CardioLog installation folder>\CardioLogScheduleServices\Logs\SP20XXTree_1.xml" />

</appSettings>

Add the following keys to the <connectionStrings> section:

  • profile_1_configDB - this is the connection string for the SharePoint configuration database.
  • profile_1_contentDB - this is a place holder for creating connection strings to the SharePoint content databases. Note: Leave "Initial Catalog={0};Data Source={1} " as it is.

<connectionStrings>

<add name="profile_1_configDB" connectionString="Integrated Security=SSPI;Persist Security Info=False;Initial Catalog=<sharepoint config database name>;Data Source=<database server name>" />
<add name="profile_1_contentDB" connectionString="Integrated Security=SSPI;Persist Security Info=False;Initial Catalog={0};Data Source={1}" />

</connectionStrings>

Go to Administration > CardioLog Scheduling Service > Portal Tree Updates and add the new profile to the Portal Tree Updates web services list:

http://<CardioLogServer>:<port>/SP20XXTree/default.aspx?profile=1&output=file&logFilePath=[CardioLog Installation Folder]\CardioLogScheduleServices\Logs\SP20XXTree_1.xml (XX - 07 for MOSS 2007, 10 for SharePoint 2010, 13 for SharePoint 2013)

Restart the CardioLog Scheduling Service. The tree structure will be refreshed the next day.

Note: In order to add multiple farms, use the profile_2_, profile_3_ etc... prefix.

Configuring Reporting Data Cache

To improve performance, CardioLog caches the results for each reporting query in accordance with the specific report filters used. In the Cache Configuration page, you can define the amount of time queries are cached,  and clear the entire reporting cache.

  1. In the Administration pane, click System Configuration, and then select Reporting Data.
  2. In the Reporting Data Cache Configuration box, check Enable Reporting Data Caching to enable report caching.
  3. Fill out a value for the Cache life time in days field.
  4. Click Save
  5. Click Clear Cache if you want to clear the entire reporting cache.

 report_cache.jpg

 System Configuration > Reporting Data

 

Have more questions? Submit a request

0 Comments

Article is closed for comments.
Powered by Zendesk