Custom Dimensions

Custom dimensions and their associated populators are documented in the following topics:

• Dimensions and Populators
• Custom Dimensions Page
• Custom Dimension Dialogs
• Populator Admin Dialogs
• Populator Fields
• Add or Edit Dimensions
• Add or Edit Populators

Custom dimensions provide a mechanism by which Kentik Detect customers can add a number of custom columns to their main tables in the Kentik Data Engine (see KDE Tables). Like Kentik-provided dimensions, custom dimensions may be chosen as the group-by dimension for a query (see Query Dimension Selectors) or as a filter in a filter group (see Filter Groups Interface).

When a custom dimension is created the user assigns a set of “populators” to that dimension. As each flow record is ingested into a main table, those populators are used, like tags (see About Flow Tags), to evaluate the flow for a match with a specified value. Tags and populators are distinct, however, in what happens when a match is found:

• With a tag, a match on a given row of incoming flow data results in the tag name being placed in either or both of two fields in that table row: the src_flow_tags column or dst_flow_tags column.
• With a populator, a match on a given row of incoming flow data results in the value property defined in the populator itself being placed in that row’s field for the custom column that corresponds to the custom dimension to which the populator was assigned.

Note: Unlike a tag, a populator is required to specify the direction of flow on which to match, which may be source, destination, or either.

The following table below shows the maximum number dimensions and populators included with your subscription to a given edition of Kentik Detect. The stated populator limits are customer-wide totals across all custom dimensions; there is no additional per-dimension limit.

Notes:
- Additional custom dimensions and populators beyond those included with a given edition are available for purchase; for further information, contact support@kentik.com.
- While up to 10,000 populators may be assigned to a given custom dimension, the field corresponding to that dimension in each row of the main table can store the value property of only a single matching populator.

Custom dimensions and their associated “populators” may be managed (created, edited, and removed) in the portal (see Adding a Custom Dimension) or via one of the following Kentik V5 APIs (see About the V5 APIs):

• To manage individual custom dimensions and/or populators: Custom Dimension API.
• To manage the populators of an existing custom dimension by batch: Batch API.

The Custom Dimensions page lists all of your organization’s custom dimensions. To view the Custom Dimensions page, choose Admin from the main Kentik Detect navbar, then Custom Dimensions from the sidebar at left. The Custom Dimensions page is documented in the following topics:

• Custom Dimensions Page UI
• Custom Dimension List

The Custom Dimensions page has the following main UI elements:

• Filter field: Enter text to filter the Custom Dimension List. The Dimension Name, Type, Display Name, and ID columns of the list are searched for a match on the string entered in this field.
• Add Custom Dimension button: Takes you to the Add Custom Dimension dialog (see Adding a Custom Dimension). This button is disabled when your organization has reached the maximum number of dimensions.
• Custom Dimension List: A table listing your organization’s currently defined custom dimensions (see Custom Dimension List).

The Custom Dimension List is a table that lists all previously saved custom dimensions. The table provides the following information and actions for each custom dimension:

• Dimension Name: The name of the custom dimension as specified when it was created. Dimension names must begin with the prefix “c_” and only contain alphanumeric characters and underscores (no spaces).
  Note: Clicking the name will take you to an Edit Custom Dimension page where you can review and edit settings for the custom dimension.
• Type: The custom dimension type, which can be either string or uint32 (an unsigned 32-bit integer).
• Display Name: The display name for the custom dimension as specified when it was created. Unlike the Dimension Name, the Display Name may contain spaces.
• Populators: The number of populators contained in the custom dimension.
• ID: The system-generated unique ID assigned when the custom dimension was created.
• Delete (icon): Opens a confirming dialog that allows you to delete the custom dimension.

Click on a column heading to sort the list (ascending or descending).

Note: To see additional information about a given custom dimension, click anywhere in the row for that custom dimension, which opens a Edit Custom Dimension dialog in which you can review and (in some cases) edit settings (see Editing a Custom Dimension).

Adding or editing a custom dimension via the Kentik portal involves specifying information in the fields of the custom dimension admin dialogs, which are covered in the following topics.

• About Dimension Admin Dialogs
• Dimension Dialogs UI
• Dimension General Tab
• Dimension Populators Tab
• Populator List

Note:
- Custom dimension admin dialogs are visible only to users whose level is Administrator.
- Custom dimensions can also be added and edited with the Custom Dimension API.

The Kentik portal uses admin dialogs to collect and display information about custom dimensions and populators. The required information is entered into the fields of the following dialogs:

• Custom dimension dialogs:
  - Add Custom Dimension when registering a new dimension with Kentik.
  - Edit Custom Dimension when editing an already registered dimension.
• Populator dialogs:
  - Add Populator when adding a populator to an existing dimension.
  - Edit Populator when editing an existing populator.

Note: For UI details on the populator dialogs, see Populator Admin Dialogs.

The custom dimension dialogs share the following common UI elements:

• Close button: Click the X in the upper right corner to close the dialog. All elements will be restored to their values at the time the dialog was opened.
• Tab selector (Add Custom Dimension dialog only): Select which tab is displayed:
  - General tab (see Dimension General Tab): Contains fields for the properties of a custom dimension.
  - Populators tab (see Dimension Populators Tab): Contains a list of populators and enables the addition of new populators.
  Note: The Populators tab is shown only after specifying the required settings on the General tab and clicking the Add Custom Dimension button, at which point the dialog changes from Add to Edit.
• Remove button (Edit Custom Dimension dialog only): Remove the dimension from your organization’s collection of Kentik-registered dimensions. This button is only present if the dimension being edited was manually added.
• Cancel button: Cancel the add dimension or edit dimension operation and exit the dialog. All elements will be restored to their values at the time the dialog was opened.
• Add Dimension button (Add Custom Dimension dialog only): Save settings for the new dimension and exit the dialog.
• Save button (Edit Custom Dimension dialog only): Save changes to dimension settings and exit the dialog.

In addition to the UI elements described in Dimension Dialogs UI, the General tab of the custom dimension dialogs contains the set of fields described in the following table.

In addition to the UI elements described in Dimension Dialogs UI, the Populators tab of the Edit Custom Dimension dialog contains the following elements:

• Filter field: Enter text to filter the Populator List. The Value, Direction, and ID columns of the list are searched for a match on the string entered in this field.
• Add Populator button: Opens the Add Populator dialog (see Populator Admin Dialogs).
• Populator List: See Populator List.

The Populator List is a table on the Populators tab of the Edit Custom Dimension dialog that lists all of the populators defined for that custom dimension. The table provides the following information and actions for each populator:

• Value: The value placed in the custom column when there’s a match with the ANDed populator parameters (see Populator Field Definitions).
  Note: Clicking the Value Field will take you to the Edit Populator page where you can review and edit settings for the populator.
• Direction: The direction (source, destination, or either) of the flow fields within which the populator will look for a match.
• ID: The system-generated unique ID assigned when the populator was created.
• Remove: Opens a confirming dialog that allows you to delete the populator.
  Note: When a populator for a custom dimension is deleted, the KDE main table rows that were previously matched by that populator will no longer be filterable by the populator’s value.

Note: To see additional information about a given populator, click anywhere in the row for that populator, which opens a Edit Populator dialog in which you can review and edit settings (see Editing a Populator).

Adding or editing a populator to a custom dimension via the Kentik portal involves specifying information in the fields of the custom dimension admin dialogs, which are covered in the following topics.

• About Populator Admin Dialogs
• Populator Dialogs UI

Note:
- Populator admin dialogs are visible only to users whose level is Administrator.
- Populators can also be added and edited with the Custom Dimension API.

The Kentik portal uses admin dialogs to collect and display information about populators. The required information is entered into the fields of the following dialogs, which are accessed from the Edit Custom Dimension dialog:

• Add Populator when adding a new populator to a custom dimension.
• Edit Populator when editing an existing populator.

The Add Populator and Edit Populator dialogs share the same layout and the following common UI elements:

• Close button: Click the X in the upper right corner to close the dialog. All elements will be restored to their values at the time the dialog was opened.
• Tab selector: Selects which tab of the dialog is displayed. Each tab contains fields related to a category of populators (see Populator Field Definitions).
• Remove button (Edit Populator dialog only): Remove the populator from this custom dimension.
• Cancel button: Cancel the add populator or edit populator operation and exit the dialog. All elements will be restored to their values at the time the dialog was opened.
• Add Populator button (Add Populator dialog only): Save settings for the new populator and exit the dialog.
• Save button (Edit Populator dialog only): Save changes to populator settings and exit the dialog.

Populators are defined with a set of fields on the tabs of the Populator Dialogs. The following topics cover working with those fields:

• Populator Field Definitions
• Populator Field Validation
• Specifying BGP Populator Fields

The populators for a given custom dimension are defined with the fields on the tabs of the Add Populator and Edit Populator dialogs, which are described in the following topics. The validation columns in each table below indicate whether or not the following validations will be applied to a given populator field:

• Comma: Comma-delimited list
• Database: Database patterns (e.g. % and _)
• Regex: Regex

Note: For additional information on validation of populator field values, see Populator Field Validation.

The following general considerations apply to the validation of values in the populator fields described in Populator Field Definitions:

• Some fields support the entry of multiple values as a comma-delimited list (see tables above).
• Commas are supported only as list delimiters (not in actual values or regex).
• Some fields support the use of database patterns (see tables above).
• In fields where regex is supported (see tables above), a period (“.”) may be used in place of a comma.
• The BGP AS Path and BGP Community fields use PostgreSQL POSIX Extended Regular Expressions. For additional information, see Specifying BGP Populator Fields.
• All other fields that support regex use PostgreSQL Advanced Regular Expressions.

Note: Documentation for PostgreSQL regex and database patterns can be found at PostgreSQL documentation:
- Database patterns are documented under “LIKE.”
- Regular expressions are documented under “POSIX Regular Expressions.”

Matches on the BGP-related populator fields (see the BGP Matching section of the table in Populator Field Definitions) are made on substrings. For ASN and Next Hop ASN, the string(s) to match are specified in a simple comma-delimited list. For both the BGP AS Path and BGP Community fields the specified values are also evaluated using a subset of standard regex (see table below):

• BGP AS path: Entering “10” in the as-path field will match any path that includes “10”, “100”, “010”, etc. Using regex, a value of “_10_” will match only paths that include ASN 10, including “10 “, “ 10”, and “ 10 “. Also allowed are tags where as-path is specified as, for example, “_10 100_”.
• BGP community: Matches on communities are similar to matches on AS paths except that they also support the use of regex periods. This allows you to specify, for example, “2000:1....” to find any flow with community 2000:1xxxx in it.

The following table shows the regex special characters that are supported when specifying the BGP AS Path and BGP Community:

Note: For BGP community and AS path, any spaces at the beginning or end of the input field and also before and after each comma will be removed.

Custom dimensions are added and edited via the Custom Dimensions page. The add/edit process is documented in the following topics:

• Adding a Custom Dimension
• Editing a Custom Dimension

Note: Custom Dimensions can also be added and edited with the Custom Dimension API.

To add a custom dimension:

1. Choose Admin from the Kentik navbar, then Custom Dimensions from the sidebar at left.
2. Click the Add Custom Dimension button at the upper right, which opens the Add Custom Dimension dialog.
   Note: If your organization already has ten custom dimensions, the Add Custom Dimension button will be grayed-out, and you will not be able to add any custom dimensions without first deleting one or more existing custom dimensions.
3. Enter the Dimension Name, Type, and Display Name for the new custom dimension.
4. To save the new custom dimension, click the Add Custom Dimension button. The dialog will become a Edit Custom Dimension dialog, which will be open to the Populators tab.
5. Do one of the following:
   - Add one or more populators to the custom dimension (see Add or Edit Populators).
   - Save the new custom dimension with no populators by clicking the Save button. This allows you to create views, dashboards, and alerts around a dimension before you have defined populators for that dimension. Used as a group-by dimension or filter, a custom dimension without populators will function essentially the same as the standard dimension FULL:Total (all traffic).

To edit a custom dimension:

1. Choose Admin from the Kentik navbar, then Custom Dimensions from the sidebar at left.
2. In the Custom Dimension List, click in the row of the custom dimension that you want to edit. The Edit Custom Dimension dialog will open.
3. Edit the custom dimension:
   - To change the name you see for the custom dimension in the Kentik Detect portal, enter a new name in the Display Name field on the General tab.
   - To add a populator to the custom dimension, see Adding a Populator.
   - To edit an existing populator, see Editing a Populator.
   - To delete a populator from the custom dimension, in the Populator List, click the Delete button for the populator you want to delete.
   Note: When a populator for a custom dimension is deleted, the KDE main table rows that were previously matched by that populator will no longer be filterable by the populator’s value.
4. To save changes to the custom dimension, click the Save button.

The populators of an existing custom dimension can be added to or edited on the Edit Custom Dimension page as described in the following topics:

• Adding a Populator
• Editing a Populator

Note: Populators can also be added and edited with either the Custom Dimension API or the Batch API.

Populators are added to a custom dimension from within the Edit Custom Dimension dialog (see Editing a Custom Dimension).

To add a populator to a custom dimension:

1. Go to the Populators tab of the dialog.
2. Click the Add Populator button at the upper right of the Populator List, which opens the Add Populator dialog.
3. Specify values for the populator’s settings (see Populator Field Definitions).
4. Click the Add Populator button to add the populator to the custom dimension and return to the Edit Custom Dimension dialog. The added populator will now appear in the Populator List.
5. Click the Save button to save the changes to the custom dimension.

Note: If you add two or more populators whose Dimension value (see Populator Field Definitions) is the same then those populators will be ORed (e.g. if the protocol value of one is 6 and the other is 17 then a protocol value of either 6 or 17 will result in a match), which allows the creation of more complex populators.

Existing populators are edited from the Edit Custom Dimension dialog (see Editing a Custom Dimension).

To edit a populator:

1. On the Populators tab of the Edit Custom Dimension dialog, click in the row of the populator that you want to edit. The Edit Populator dialog will open.
2. Edit the populator fields that you wish to change (see Populator Field Definitions).
3. Click the Save button to save changes to the populator and return to the Edit Custom Dimension dialog.
4. Click the Save button to save the changes to the custom dimension.