​
Overview

Labels are key-value pairs that add custom metadata to resources in the Heex Smart-Data platform. They provide a flexible way to organize, classify, and search your data across systems, triggers, events, and recordings.

With strategic use of labels, you can implement and track any custom management policy. From filtering systems by operational group to flagging events for review, labels keep your workflow organized and your data actionable.

​
Key Concepts

  • Key-Value Structure: Each label consists of a key (category) and a value (specific detail). For example: environment = production or robot_type = delivery.

  • Custom Classification: Tag resources based on criteria relevant to your operations: location, purpose, team ownership, status, and more.

  • Enhanced Searchability: Quickly locate resources using Heex’s filtering and search capabilities, dramatically reducing time spent navigating large datasets.

​
Label Types

Heex supports four distinct label types, each with specific properties and use cases:

​
System Labels

  • Purpose: Identify and categorize your systems
  • Creation: Added during system creation or when generating an event
  • Behavior:
    • Fixed for historical events (updates to system labels won’t retroactively change past events)
    • Can be deleted but not added after an event occurs
  • Usage: Filter systems in the Systems view
  • Example: version = 2.1 to track robot software versions

​
Trigger Labels

  • Purpose: Classify and prioritize triggers
  • Creation: Set during trigger creation and automatically added to resulting events
  • Behavior: Can be deleted but not added after event generation
  • Example: severity = high for critical collision detection triggers

​
Event Labels

  • Purpose: Add context and classification to events after they occur
  • Creation: Manually added via the Heex web app or CLI after event creation
  • Behavior: Fully flexible for post-event analysis and categorization
  • Example: test_run = 2025-03-20 for tracking specific test sessions

​
Recording Labels

  • Purpose: Add metadata from the recording process itself
  • Creation: Generated by the Heex Agent’s recorder and included in event metadata
  • Behavior: Fixed once set; cannot be edited or removed
  • Customization: Implementable via the SDK’s generateRequestedLabels() method in Recorder classes
  • Example: sensor_status = calibrated to indicate sensor state during recording

​
Groups: Special-Purpose Labels

Groups are a specialized label type where the key is predefined as group. They enable you to cluster related systems for collective monitoring and management.

  • Purpose: Organize systems—similar or different—for bulk operations
  • Creation: Assigned during system configuration
  • Usage: Filter by group in the Systems view
  • Example: group = warehouse_bots to identify all robots in a specific facility

​
Working with Labels

​
In the Heex Web Application

  • Viewing: Browse existing labels in the Systems page or Smart-Data view (Events list)
  • Filtering: Use the filter interface to show only resources with specific labels
  • Example: Filter for environment = test to isolate test systems from production

​
Using the Heex SDK

  • Custom Recorders: Override generateRequestedLabels() in Recorder implementations to define custom recording labels

  • Dynamic Labels: Use SDK utilities like addLabel() (available in both C++ and Python) to programmatically define key-value pairs

  • Example:

In a C++ Recorder implementation do the following:

this->addLabel("mode", "autonomous");

​
Best Practices

  • Use consistent naming conventions for keys and values
  • Create a labeling schema before widespread implementation
  • Consider searchability when designing label structures
  • Limit the number of unique label keys to prevent fragmentation
  • Document your labeling conventions for team reference