Skip to content

Commit b59f223

Browse files
ysyneuysyneu
authored
Merge pull request #6 from flashcatcloud/mapping
feat: add enrich mapping api
2 parents 873489b + 830c3d8 commit b59f223

2 files changed

Lines changed: 282 additions & 7 deletions

File tree

‎en/on-call/integration/alert-integration/label-enhancement.mdx‎

Lines changed: 141 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,7 @@
11
---
22
title: "Label Enhancement"
3-
description: "Label enhancement automatically generates new labels during alert ingestion to supplement source data. Examples: extract IP from description, map resource ID to readable name, combine multiple fields to generate jump links"
3+
description: "Label enhancement automatically generates new labels during alert ingestion to supplement source data. Examples: extract IP from description, map resource ID to readable name, combine multiple fields to generate jump links, query external systems via API for dynamic data"
4+
keywords: ["label enhancement", "auto labels", "data extraction", "field mapping", "alert labels", "API mapping", "dynamic labels"]
45
---
56
{/*
67
## Video Introduction
@@ -104,7 +105,18 @@ Multiple rules execute sequentially from top to bottom. When a rule doesn't matc
104105
</Tab>
105106

106107
<Tab title="Label Mapping">
107-
**Scenario**: When source alert label values are variable and not intuitively meaningful, use mapping to map source labels to newly defined labels and values. For example, source alerts only have resource type IDs, but want to show corresponding resource type names.
108+
**Scenario**: When source alert label values are variable and not intuitively meaningful, use mapping to map source labels to newly defined labels and values.
109+
110+
Label mapping supports two mapping methods:
111+
112+
| Mapping Type | Description | Use Case |
113+
| :--- | :--- | :--- |
114+
| **Schema (Mapping Table)** | Static mapping via predefined CSV mapping table | Mapping relationships are relatively fixed with limited data |
115+
| **API (API Mapping)** | Dynamic mapping by calling external API service | Need to query external systems (e.g., mapping api) for real-time data |
116+
117+
<Tabs>
118+
<Tab title="Schema Mapping">
119+
**Example**: Source alerts only have resource type IDs, want to show corresponding resource type names.
108120

109121
<Steps>
110122
<Step title="Prepare Mapping Table File">
@@ -152,7 +164,46 @@ Prepare a CSV format mapping table file to map resource type IDs in alerts to ac
152164
</Step>
153165
</Steps>
154166
</Tab>
167+
168+
<Tab title="API Mapping">
169+
**Example**: Need to query responsible team, service tier, and other dynamic data from mapping api system based on host information in alerts.
170+
171+
<Steps>
172+
<Step title="Create Mapping Service">
173+
1. Go to `Integration Center` → `Mapping Service` → `Create Mapping Service`
174+
2. Fill in service configuration:
175+
176+
| Configuration | Description | Example |
177+
| :--- | :--- | :--- |
178+
| Service Name | Readable name for the service | Mapping api Asset Query Service |
179+
| Description | Service purpose description | Query asset info by host IP |
180+
| Request URL | API request address | `https://mapping-api.example.com/v1/enrich-event` |
181+
| Headers | HTTP request header configuration | `X-Auth-Token: your-token` |
182+
| Timeout | Request timeout in seconds | 5 |
183+
| Retry Count | Number of retries after failure | 2 |
184+
185+
<Tip>
186+
If the API uses HTTPS with an untrusted certificate, you can enable the `Skip Certificate Verification` option.
187+
</Tip>
188+
</Step>
189+
190+
<Step title="Configure Mapping Rule">
191+
Add a mapping rule in label enhancement, select mapping type as `API`:
192+
1. Select the created mapping service
193+
2. Configure `Result Label List`: specify label names expected from API response, e.g., `owner_team`, `service_tier`, `host_ip`
194+
3. Enable `Override` option as needed
195+
</Step>
196+
197+
<Step title="Verify Mapping Result">
198+
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.
199+
</Step>
200+
</Steps>
201+
</Tab>
155202
</Tabs>
203+
</Tab>
204+
</Tabs>
205+
206+
## Mapping Data Management
156207

157208
### Mapping Table Data Management
158209

@@ -171,9 +222,96 @@ In the mapping table details page, you can manage mapping table data:
171222
</Frame>
172223

173224
<Tip>
174-
For frequently changing mapping relationships (like CMDB data sync), we recommend using [Flashduty API](https://developer.flashcat.cloud/api-142429470) for automated updates.
225+
For frequently changing mapping relationships (like Mapping api data sync), we recommend using API mapping, or use [Flashduty API](https://developer.flashcat.cloud/api-142429470) for automated mapping table updates.
175226
</Tip>
176227

228+
### Mapping Service API Specification
229+
230+
When using API mapping, your external API service must follow these specifications:
231+
232+
#### Request Specification
233+
234+
Flashduty will call your API via `POST` method with the following request body:
235+
236+
```json
237+
{
238+
"result_label_keys": ["owner_team", "service_tier", "host_ip"],
239+
"event": {
240+
"account_id": 1,
241+
"channel_id": 20,
242+
"data_source_id": 15,
243+
"data_source_type": "prometheus",
244+
"description": "CPU usage for instance '10.0.1.1:9100' is over 95%",
245+
"title": "High CPU Usage on instance 10.0.1.1:9100",
246+
"alert_key": "d41d8cd98f00b204e9800998ecf8427e",
247+
"alert_id": "62d6c0f6b8f1b2b3c4d5e6f7",
248+
"event_severity": "Critical",
249+
"event_status": "Critical",
250+
"event_time": 1678886400,
251+
"labels": {
252+
"region": "us-east-1",
253+
"service": "service-A",
254+
"env": "production",
255+
"instance": "10.0.1.1:9100"
256+
}
257+
}
258+
}
259+
```
260+
261+
| Field | Type | Description |
262+
| :--- | :--- | :--- |
263+
| `result_label_keys` | array[string] | List of expected label names to return, configured by user in the rule |
264+
| `event` | object | Complete information of the current alert event |
265+
266+
#### Response Specification
267+
268+
The API must return a JSON response in the following format:
269+
270+
**Success Response** (HTTP 200):
271+
272+
```json
273+
{
274+
"result_labels": {
275+
"owner_team": "team-database",
276+
"service_tier": "tier-1",
277+
"host_ip": "10.0.1.1"
278+
}
279+
}
280+
```
281+
282+
| Response Code | Description |
283+
| :--- | :--- |
284+
| `200 OK` | Success, returns `result_labels` object |
285+
| `404 Not Found` | No matching data found |
286+
| `400 Bad Request` | Invalid request format |
287+
| `5xx` | Internal server error |
288+
289+
<Note>
290+
If a requested label cannot find a corresponding value, the API **should not** include that key in `result_labels`.
291+
</Note>
292+
293+
#### Security Constraints
294+
295+
For security purposes, the following HTTP Headers are prohibited in mapping services:
296+
297+
| Category | Prohibited Headers |
298+
| :--- | :--- |
299+
| Authentication | `authorization`, `proxy-authorization`, `cookie`, `x-api-key`, `x-access-token` |
300+
| IP Spoofing | `x-forwarded-for`, `x-real-ip`, `true-client-ip`, `x-client-ip` |
301+
| Host & Routing | `host`, `x-forwarded-host`, `x-forwarded-proto`, `x-internal-id`, `x-user-id` |
302+
| Protocol Related | `transfer-encoding`, `upgrade`, `connection` |
303+
304+
<Tip>
305+
We recommend using custom Headers with `X-Custom-` or `X-Enrich-` prefix for authentication.
306+
</Tip>
307+
308+
#### Best Practices
309+
310+
1. **Performance First**: The API is on the critical path of alert processing, must ensure low latency (recommended < 500ms)
311+
2. **Implement Caching**: For identical query conditions, implement caching to improve performance
312+
3. **Idempotent Design**: Multiple calls for the same event should return identical results
313+
4. **Secure Authentication**: API must be protected by authentication mechanisms to prevent unauthorized access
314+
177315
## Further Reading
178316

179317
<CardGroup cols={2}>

‎zh/on-call/integration/alert-integration/label-enhancement.mdx‎

Lines changed: 141 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
---
22
title: "标签增强"
3-
description: "标签增强可在告警接入时自动生成新标签，弥补源数据不足。例如：从描述中提取 IP、将资源 ID 映射为可读名称、组合多个字段生成跳转链接"
4-
keywords: ["标签增强", "自动标签", "数据提取", "字段映射", "告警标签"]
3+
description: "标签增强可在告警接入时自动生成新标签，弥补源数据不足。例如：从描述中提取 IP、将资源 ID 映射为可读名称、组合多个字段生成跳转链接、通过 API 查询外部系统获取动态数据"
4+
keywords: ["标签增强", "自动标签", "数据提取", "字段映射", "告警标签", "API映射", "动态标签"]
55
---
66
{/*
77
## 视频介绍
@@ -105,7 +105,18 @@ keywords: ["标签增强", "自动标签", "数据提取", "字段映射", "告
105105
</Tab>
106106

107107
<Tab title="标签映射">
108-
**场景**：当源告警信息中的标签值不固定且不能直观定位其含义时，可以通过映射的方式将源标签映射为新定义的标签和值。比如源告警中只有资源类型 ID 信息，但希望将每个 ID 对应的资源类型名称也体现出来。
108+
**场景**：当源告警信息中的标签值不固定且不能直观定位其含义时，可以通过映射的方式将源标签映射为新定义的标签和值。
109+
110+
标签映射支持两种映射方式：
111+
112+
| 映射类型 | 说明 | 适用场景 |
113+
| :--- | :--- | :--- |
114+
| **Schema（映射表）** | 通过预定义的 CSV 映射表进行静态映射 | 映射关系相对固定，数据量有限 |
115+
| **API（接口映射）** | 通过调用外部 API 服务进行动态映射 | 需要查询外部系统（如 mapping api）获取实时数据 |
116+
117+
<Tabs>
118+
<Tab title="Schema 映射">
119+
**示例**：源告警中只有资源类型 ID 信息，希望将每个 ID 对应的资源类型名称也体现出来。
109120

110121
<Steps>
111122
<Step title="准备映射表文件">
@@ -153,7 +164,46 @@ keywords: ["标签增强", "自动标签", "数据提取", "字段映射", "告
153164
</Step>
154165
</Steps>
155166
</Tab>
167+
168+
<Tab title="API 映射">
169+
**示例**：需要根据告警中的主机信息从 mapping api 系统查询负责团队、服务等级等动态数据。
170+
171+
<Steps>
172+
<Step title="创建映射服务">
173+
1. 进入 `集成中心` → `映射服务` → `创建映射服务`
174+
2. 填写服务配置信息：
175+
176+
| 配置项 | 说明 | 示例 |
177+
| :--- | :--- | :--- |
178+
| 服务名称 | 服务的可读名称 | Mapping api 资产查询服务 |
179+
| 描述 | 服务用途说明 | 根据主机 IP 查询资产信息 |
180+
| 请求 URL | API 的请求地址 | `https://mapping-api.example.com/v1/enrich-event` |
181+
| 请求头 | HTTP 请求头配置 | `X-Auth-Token: your-token` |
182+
| 超时时间 | 请求超时时间（秒） | 5 |
183+
| 重试次数 | 请求失败后的重试次数 | 2 |
184+
185+
<Tip>
186+
如果 API 使用 HTTPS 且证书不受信任，可开启 `跳过证书验证` 选项。
187+
</Tip>
188+
</Step>
189+
190+
<Step title="配置映射规则">
191+
在标签增强中添加映射规则，选择映射类型为 `API`：
192+
1. 选择已创建的映射服务
193+
2. 配置 `生成标签列表`：指定希望从 API 返回的标签名称，如 `owner_team`、`service_tier`、`host_ip`
194+
3. 根据需要开启 `覆盖` 选项
195+
</Step>
196+
197+
<Step title="验证映射效果">
198+
当告警触发时，Flashduty 会自动调用配置的 API 服务，将告警事件数据发送给外部系统，并将返回的标签添加到告警中。
199+
</Step>
200+
</Steps>
201+
</Tab>
156202
</Tabs>
203+
</Tab>
204+
</Tabs>
205+
206+
## 映射数据管理
157207

158208
### 映射表数据管理
159209

@@ -172,9 +222,96 @@ keywords: ["标签增强", "自动标签", "数据提取", "字段映射", "告
172222
</Frame>
173223

174224
<Tip>
175-
对于频繁变更的映射关系（如 CMDB 数据同步），建议使用 [Flashduty API](https://developer.flashcat.cloud/api-142429470) 进行自动化更新。
225+
对于频繁变更的映射关系（如 Mapping api 数据同步），建议使用 API 映射方式，或通过 [Flashduty API](https://developer.flashcat.cloud/api-142429470) 自动化更新映射表数据。
176226
</Tip>
177227

228+
### 映射服务 API 规范
229+
230+
当使用 API 映射时，您的外部 API 服务需要遵循以下规范：
231+
232+
#### 请求规范
233+
234+
Flashduty 将通过 `POST` 方法调用您的 API，请求体包含以下内容：
235+
236+
```json
237+
{
238+
"result_label_keys": ["owner_team", "service_tier", "host_ip"],
239+
"event": {
240+
"account_id": 1,
241+
"channel_id": 20,
242+
"data_source_id": 15,
243+
"data_source_type": "prometheus",
244+
"description": "CPU usage for instance '10.0.1.1:9100' is over 95%",
245+
"title": "High CPU Usage on instance 10.0.1.1:9100",
246+
"alert_key": "d41d8cd98f00b204e9800998ecf8427e",
247+
"alert_id": "62d6c0f6b8f1b2b3c4d5e6f7",
248+
"event_severity": "Critical",
249+
"event_status": "Critical",
250+
"event_time": 1678886400,
251+
"labels": {
252+
"region": "us-east-1",
253+
"service": "service-A",
254+
"env": "production",
255+
"instance": "10.0.1.1:9100"
256+
}
257+
}
258+
}
259+
```
260+
261+
| 字段 | 类型 | 说明 |
262+
| :--- | :--- | :--- |
263+
| `result_label_keys` | array[string] | 期望返回的标签名称列表，由用户在规则中配置 |
264+
| `event` | object | 当前告警事件的完整信息 |
265+
266+
#### 响应规范
267+
268+
API 需要返回以下格式的 JSON 响应：
269+
270+
**成功响应** (HTTP 200)：
271+
272+
```json
273+
{
274+
"result_labels": {
275+
"owner_team": "team-database",
276+
"service_tier": "tier-1",
277+
"host_ip": "10.0.1.1"
278+
}
279+
}
280+
```
281+
282+
| 响应码 | 说明 |
283+
| :--- | :--- |
284+
| `200 OK` | 成功，返回 `result_labels` 对象 |
285+
| `404 Not Found` | 未找到匹配数据 |
286+
| `400 Bad Request` | 请求格式错误 |
287+
| `5xx` | 服务器内部错误 |
288+
289+
<Note>
290+
如果某个请求的标签无法找到对应的值，API **不应**在 `result_labels` 中包含该 key。
291+
</Note>
292+
293+
#### 安全约束
294+
295+
为确保安全性，以下 HTTP Header 被禁止在映射服务中使用：
296+
297+
| 分类 | 禁用 Header |
298+
| :--- | :--- |
299+
| 认证与授权 | `authorization`, `proxy-authorization`, `cookie`, `x-api-key`, `x-access-token` |
300+
| IP 伪造 | `x-forwarded-for`, `x-real-ip`, `true-client-ip`, `x-client-ip` |
301+
| 主机与路由 | `host`, `x-forwarded-host`, `x-forwarded-proto`, `x-internal-id`, `x-user-id` |
302+
| 协议相关 | `transfer-encoding`, `upgrade`, `connection` |
303+
304+
<Tip>
305+
建议使用 `X-Custom-` 或 `X-Enrich-` 前缀的自定义 Header 进行认证。
306+
</Tip>
307+
308+
#### 最佳实践
309+
310+
1. **性能优先**：API 位于告警处理的关键路径，必须保证低延迟（建议 < 1s）
311+
2. **实现缓存**：对于相同的查询条件，建议实现缓存以提高性能
312+
3. **幂等设计**：对于同一个事件，多次调用应返回相同的结果
313+
4. **安全认证**：API 必须通过认证机制保护，防止未授权访问
314+
178315
## 延伸阅读
179316

180317
<CardGroup cols={2}>

0 commit comments

Comments
 (0)