Flow Tags

Flow Tags allow you to classify network traffic by mapping IP addresses and CIDR ranges to meaningful labels. Instead of analyzing raw IP addresses, you can tag traffic as belonging to specific servers, applications, environments, or owners — then filter, group, and report on those tags throughout the platform.

Tags are applied in real-time by the Go flow enricher as flows pass through the pipeline. Each flow can match multiple tags across multiple dimensions, and a single IP can belong to several tags simultaneously (e.g., 192.168.100.132 can be tagged as both "Collector" in the server dimension and "Office Network" in the environment dimension).

Concepts

Tags

A tag is a named label with a dimension and optional description. Tags are displayed as cards in the Flow Tag Management view. Each card shows the tag name, dimension badge, description, a color indicator, the number of rules, and the CIDR rules assigned to it.

Rules

Rules are the CIDR-to-tag mappings that define which IP addresses belong to a tag. Each rule specifies a CIDR range (or single IP with /32), a direction, and an optional priority. A tag can have multiple rules — for example, the "Router" tag in the screenshot has two rules: 192.168.100.65/32 and 192.168.100.146/32.

Dimensions

Every tag belongs to one of four classification dimensions. Dimensions are stored as separate array columns on each flow record in ClickHouse, enabling independent filtering and grouping:

Dimension	Use Case	Example Tags
server	Identify specific hosts or infrastructure roles	Collector, Router, Database Server
application	Classify traffic by application or service	Internal, Web Services, DNS
environment	Label networks by deployment stage or location	Office Network, internal-vpc-subnet, Production
owner	Attribute traffic to teams or business units	Engineering, Operations, Customer

Flow Tag Management

The management view shows a summary at the top (total tags and total rules) along with controls for searching, layout switching, and bulk operations.

Search

The search bar filters tags by name or by CIDR rule. Typing an IP address or subnet will show only tags that contain matching rules.

Layout Toggle

Switch between grid view (card layout, shown in the screenshot) and list view (compact table layout) using the toggle buttons. Grid view provides a visual overview; list view is more efficient for large tag inventories.

Expand All / Collapse

Expands or collapses all tag cards to show or hide their CIDR rules. Individual cards can also be toggled by clicking the chevron.

Creating Tags

+ Add Tag

Click + Add Tag to create a new tag. The form includes:

• Name (required) — A unique, descriptive label. Names should be concise since they appear in dashboard filters, chart legends, and flow table columns.
• Description — Optional context explaining what the tag represents.
• Dimension — Select from server, application, environment, or owner. This determines which ClickHouse array column the tag is written to (e.g., src_tags_server, dst_tags_environment).
• Color — A color indicator for visual identification in the tag card grid.

After creating a tag, add one or more CIDR rules to define which IPs it matches.

Managing Rules

Each tag card displays its rules as colored CIDR chips. Click the + button on a tag card to add a new rule, or click the edit/delete icons on an existing rule.

Rule Fields

CIDR / IP Address (required) — A single IP address or CIDR subnet in standard notation. Examples:

• 192.168.100.132/32 — Matches a single host.
• 192.168.0.0/16 — Matches the entire 192.168.x.x range.
• 172.31.0.0/16 — Matches a VPC subnet.
• 10.0.0.0/8 — Matches all RFC1918 Class A space.

Direction — Controls whether the rule matches on the source IP, destination IP, or both:

Direction	Behavior
Both (Source & Destination)	The tag is applied when the CIDR matches either src_addr or dst_addr. This is the most common setting.
Source Only	The tag is only applied when the CIDR matches src_addr. Useful for tagging traffic originating from specific hosts.
Destination Only	The tag is only applied when the CIDR matches dst_addr. Useful for tagging traffic destined to specific services.

Priority — A numeric value controlling match order when multiple rules overlap. Higher priority rules are evaluated first. The default is 0. Priority is primarily useful when you need to ensure a more specific rule takes precedence over a broader one.

Rule Actions

Each rule chip on the tag card supports:

• Copy (clipboard icon) — Duplicates the rule, useful for creating similar rules across tags.
• Edit (pencil icon) — Opens the Edit Rule modal to modify the CIDR, direction, or priority.
• Delete (trash icon) — Removes the rule from the tag.

Importing Flow Tags from NetBox

If you have a NetBox instance configured under Settings → Integrations → NetBox, you can import IP Prefixes as Flow Tags. This is especially powerful for organizations that manage their IP address space in NetBox — every prefix can become a flow classification rule automatically.

To import prefixes as flow tags:

1. Navigate to Settings → Integrations → NetBox and ensure your API URL and token are saved.
2. Check the Flow Tags (IP Prefixes) checkbox under Import Options.
3. Configure the import options:
   • Dimension — Which tag dimension to assign (server, application, environment, owner). The selected dimension applies to all imported prefixes in this batch.
   • Direction — Whether the CIDR matches source IPs, destination IPs, or both.
   • Create Tags — When enabled, new tags are automatically created for each prefix. When disabled, rules are only added to tags that already exist in Chompy.
4. Click Preview Selected to review. Each prefix shows its CIDR, the auto-generated tag name, and whether it's new or already exists.
5. Click Import Selected to execute.

Tag naming from NetBox prefixes — Tag names are automatically built by combining available NetBox metadata: Site name + VRF name + Role + Tenant. For example, a prefix at site "HQ Data Center" in VRF "Production" with role "Infrastructure" would create a tag named HQ Data Center - Production - Infrastructure.

Import Sites First

Import sites and devices from NetBox before importing prefixes. This ensures that site-based tag names reference locations that already exist in Chompy.

How Flow Tagging Works

Flow tags are applied by the Go flow enricher service running between Kafka and ClickHouse:

1. The enricher loads all tag rules from PostgreSQL at startup and periodically reloads them (picking up new or modified rules without restart).
2. For each incoming flow, the enricher checks src_addr and dst_addr against the CIDR index.
3. All matching rules are applied — a single IP can match multiple tags across multiple dimensions.
4. Matched tags are written to array columns on the flow record in ClickHouse:
   • src_tags_server, src_tags_application, src_tags_owner, src_tags_environment
   • dst_tags_server, dst_tags_application, dst_tags_owner, dst_tags_environment
   • src_matched_cidrs, dst_matched_cidrs (for debugging which rules fired)

The enricher uses an optimized CIDR trie structure for matching, supporting 20,000+ flows per second with hundreds of rules.

Sampler Address Filtering

Rules can optionally be scoped to a specific sampler address. This is useful when you have overlapping IP space across different network segments or VPCs — the same CIDR might mean different things depending on which device exported the flow. If a rule has a sampler address set, it only applies to flows from that specific exporter. If the sampler address is empty, the rule applies to all flows regardless of source.

Troubleshooting

Tags not appearing on flows

After creating or modifying tags, the Go flow enricher needs to reload rules from PostgreSQL. This happens automatically on a periodic schedule (typically every 60 seconds). New flows arriving after the reload will have the updated tags. Existing historical flows are not retroactively re-tagged.

Overlapping CIDR rules

When multiple rules match the same IP, all matching tags are applied and deduplicated. The most specific CIDR (longest prefix length) is listed first in the matched_cidrs array. If you need a specific rule to take priority, increase its priority value.

Large number of tags

For environments with hundreds of tags and thousands of rules (common when importing from NetBox), the enricher's trie-based matching remains efficient. Monitor the enricher logs for reload timing if you notice any performance impact after large imports.