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 drive the whole alert workflow: filtering the incident list, routing alerts to channels, matching escalation rules, grouping alerts, and matching silence and inhibition rules. Label enhancement lets these steps use information the source data doesn’t provide directly.

Configure label enhancement

Go to Integration Details → Label Enhancement → Add Rule.

To turn off label enhancement for an integration, delete all rules and save (applies to both alert and change events). The edit page then shows No label rules; click Add label rule to configure rules again.

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 with a mapping table	Map resource ID to resource type
Delete	Remove specified labels	Delete sensitive info labels

Mapping methods

When source label values vary or aren’t meaningful on their own, map them to new labels and values. When adding a mapping rule, choose Schema or API:

Mapping Type	Description	Use Case
Schema (Mapping Table)	Static mapping with a 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 (for example, mapping api) for real-time data

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. Flashduty skips a rule that doesn’t match and generates no label for it.

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

Flashduty validates condition fields when you save a rule. Fields outside this vocabulary make the save fail, such as typos or fields from other rule families like incident_severity or dedup_key. Rules saved before this check still work, but re-saving one with an unsupported field fails.

Configuration examples

Label Extraction
Label Combination
Mapping: Schema
Mapping: API

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

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, and so on.
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 (for example, ID), select Target Label (for example, 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, for example, 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

Each account can create up to 20 mapping tables and 50 mapping services (APIs). Creation fails with a limit-exceeded error once the quota is reached.

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 with a POST request 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

Product Comparison

Channels

Incident Management

Post-Mortem

Status Page

Analytics

Integration Settings

Configuration

Advanced

Integrations

Best Practices

Core uses