Label Enhancement

Plan requirement: Basic label enhancement requires an On-call Standard or higher subscription. Advanced label enhancement (such as API mapping) requires a Pro or higher subscription. Learn more

Core Uses

Labels are used throughout Flashduty On-call’s alert processing workflow:

Scenario	Use
Incident Filtering	Quickly filter by labels in incident list
Route Distribution	Route alerts to different channels based on labels
Assignment Notification	Match different escalation rules by labels
Alert Grouping	Group similar alerts by label dimensions
Silence/Inhibition	Match alerts to silence or inhibit by labels

Configure Label Enhancement

Go to Integration Details → Label Enhancement → Add Rule.

Enhancement Types

Type	Description	Example
Extract	Extract content from title/description/labels using regex	Extract IP address from description
Combine	Concatenate new labels using template syntax	Combine domain + event ID to generate log link
Map	Convert values to readable names via mapping table	Map resource ID to resource type
Delete	Remove specified labels	Delete sensitive info labels

Configuration Options

Option	Description
Condition	Only applies to events (both alert events and change events) matching the conditions, see Configure Filter Conditions
Overwrite	When enabled, overwrites labels with same name; disabled by default
Preview	Preview rule effects using real alerts

Multiple rules execute sequentially from top to bottom. When a rule doesn’t match, it’s skipped and no corresponding label is generated.

Condition Fields

Label enhancement rules apply to both alert events and change events, and the fields usable in conditions are the union of the two:

Field	Description
`labels.<name>`	Any label; label names are unrestricted
`data_source_id`, `integration_id`	Data source (integration) ID; the two fields are equivalent
`severity`, `event_severity`, `alert_severity`	Alert event severity; the three fields are equivalent, only carried by alert events
`status`	Event status: alert status for alert events, change status for change events
`title`	Event title
`description`	Event description
`title_rule`	Alert title rule ID, only carried by alert events
`alert_key`	Unique identifier of the alert event
`change_key`	Unique identifier of the change event

Condition fields are validated when a rule is saved: fields outside this vocabulary (such as typos, or fields belonging to other rule families like incident_severity or dedup_key) cause the save to fail with an error. Rules saved before this validation was introduced are unaffected, but re-saving a rule containing an unsupported field fails.

Configuration Examples

Label Extraction
Label Combination
Label Mapping

Scenario: Alert events come from email integration; need to extract key information from description as labels for other scenarios, like extracting IP and trigger value from description as independent labels.

View Original Alert

Configure Extraction Rule

Verify Extraction Result

Scenario: When source alert label values are variable and not intuitively meaningful, use mapping to map source labels to newly defined labels and values.Label mapping supports two mapping methods, selected via an inline radio toggle when adding a mapping rule — choose Schema or API:

Mapping Type	Description	Use Case
Schema (Mapping Table)	Static mapping via predefined CSV mapping table	Mapping relationships are relatively fixed with limited data
API (API Mapping)	Dynamic mapping by calling external API service	Need to query external systems (e.g., mapping api) for real-time data

Schema Mapping
API Mapping

Example: Source alerts only have resource type IDs, want to show corresponding resource type names.

Prepare Mapping Table File

Prepare a CSV format mapping table file to map resource type IDs in alerts to actual resource type names.

ID	Type
A	server
B	router
C	gateway
D	database
E	MQ

Create Mapping Table

Go to Configuration → Mappings → Schema → Create mapping schema
Fill in basic info like name, description, management team, etc.
In Mapping Table Data, upload the prepared CSV file (if quantity is small, you can edit and add in mapping details page after creation)
Select Source Label (e.g., ID), select Target Label (e.g., Type)
Click Create to complete mapping table creation

Configure Mapping Relationship

Verify Mapping Result

Original Alert: Reported alert info only has resource ID, no resource type name.

Mapping Result: Through configured mapping relationship, map resource ID to new resource type name label.

Example: Need to query responsible team, service tier, and other dynamic data from mapping api system based on host information in alerts.

Create Mapping Service

Go to Configuration → Mappings → API → Create API
Fill in service configuration:

Configuration	Description	Example
Service Name	Readable name for the service	Mapping api Asset Query Service
Description	Service purpose description	Query asset info by host IP
Request URL	API request address	`https://mapping-api.example.com/v1/enrich-event`
Headers	HTTP request header configuration	`X-Auth-Token: your-token`
Timeout	Request timeout, 1-3 seconds, default 2 seconds	1
Retry Count	Retry count on failure, 0-1 times, default 0 times	1

If the API uses HTTPS with an untrusted certificate, you can enable the Skip Certificate Verification option.

Configure Mapping Rule

Add a mapping rule in label enhancement, use the radio toggle to select mapping type as API:

Select the created mapping service
Configure Result Label List: specify label names expected from API response, e.g., owner_team, service_tier, host_ip
Enable Override option as needed

Verify Mapping Result

When an alert is triggered, Flashduty automatically calls the configured API service, sends alert event data to the external system, and adds the returned labels to the alert.

Mapping Data Management

Mapping Table Data Management

In the mapping table details page, you can manage mapping table data:

Feature	Description
Data Search	Search by source label value
Data Add	Manually add mapping data
Data Upload	Upload new data mapping table, will overwrite existing data
Data Download	Download current mapping table data locally
Data Display	Display current mapping table data, can edit or delete

For frequently changing mapping relationships (like Mapping api data sync), we recommend using API mapping, or use Flashduty API for automated mapping table updates.

Mapping Service API Specification

When using API mapping, your external API service must follow these specifications:

Request Specification

Flashduty will call your API via POST method with the following request body:

{
  "result_label_keys": ["owner_team", "service_tier", "host_ip"],
  "event": {
    "account_id": 1,
    "channel_id": 20,
    "data_source_id": 15,
    "data_source_type": "prometheus",
    "description": "CPU usage for instance '10.0.1.1:9100' is over 95%",
    "title": "High CPU Usage on instance 10.0.1.1:9100",
    "alert_key": "d41d8cd98f00b204e9800998ecf8427e",
    "event_severity": "Critical",
    "event_status": "Critical",
    "event_time": 1678886400,
    "labels": {
      "region": "us-east-1",
      "service": "service-A",
      "env": "production",
      "instance": "10.0.1.1:9100"
    }
  }
}

Field	Type	Description
`result_label_keys`	array[string]	List of expected label names to return, configured by user in the rule
`event`	object	Complete information of the current alert event

Response Specification

The API must return a JSON response in the following format: Success Response (HTTP 200):

{
  "result_labels": {
    "owner_team": "team-database",
    "service_tier": "tier-1",
    "host_ip": "10.0.1.1"
  }
}

Response Code	Description
`200 OK`	Success, returns `result_labels` object
`404 Not Found`	No matching data found
`400 Bad Request`	Invalid request format
`5xx`	Internal server error

If a requested label cannot find a corresponding value, the API should not include that key in result_labels.

Security Constraints

For security purposes, the following HTTP Headers are prohibited in mapping services:

Category	Prohibited Headers
Authentication	`authorization`, `proxy-authorization`, `cookie`, `x-api-key`, `x-access-token`
IP Spoofing	`x-forwarded-for`, `x-real-ip`, `true-client-ip`, `x-client-ip`
Host & Routing	`host`, `x-forwarded-host`, `x-forwarded-proto`, `x-internal-id`, `x-user-id`
Protocol Related	`transfer-encoding`, `upgrade`, `connection`

We recommend using custom Headers with X-Custom- or X-Enrich- prefix for authentication.

Best Practices

Performance First: The API is on the critical path of alert processing, must ensure low latency (recommended < 500ms)
Implement Caching: For identical query conditions, implement caching to improve performance
Idempotent Design: Multiple calls for the same event should return identical results
Secure Authentication: API must be protected by authentication mechanisms to prevent unauthorized access

Configure Escalation Rules

Use labels to match escalation conditions

Configure Noise Reduction

Use labels as grouping dimensions

Configure Filter Conditions

Learn label matching syntax

Configure Routing Rules

Distribute alerts to different channels

Quick Start

Channels

Incident Management

Post-Mortem

Status Page

Analytics

Integration Settings

Configuration

Advanced

Integrations

Best Practices

Core Uses

Configure Label Enhancement

Enhancement Types

Configuration Options

Condition Fields

Configuration Examples

Mapping Data Management

Mapping Table Data Management

Mapping Service API Specification

Request Specification

Response Specification

Security Constraints

Best Practices

Further Reading

Configure Escalation Rules

Configure Noise Reduction

Configure Filter Conditions

Configure Routing Rules

​Core Uses

​Configure Label Enhancement

​Enhancement Types

​Configuration Options

​Condition Fields

​Configuration Examples

​Mapping Data Management

​Mapping Table Data Management

​Mapping Service API Specification

​Request Specification

​Response Specification

​Security Constraints

​Best Practices

​Further Reading

Configure Escalation Rules

Configure Noise Reduction

Configure Filter Conditions

Configure Routing Rules

Core Uses

Configure Label Enhancement

Enhancement Types

Configuration Options

Condition Fields

Configuration Examples

Mapping Data Management

Mapping Table Data Management

Mapping Service API Specification

Request Specification

Response Specification

Security Constraints

Best Practices

Further Reading