By default, a dimension is populated by all data values detected in the capture stream. Optionally, to normalize or otherwise restrict the source data, you may choose to record values for a dimension from values that are specified in lists.

For each dimension, you can define the scope of values to be recorded for the dimension.

• To specify the values, select an option from the Values to Record drop-down in the Add/Edit Dimension dialog.
• For events that record Count Only values, you can choose to record to the dimension the first, last, or current count of the event in the session.
• For each dimension, you can specify a maximum number of values to capture per hour, which allows you to limit the data size for the dimension.

For each dimension, you can specify one of the following to record:

Note: After you save the dimension that includes a specified list, you cannot change the source values in the list, and the Values to Record cannot be changed if a Group List type is used.
For these types, export the list to a file, delete the dimension, and create a dimension with the same properties, making changes as needed. Then, import the file, if needed, as the source for the values to record.

Whitelist + Observed Values

Record values that are on the whitelist for the dimension, as well as non-blacklisted values detected in the capture stream. A Whitelist + Observed Values configuration may be used when populating a dimension that is not dynamic or is populated by a very limited set of dynamic data. For example, you might use observed values to capture a limited set of query strings associated with a small subset of hit or event occurrences.

When dimensions are created to capture data using Whitelist + Observed Values, the volume of data can grow without limit, which result in a very large number of either individual dimension values or combinations of values with other dimensions. A high number of dimension values can also become a bottleneck in the Data Service and the Portal, which attempt to pass these values upon request. Because Whitelist + Observed Values is the easiest way for a dimension to immediately gather values without extra configuration, Whitelist + Observed Values is the default method of recording for dimensions. As a result, however, data management issues can occur for any newly created dimension.

Note: Because dimension values are recorded as text values, logging of dimension values is disabled for numeric group lists.

Sources for dimension values

The recorded values for a dimension are generated from the data sources that are listed below:

• Whitelist - For a dimension, you can specify the list of values that are accepted to populate the dimension. This list can be generated from the following mechanisms.
  • Logs - When logging for a dimension is enabled, all detected values are stored in a log file. You can select to permit individual values in the logs or all values.
  • Importing a List - You can import a set of values into your whitelist.
  • Manual Entry - You can also specify individual entries for the dimension.
  • Observed values - You may choose to include observed values in raw form in the dimension data. This population occurs when you select Whitelist + Observed Values for the values to record.
• Blacklist - A blacklist contains the list of values that are not permitted to populate the dimension. Blacklists are specified in the same manner as whitelists.

  A dimension can have both a whitelist and a blacklist.

• Group list - A group list is used to specify dimension values in which multiple detected values are normalized to a single value. For example, you might use a group list that is called States to normalize values of CA and California to California.

Processing dimension values

After a dimension value is retrieved from the data source for the dimension, leading and trailing spaces are stripped from the value, and it is converted to uppercase. A copy of the trimmed dimension string is saved as the source value.

Each source value is processed through the dimension's whitelist or group list and then the blacklist.

• If a match in a fixed whitelist is found, the display value is returned. If a display value is not found, the default dimension value is used.

  Note: There is no logging for fixed whitelist values.

• If the source value is not in a fixed whitelist, the value is submitted for the blacklist processing. If it is not in the blacklist, the value is logged for checking against permitted value limits.
• Dimension logging and limit checking are run against the trimmed dimension value.

Example: Recording dimension values

Dimension values can be recorded as soon as the following occurs:

• Dimension definition is saved.
• Dimension is associated with a report group.
• Report group is assigned to an event.
• Event is triggered.

The previous information has some implications that are best explained by example. Suppose you have an event with the following configuration:

As soon as the dimensions are associated with the report group and the report group is associated with EventA, values are recorded for DimA and DimB whenever EventA fires.

Suppose that three days later two more report groups are created and associated with EventA, so that the configuration now looks like the following:

Now, when EventA fires, dimension values are recorded for dimensions A-E, yet there is no data at all for DimC, DimD, and DimE before Day 4. When dimensions from ReportGroup2 and ReportGroup3 are added to reports, there are no values from before Day 4.

Suppose that another three days passes, and then DimC is added to ReportGroup1. The event configuration now looks like the following:

Since DimC was added to ReportGroup1, there is no data for DimC in recorded instances of EventA + ReportGroup1 combination before Day 7. While the dimension is included as part of the report group, all values displayed for ReportGroup1\DimC before Day 7 are null values.

However, if you use EventA + ReportGroup2 or EventA + ReportGroup3, there are reported values for DimC for Days 4 and onward.

This distinction can be confusing in reports using the configured dimensions.

Note: For purposes of reporting, different data sets are recorded for event + report group\dimension combinations in the Reporting database. So, the data set referenced in a report uses the specific instances of the event + report group\dimension values, instead of all data that is captured since the dimension was created. This space-saving mechanism works as designed.