To log additional data, you need to decide what kind of data you want to capture and how that data will be stored.
Determining What Data to Log
You also need to decide what kind of data about the event you want to log. In a sense, you are defining the building blocks for your metric by determining which data points to capture. Those data points will be used to generate your metric. In order to track a data point, you need to add it to the appropriate item descriptor as a property and define a column for it in the relevant database table.
There are some data that are common to most metrics, while other data is only applicable for certain ones. Here’s a list of data that you should log:
Time stamp: Capturing a time stamp identifies when a logged activity occurs. The Report Generator Service requires you to log a time stamp for your test data. You may choose to have a primary key that’s a combination of profile ID and timestamp, if this does not cause a delay in performance for your ATG instance. The data type for time stamp should be
timestampin the item descriptor and database.Dataset: Every event needs a dataset in order to map the event that generates the data to the data in the database. In rare cases, a log holds information about two datasets, each from a different event. The Participant Assigned to a Test Group event uses two datasets to track each group it defines. The data type for dataset should be
stringin the item descriptor andvarchar(40)in the database.Group ID: All tests organize users into at least two groups: one that views the site as is (control group) and one or more other groups, each of which represents a unique site experience. Creating groups allows you to derive reliable statistics you can use to judge the efficacy of the parts of your site. You are required to log a group ID. The data type for group ID should be
stringin the item descriptor andvarchar(40)in the database.Test ID: Providing a test ID is required by ATG Campaign Optimizer in order to derive meaningful statistic about test results. The data type for test ID should be
stringin the item descriptor andvarchar(40)in the database.Profile ID: One way to identify the number of times a user passes through a test is to track each user’s ID. Other benefits to gathering profile IDs is that it gives you access to the user’s profile so tests that log profile IDs can provide a richer context about the test participants. You may choose to use a profile ID as part of a primary key, if you are creating a new table for your metric. The data type for profile ID should be
stringin the item descriptor andvarchar(40)in the database.Currency code: Sites that support multiple locales need to record the currency used for monetary data. Currency code captures the ISO 4127 currency code used for any currency values recorded for an event. The data type for currency code should be
stringin the item descriptor andvarchar(40)in the database.
Keep in mind that each column holding data that’s a number needing to be tallied in a report, such as revenueOrdered, should be identified as such in the metric handler component. The metric handler component includes the currencySumProperties, doubleSumProperties, and integerSumProperties properties to identify each property used for a metric of the specified type. See About MetricHandler for more information on these properties.
Where to Store Metric Data
Will you need a new item descriptor or can you add properties to an existing one? Do you need to create a new table or can you add columns to an existing table? It depends on the metric you are working with.
When adding new metrics for existing events, you should add new properties to the existing log item descriptor and add new columns to the existing log database for that table. For example, you may currently monitor user page visits, but would like to also know the state of residence for those users. You can create a new property for the pageVisitLogData item descriptor in ABTestLogRepository that defines state as a property, information for which is stored in a new state column in the abl_page_visit database table. The resultant report might calculate the number of page visits per user organized by state: 18 for Mississippi, 806 for Texas, and so on.
For new metrics added to events that aren’t currently used by ATG Campaign Optimizer tests, you should create a new log item descriptor and database table. A custom metric could track information about users who register for a site. Information such as profile ID, group ID, test ID, and time stamp could be logged in a database table called abl_registration with columns for holding profile, group, test, and time values. This database table, like all tables that store logging data for ATG Campaign Optimizer tests, must be accessible by the runtime and reporting modules and should define an index for the test_id column. The corresponding item descriptor, called RegistrationLogData, would define the four pieces of information as properties. In such cases, you would also need to create a dataset, data collection object, queue, and mapper for your metric. See Creating Recording Devices for instructions.
Ensuring Optimal Performance
Every item descriptor defined in ABTestLogRepository.xml should use the following attribute in order to avoid performance degradation in the ReportGeneratorService:
<attribute name="defaultUncachedItemQueries" value="true"/>
