Custom Geo

The Custom Geo feature in Kentik Detect is discussed in the following topics:

• About Custom Geo
• Custom Geo Page
• Add or Edit Custom Geo

Custom Geo enables you to assign countries to custom groups that you can then use in queries via group-by or filter dimensions from the Custom Geo dimension family. A custom geo is simply a property whose value is text. You can apply this value to one or more countries to create a custom-tailored group of countries that you can refer to together rather than individually.

Note: Custom geos are mutually exclusive, so a given country can be included in only one custom geo at a time.

Once defined on the Custom Geo page (Admin » Custom Geo), custom geos can be used a couple different ways:

• Custom geo group-by: If Source or Destination Custom Geo is included in a query as a group-by dimension (see Query Dimension Selectors), the traffic from all countries assigned to a given custom geo will be evaluated together. For example, if you assign Norway, Sweden, Denmark, Finland, and Iceland to a custom geo for Scandinavia then when a Custom Geo dimension is included in a query the traffic from all five countries will be treated as a single group (Scandinavia) for the top-X evaluation.
• Custom geo filter: If Source or Destination Custom Geo is chosen as a dimension for a filter, then all currently defined custom geos (such as Scandinavia from our example above) will be available to choose from the drop-down list of filter values (see Ad Hoc Filter Controls).

Each flow record whose source or destination country is assigned to a custom geo is permanently tagged with that custom geo at time of ingest, which has the following important consequences:

• A flow’s custom geo value won’t change even if the countries making up that custom geo are later changed. As a result, if a query’s time range includes a point at which there was a change in the custom geo assignment of a given country that change will be reflected in the time series data returned by the query.
  Example: Let’s say that you have all of your custom geos defined by Jan 1, but on Jan 5 you realize that you had mistakenly assigned Namibia to Scandinavia instead of Africa, so you move it from one custom geo to the other. Then on Jan 10 you run a query looking back 10 days. The time series for Africa would show increased traffic at the time of change, and Scandinavian traffic would show a drop at the same time.
• Editing the name of a custom geo effectively creates a new custom geo even if the assigned countries are not changed. Traffic from the countries of the original custom geo will be evaluated separately from the traffic of the same countries that is ingested after the custom geo is renamed.

Notes:
- Unless changed by an administrator on the Custom Geo Page, your organization’s custom geos will default to continents.
- Custom geo (source or destination) is among the dimensions supported for the Geo HeatMap view type.

Custom geos are managed on the Custom Geo page. To access the page, choose Admin from the Kentik navbar, then Custom Geo from the sidebar at left. The page is covered in the following topics:

• Custom Geo Page UI
• Custom Geo Controls

The Custom Geo page includes the following UI elements:

• Custom Geo Map: A world map that is color-coded to indicate which countries belong to your organization’s various custom geos.
• Custom Geo list (at right): A list of your organization’s currently defined custom geos. Each row in the list includes the name of a custom geo against a background whose color corresponds to the color used for the custom geo on the map. A row also includes the following UI elements:
  - Edit button (pencil icon): Opens a form to edit the custom geo (see Custom Geo Controls).
  - Remove button (trash icon): Removes the custom geo.
• Add Custom Geo button: Opens a form that you use to add a new custom geo (see Custom Geo Controls).

The custom geo controls enable you to add to your organization’s collection of custom geos or to edit an existing custom geo:

• Custom Geo Name: Enter a name for the new custom geo, or edit the name of an existing custom geo.
  Note: Because flow records are associated with custom geos at ingest, changing the name of an existing custom geo will effectively create a new custom geo even if the assigned countries are not changed.
• Countries: A field listing the countries included in an existing custom geo (if editing) or to be included in a new custom geo (if adding). See Changing the Countries List.
• Cancel: Cancels the operation without adding a new custom geo.
• Save button (active only when text is present in the Custom Geo Name field): Adds a new custom geo with the specified name. The new custom geo will appear in the custom geo list.

The Countries field lists the countries currently assigned to a custom geo. Countries may be added or removed from the list in the following ways:

• Adding a country:
  - In the field: Click to drop down a menu of countries, then click on one country in the menu. The menu will close when the country is added. Repeat to add all desired countries.
  - In the map: Click a country that isn’t already assigned to a custom geo (country color is gray). The country will be added to the list. Repeat to add all desired countries.
• Removing a country:
  - In the field: Click to drop down a menu of countries, then click on the X at the right of the country you’d like to remove. The country will be removed from the list.
  - In the map: Click the country that you want to remove (country color will not be gray). The country will be removed from the list. Repeat to remove all desired countries.

The management of custom geos is covered in the following sections:

• Adding a Custom Geo
• Editing a Custom Geo

To add a new custom geo to your organization’s collection of custom geos:

1. Open the Custom Geo page (choose Admin from the Kentik navbar, then Custom Geo from the sidebar at left).
2. Click the Add Custom Geo button to open the Custom Geo Controls.
3. In the Custom Geo Name field, enter a name for the new custom geo.
4. Add countries to the Countries field by clicking either in the field or directly on the country on the map (see Changing the Countries List).
5. Click the Save button. The custom geo will be added to the Custom Geo List.

To edit an existing custom geo:

1. Open the Custom Geo page (Admin » Custom Geo).
2. In the Custom Geo List, click the Edit button (pencil icon) in the row of the custom geo that you want to edit. The Custom Geo Controls will open.
3. Edit the custom geo:
   - To change the name, enter a new name In the Custom Geo Name field.
   Note: Because custom geo labeling is applied to flow records at ingest, changing the name of an existing custom geo will effectively create a new custom geo even if the assigned countries are not changed.
   - To change the countries assigned to the custom geo, use the Countries field or the map (see Changing the Countries List).
4. Click the Save button to save changes to the custom geo.