Dimensions are populated by event, hit attribute or session attribute data that is detected in the capture stream or by values that you manually specify. In the dimension definition, you can specify the data source and values for the object that is detected in the session.

You can configure whether the first or last value of the attribute or event is used. The value that you specify to populate the dimension definition depends on the configuration for the populating event or hit attribute.

• A hit attribute can acquire either the first match or all matches.
• Events can acquire the first, last, or all matches.

The value of the Populate With setting (first or last value) on the dimension only matters if the hit attribute or event returns multiple values. If the hit attribute or event returns a single value, then the dimension has only one possible value to retrieve, so the Populate With setting is irrelevant.

If the dimension is populated by an event or session attribute, you can populate it with the first or last value in the session only.

Text format for dimension values

Note: Dimension values are always stored as text data. Even if the captured value is numeric, the stored dimension value is of text type. Dimension values are case-insensitive.

To perform numeric comparisons between dimension values, you must use JavaScript™ in Advanced Mode to convert the values to numeric values and perform your comparisons.

Dimension default values

You can specify default values for the dimension. If a value detected in the capture stream does not map to a whitelist or blacklist value, the specific Default Value is inserted in the data.

The default value can be specified to be a custom value or one of the values available in the drop-down.

To specify a default value that is not listed, select Custom Value in the drop-down and insert the default value for the dimension in the textbox.

If Allow Empty Values is selected, then the [Empty] constant is applied when no value is detected otherwise the [Null] constant is applied.

Maximum number of dimension values

For data storage purposes, each dimension can be assigned a maximum number of values to be captured per hour for each Processing Server. Imposing a limit on the number of values ensures that a statistically meaningful sample of the available values is captured and reported.

For example, in a large website, a dimension that captures visited URLs may quickly exceed this value.

Note: This value indicates the total number of instances of unique values permitted per hour for each Processing Server. For example, if your environment contains three Processing Servers and this value is set to 500, then a total of 1500 unique dimension values can be captured system-wide in an hour, with no more than 500 captured by an individual Processing Server.

• It is possible to have specific values that are repeated in the hourly data set. For example, if the value shirt is appears 10 times in an hour for a dimension, it is recorded only once as a dimension value.
• By default, this limit is set to 1000. It can be set a maximum value of 50000 values per hour.
• Processed values include whitelisted values, which also count against this limit. Blacklisted values do not count.
• If the actual number of captured values exceeds this limit for a given hour, the default value for the dimension is recorded.

Each hour, the counter of dimension values resets to zero for each Processing Server.

Global fact limit

As a safeguard, Tealeaf also enforces a maximum number of facts that can be generated. For each event, this limit is tested each user-defined interval (Fact Limits - Check Interval (minutes)) for the preceding hour.

• By default, the limit for number of facts that are recorded per hour for an event is set to 500, 000.
• If this limit is exceeded, any associated scorecard or dashboard is disabled. The fact is also disabled and must be re-enabled through the Report Groups step of the Event Wizard.

Global dimension value limit

To prevent runaway growth of the number of values that are stored for dimension data, Tealeaf enforces a global limit on the number of dimensions that are retained for any individual dimension. Periodically, the Data Collector scans the values that are stored in the database for each dimension and removes the oldest values that exceed the defined number of permitted values, which are based on the timestamps when the values were recorded.

Counts for dimension values that are trimmed in this manner are moved to the [others] category.

Note: The global dimension value limit is not intended to replace effective management of dimension data. Dimensions that reach the global limit are trimmed back to the global limit. If new values are added, the trimming is repeated, which can significantly burden the system over time. Convert all high-volume dimensions to whitelists.

Dimension constants

Depending on the number of values that are captured for a dimension and the data type, one of the following constants might be inserted for the dimension value in place of the captured value.

Note: All dimension constants are searchable except for [Null].

[Null]

This constant is inserted as the dimension value if a null value is detected for the dimension. A null value occurs if the criteria for detecting the dimension value cannot be satisfied.

The null value constant is not indexed for search. You cannot retrieve results when searching for this value. Where it appears in reports, drill-down to the underlying data is disabled.

Note: Advanced users might be able to record a separate value for null values for dimension constants. Using an ELSE clause in the definition that records the dimension value, you can store a specific value (for example, tlnull), which is then available for indexing and search. You can also drill down on these values to search for underlying sessions where they appear. However, non-default "null" values should be used carefully, as they can significantly increase the size of the indexes and reporting data for sparsely populated dimensions.

[Empty]

This constant is inserted if the dimension value is empty. For example, if a dimension is created to detect the value of the address field, the [Empty] constant is inserted if the field is found yet it contains no value.

[Others]

If a whitelist is used to define the values that are accepted for use in the dimension, the [Others] constant is inserted when any value that is not on the whitelist is detected for the dimension.

[Limit]

Dimensions can be configured to accept a defined number of values per hour. If the number of values that are captured within an hour exceeds this value, the [Limit] constant is inserted as the dimension value.