Creating Optional Subnet Tags

Overview

Subnet tags enable you to enrich network flow data with business-relevant metadata by associating key-value pairs with specific subnets. This categorization system allows you to filter, group, and analyze traffic based on dimensions meaningful to your organization—such as security zones, geographic locations, business units, or any other custom classification.

By tagging subnets with structured metadata, you can:

• Filter traffic by specific tag keys and values to focus on relevant network segments.

• Group flows by tag categories to visualize traffic patterns across business dimensions.

• Create meaningful alerts that align network data with organizational structure.

• Automate analysis by applying consistent labels across large network environments.

Subnet tags use a key-value pair structure (for example, security_zone:dmz, region:emea, cost_center:engineering) that provides hierarchical organization and enables multi-dimensional analysis.

Tag Structure and Format

Key-Value Pairs

Each subnet tag consists of:

• Key: A category or dimension (for example, branch, security_zone, owner)

• Value: A specific identifier within that category (such as london, dmz, alice_meyers)

Format: key:value

Multiple Tags per Subnet

You can assign multiple key-value pairs to a single subnet to create rich, multi-dimensional classification. See Creating Subnet Tags for instructions.

Tag Restrictions

Reserved Keys: Tag keys beginning with thousandeyes: are used to indicate predefined subnet attributes (such as subnet-name) that cannot currently be used by customers as tag keys. User-defined tag keys beginning with thousandeyes: will result in an error.

Creating Subnet Tags

Manual Tag Assignment

There are two ways to assign tags manually: directly within the Create Subnets panel, or by first defining the tags in Tags Management, then assigning them to subnets in the Create Subnets panel.

Direct Tag Creation

You can create and assign subnet tags directly in the Create Subnets panel.

Note: due to unique CIDR requirements, you cannot create multiple values per key in this panel. Use the 2-Step Tag Creation method, below, if you wish to define multiple values per key first.

1. In Traffic Insights > Settings > Subnet Tags, select Create Subnets.

2. In the configuration dialog:

   • Subnet Name: Enter a meaningful name for this subnet.

   • Subnet: Enter the CIDR notation (for example, 10.50.0.0/16 for IPv4 or 2001:db8::/32 for IPv6)

3. Click + Add.

4. Type in your key followed by the delimiter colon (":").

5. Type in your value.

6. Click Save.

2-Step Tag Creation

2-step tag creation involves first generating a set (or sets) of key-value pairs, then assigning them to your subnets.

1. Create the key-value pairs

1. Navigate to Traffic Insights > Settings > Subnet Tags.

2. Select the Tags Management cog.

3. Click Create New in the lower left of the panel.

4. In the configuration dialog:

   • Enter the Key (such as region).

   • Enter the Value (such as emea).

5. Click Save.

Repeat this process for each key-value pair you wish to create.

2. Assign your new tags to your subnets

1. In Traffic Insights > Settings > Subnet Tags, select Create Subnets.

2. In the configuration dialog:

   • Subnet Name: Enter a meaningful name for this subnet.

   • Subnet: Enter the CIDR notation (for example, 10.50.0.0/16 for IPv4 or 2001:db8::/32 for IPv6)

3. Click + Add.

4. Select one or more key-value pairs from the available list.

5. Click Save.

The system applies these tags to all matching flow records at ingestion. See Tag Application and Timing for more information about how this is done.

Bulk Upload Via CSV

For large-scale environments with hundreds or thousands of subnets, manual tagging is impractical. The CSV bulk upload feature enables you to manage subnet tags efficiently.

Workflow Overview

1. Download the current subnet tag configuration or a blank template.

2. Edit the CSV file with your tag definitions.

3. Upload the file to replace all existing subnet tags.

CSV upload performs a complete replacement of all existing subnet tags. You are required to download your current configuration before uploading a new file. We recommend you save it somewhere safe in case you want or need to revert to it.

1. Download Current Configuration

1. Navigate to Traffic Insights > Settings > Subnet Tags.

2. Select + Bulk Upload.

3. In the right-hand panel, click Download Data to export your existing configuration or to download a blank CSV template.

2. Populate CSV File

1. Open your downloaded CSV file.

2. Either edit your current subnets or add new ones, adhering to the following specifications.

File Format

Column headers required:

• thousandeyes:ti:subnet-cidr

• thousandeyes:ti:subnet-name

• <key name>: User-defined tag key. Keys must be unique.

Rows must contain, respectively:

• Your subnet CIDR notations for IPv4 or IPv6 (such as 10.50.0.0/16 or 2001:db8::/32). All network CIDRs throughout the entire CSV file must be unique. Duplicate network CIDRs trigger an error.

• Your subnet names.

• The values for your keys.

Characters allowed for columns and rows:

• Uppercase letters (A-Z)

• Lowercase letters (a-z)

• Numbers (0-9)

• Spaces ( )

• Special characters: . : / = + - @ _

Trimming: All cell values (including headers) have leading and trailing whitespace automatically trimmed prior to validation and processing.

File Validation

The system enforces:

• File Type: Comma Separated Values (CSV)

• File size limits: 2 MB compressed (compression is automatic), about 20 MB uncompressed.

• Encoding: UTF-8.

• Maximum subnets (unique CIDRs): 50,000

• Max tag columns: 40

• Max tags per subnet: 10

• Max character length for subnet names, keys, and values: 64, after trimming

• Case sensitivity: Subnet names, tag keys, and tag values are case sensitive. Values that differ only by letter casing (for example, Prod vs. prod) are treated as distinct and are not considered equivalent. However, all column names in the header row must be unique, disregarding case. For instance, having both "Tag1" and "tag1" as column headers is not permissible.

Format Example

thousandeyes:ti:subnet-cidr	thousandeyes:ti:subnet-name	Location	Environment	Owner	Cost Center	Project
10.0.0.0/8	prod	US-East	Production	John Doe	CC123	App Migration
172.16.0.0/16	dev	EU-West	Development	Jane Smith	CC456	New Feature
192.168.1.0/24	stg	Asia-South	Staging	Alice Brown	CC789
10.1.1.0/24	Prod	US-East	Production		CC123

In the example above:

• The subnet 192.168.1.0/24 possesses Location, Environment, Owner, and Cost Center tags, but not a Project tag as its value is empty.

• The subnet 10.1.1.0/24 includes Location, Environment, and Cost Center tags, but does not have Owner or Project tags as their values are empty.

Notes

• Both IPv4 and IPv6 subnets are supported in the same file.

• Import of the whole file fails if duplicate rows or column-headers are detected.

• Overlapping subnets prioritize the longest prefix. See Overlapping Subnets for information about how multiple subnets per IP are treated.

3. Upload CSV File

• In the Bulk Upload panel, click Select File.

  • Browse to your edited CSV file.

  • Once selected, the file is automatically uploaded. Before upload, the system:

    • Validates the file format, size, and tag count limits.

    • Rejects the upload with an error message if validation fails.

    • Applies all changes atomically if validation succeeds—either all tags are updated or none.

During upload: Manual tagging and additional uploads are disabled until processing completes.

If validation fails, you receive:

• An error message.

• No changes to your existing configuration.

When validation succeeds:

• All existing subnet tags are replaced with the uploaded configuration.

• The operation is atomic — no partial updates occur.

• Changes take effect immediately for newly ingested flows.

Editing Subnet Tags

To manually edit an existing subnet tag:

1. Navigate to Traffic Insights > Settings > Subnet Tags.

2. Click the ellipsis (...) on the row of the subnet you want to edit.

3. Select Edit.

4. In the editing panel:

   • Change the subnet name.

   • Add or remove subnet CIDRs.

   • Add or remove key:value pairs.

5. Click Save.

Use the bulk upload procedure to edit multiple subnets or tags in one go.

Deleting Subnet Tags

• To delete a single subnet, select Delete from the ellipsis (...) menu at the end of the subnet’s row.

• To delete several subnets, check the boxes next to the subnets you want to delete, then click Delete at the bottom of the table.

• To delete all subnet tags, upload a blank csv template via bulk upload.

Using Subnet Tags in Analysis

Once configured, subnet tags become powerful dimensions for filtering and grouping traffic data.

Filtering by Tags

Filter flow data by specific tag keys and values:

1. In Traffic Insights > Views, click Add Filter at the top of the page.

2. Select Subnet Tag from the filter options.

3. Choose a tag key or one or more values for that key. Selecting a value automatically selects the key as well.

4. Click off the filter to apply your settings.

Multiple tag filters can be combined to create precise queries (for example, "show all traffic in the dmz security zone within the london branch").

Grouping by Tags

Group conversations by tag categories:

1. In Traffic Insights > Views, select View By: Conversations.

2. In the table settings, select Group By: Subnet Tags.

This orders all table data by your subnets.

Tag Application and Timing

When Tags Are Applied

• Tags are applied to flow records at time of ingestion when flows are first processed.

• The system matches the client and server IP addresses against configured subnet definitions.

• All matching tags are enriched into the flow record.

Overlapping Subnets

When a flow's IP address matches multiple subnet definitions:

• Per flow record, two subnets can be applied: one from the client IP and one from the server IP.

• The longest IP prefix from each subnet is applied to the flow record.

• All tags associated with those prefixes are applied to the flow record. Tags from shorter subnet prefixes are not applied to the flow record.

Retroactive Changes

Changes to subnet tag definitions are not applied retroactively.

• New or updated tags: apply only to flows ingested after the change.

• Historical data: retains the tags that were active when those flows were originally ingested.

• Retention period: you can filter and group by both old and new tags until historical data expires (current retention: 30 days).

Migration from Legacy Labels

If you previously used simple string labels (prior to the key-value pair migration):

• All legacy labels have been automatically migrated to key-value format.

• Migration format: old_label:old_label (for example, a label “webex” becomes webex:webex).

• Historical flow data retains these migrated tags.

• You can update or replace these tags at any time using the manual or bulk upload methods.

View Your Subnet Tags

Subnet Tagging screen

You can find the Subnets Tags screen at Traffic Insights > Settings > Subnets Tags.

Understanding the Subnet Tag Table

• Subnet Name: A unique name provided for this subnet using + Create Subnets. Note that the name is not the same as the subnet tags, which are re-usable.

• Subnet: The IP address range associated with this subnet for example 192.168.110.0/24.

• Tags: One or more tags assigned to this subnet.

• Creation Type: Either bulk upload or manual.

• Created By: The ThousandEyes user who created this subnet.

• Created On: Date this subnet was created.

• Modified By: ThousandEyes user who last modified this subnet.

• Modified On: Date this subnet was last modified.

• ... (ellipsis): Click to Edit or Delete each row.

Best Practices

Tag Design

• Use consistent key naming: Establish standard keys across your organization (for example, region, branch, security_zone).

• Align with business structure: Tag according to how your teams organize and analyze network data.

• Document tag keys: Maintain documentation of what each key represents for team consistency.

Bulk Upload Management

• Validate offline: Review your CSV file carefully before uploading.

• Version control: Keep historical versions of your CSV files to track changes over time.

Troubleshooting

CSV Upload Failures

Problem: File rejected with error

Solution:

• Verify the CSV has the correct headers (see Bulk Upload Via CSV).

• Check that all subnet values are valid CIDR notation.

• Ensure you use no reserved keys (starting with thousandeyes:).

• Remove unnecessary tags or consolidate subnets where possible.

Missing Tag Data

Problem: Tags not appearing in filters or groups

Solution:

• Verify tags were saved successfully in Traffic Insights > Settings > Subnet Tags.

• Check that flows match the configured subnet CIDR ranges.

• Remember that tags apply only to newly ingested flows — allow time for new data.

Problem: Old tag values still appearing

Solution:

• This is expected behavior — historical data retains tags from when flows were ingested.

• Old tags disappear as data ages out beyond the retention period (30 days).