CH logo® Knowledge Base
Contents Search
   

 

Custom Dimensions

Note: These settings are accessed via the Admin menu, which is displayed to Admin users only (hidden from Member users).

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

 

 
 top

Dimensions and Populators

Custom dimensions provide a mechanism by which Kentik Detect customers can add up to 10 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 Ad-Hoc Filter 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 include a direction (src or dst), which means that a match on a given populator is a match on either SRC-related flow fields or DST-related flow fields (not both).

 

Dimension and Populator Limits

The following table shows per-customer limits on dimensions and populators:

Max Custom Dimensions Max Populators Max Populator Value Length
10 per customer account. 10,000 total, customer-wide across all custom dimensions (no additional per-dimension limit). 128 characters.

Note: 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.

 

 
 top

Custom Dimensions Page

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:

 

 
 top  |  section

Custom Dimensions Page UI

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).

 

 
 top  |  section

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).

 

 
 top

Custom Dimension Dialogs

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.

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.

 

 
 top  |  section

About Dimension Admin Dialogs

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.

 

 
 top  |  section

Dimension Dialogs UI

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.

 

 
 top  |  section

Dimension General Tab

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.

Element Add Dimension Edit Dimension Description
Dimension name Editable field Read-only The name of the custom dimension, which must start with “c_” and contain only alphanumeric characters and underscores. This is the name that will be used for the column that corresponds to the new dimension in the KDE Tables.
Type Editable field Read-only The type of the custom dimension, chosen from the drop-down menu: string (default) or uint32.
Display name Editable field Editable field The name that will be shown for the dimension in the Kentik Detect portal (e.g. in the Query Dimension Selectors or the Filtering Pane Settings).

 

 
 top  |  section

Dimension Populators Tab

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.

 

 
 top  |  section

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 (src or dst) 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).

 

 
 top

Populator Admin Dialogs

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.

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.

 

 
 top  |  section

About Populator Admin Dialogs

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.

 

 
 top  |  section

Populator Dialogs UI

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 interface from your organization’s collection of Kentik-registered interfaces. This button is only present if the interface being edited was manually added.
  • Cancel button: Cancel the add interface or edit interface 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 interface and exit the dialog.
  • Save button (Edit Populator dialog only): Save changes to interface settings and exit the dialog.

 

 
 top

Populator Fields

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

 

 
 top  |  section

Populator Field Definitions

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 column in each table below indicates, in order, whether or not the following validations will be applied to a given populator field:

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

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

 

General Populator Settings

Field Description Validation A, B, C
Value Required: The value placed in the custom column when there’s a match with the ANDed populator parameters below.
• When the custom dimension type is “string”:
- Valid characters: alphanumeric, spaces, dashes, underscores.
- Length: min=1, max=128.
• When the custom dimension type is “uint32”
- Valid values: min=0, max=4294967295.
No, No, No
Direction Required: The direction (src or dst) of the flow fields in which to look for a match with the populator parameters below. N.A.

 

Populator Device Matching

Field Description Validation A, B, C
Device name Results in a match if this value appears within the name of a device or equals the IP address of a device that has been configured to send flow records to Kentik Detect. Yes, Yes, No
Device Type Router or host (e.g. nProbe), as specified by the user when creating the device. Yes, No, Yes
Site Results in a match if this value appears within the name of a site to which the device sending the flow record to Kentik has been assigned (see About Sites). Yes, No, Yes
Interface name/description Results in a match if this value appears within the name or description of a source or destination interface. Yes, Yes, Yes

 

Populator IP Matching

Field Description Validation A, B, C
IP address (IP/CIDR format) Expressed in IPv4 or IPv6 CIDR notation (e.g. 38.12.34.0/24; see CIDR Notation), this value will result in a match if it corresponds to a range of IP addresses in the flow, either source (SRC IP) or destination (DST IP). Yes, No, No
Port Results in a match if this value appears within a port number in the flow, either source (SRC Port) or destination (DST Port). Yes, No, No
TCP flag An integer number between 0 and 255 representing an 8-bit binary bit pattern. At ingest this pattern is used as a bitmask that is ANDed with the composite (ORed) bit pattern of the TCP flags set in the flow. A match will result if the value in both the flow bit pattern and the bitmask is 1 at any of the eight places. No, No, No
Protocol Name or Number Results in a match if this value is the same as the protocol of the traffic represented by the flow. The protocol of TCP is 6, and of UDP is 17. Yes, No, No

 

Populator BGP Matching

Field Description Validation A, B, C
Last-hop (origin) ASN Results in a match if this value is the same as the last ASN (16- or 32-bit) in the path in the routing table for either the source (SRC IP) or destination (DST IP). Yes, No, No
Last-hop (origin) AS Name Results in a match if this value represents the name corresponding to the last ASN in the path in the routing table for either the source (SRC IP) or destination (DST IP). Yes, No, Yes
Next-hop ASN Results in a match if this value is the same as the ASN (16- or 32-bit) of the next hop router based on AS path. Yes, No, No
Next-hop AS Name Results in a match if this value represents the name corresponding to the ASN of the next hop router based on AS path. Yes, No, Yes
Next-hop IP If a CIDR grouping (IPv4 or IPv6) is specified, a match can be on any address within that grouping. If no CIDR grouping is specified a match requires an exact IP.
- CIDRs may be expressed in “short form” (e.g. 1::2/127).
Yes, No, No
BGP AS Path Results in a match if this value is the same as the BGP AS path in the route (see Specifying BGP Populator Fields). Yes, No, Yes
BGP Community Results in a match if this value is the same as the BGP community of BGP route. May be specified with a form of regex (see Specifying BGP Populator Fields). Yes, No, Yes

 

Other Populator Settings

Field Description Validation A, B, C
MAC Address Results in a match if this value matches source or destination Ethernet (L2) address. Yes, No, No
Country Results in a match if this value includes a two-letter country code associated with the source or destination IP of the flow. Yes, No, No
VLAN(s) Results in a match if this value includes a VLAN ID associated with the source or destination IP of the flow. Yes, No, No

 

 
 top  |  section

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 table below).
  • Commas are supported only as list delimiters (not in actual values or regex).
  • Some fields support the use of database patterns (see table below).
  • In fields where regex is supported (see table below), 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.”

 

 
 top  |  section

Specifying BGP Populator Fields

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:

Special Character Matches
_
(underscore)
start of string
end of string
“ “ (space)
. Any single character, including white space
[ ] The characters, or a range of characters separated by a hyphen, contained within square brackets.
^ The character or null string at the beginning of an input string.
? Zero or one occurrence of the pattern containing the question mark.
$ End of string
* Zero or more sequences of the preceding character. Also acts as a wildcard for matching any number of characters.
+ One or more sequences of the preceding character.
() Used for nesting of expressions.

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.

 

 
 top

Add or Edit Dimensions

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

 

 
 top  |  section

Adding a Custom Dimension

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).

 

 
 top  |  section

Editing a Custom Dimension

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.

 

 
 top

Add or Edit Populators

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:

 

 
 top  |  section

Adding a Populator

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.

 

 
 top  |  section

Editing a Populator

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.
 

In this article: