可观测性与稳定性 / 系统课时
建立日志 Index 与 Mapping
建立日志 Index 与 Mapping
这一练习为日志建立可控的 Index 与 Mapping,让时间范围查询、消息全文检索和按服务聚合分别落到合适的数据类型上。完成后,同一条日志既能保留原始 _source,又能避免把数值、时间和标识符误判成不适合检索的类型。
学习目标
- 为日志常用字段选择
date、keyword、text和数值类型。 - 创建显式 Mapping,减少动态类型推断带来的冲突。
- 用一条测试文档验证时间查询、全文检索和聚合能力。
先把字段用途对应到类型
日志字段的类型应由查询方式决定,而不是由“看起来像字符串”决定。时间需要范围过滤,服务名和环境适合精确筛选与聚合,消息正文需要分词检索,耗时则需要数值范围与统计。
| 字段 | Mapping 类型 | 主要用途 |
|---|---|---|
timestamp |
date |
时间范围过滤、排序 |
level |
keyword |
精确筛选、聚合 |
service |
keyword |
按服务筛选、聚合 |
environment |
keyword |
区分生产、测试等环境 |
host |
keyword |
定位实例或节点 |
request_id |
keyword |
精确关联同一请求 |
message |
text |
全文检索 |
duration_ms |
long |
范围查询、统计 |
message 不适合只映射成 keyword,否则无法按分词结果搜索;request_id 也不适合映射成 text,因为它需要按完整值精确匹配。
创建显式 Mapping
下面创建 logs-app-v1。根级 dynamic 设为 false,未声明字段仍会保留在 _source 中,但不会自动建立可搜索字段,从而降低日志格式漂移造成类型冲突的风险。
curl -s -X PUT "http://<HOST>:<PORT>/logs-app-v1" \
-H "Content-Type: application/json" \
-d '{
"mappings": {
"dynamic": false,
"properties": {
"timestamp": { "type": "date" },
"level": { "type": "keyword" },
"service": { "type": "keyword" },
"environment": { "type": "keyword" },
"host": { "type": "keyword" },
"request_id": { "type": "keyword" },
"message": { "type": "text" },
"duration_ms": { "type": "long" }
}
}
}'预期结果
{"acknowledged":true,"shards_acknowledged":true,"index":"logs-app-v1"}如果平台已经存在同名 Index,创建请求会失败。练习时可以换一个新版本名;生产环境通常通过 Index Template 和 Alias 管理后续滚动,而不是反复修改已有字段类型。
写入测试文档
用 HTTP 状态码确认文档创建成功,可以避免被动态 _id 干扰。refresh=true 只适合练习和立即验证,不应在高吞吐写入路径中对每条日志都开启。
curl -s -o /dev/null -w '%{http_code}\n' \
-X POST "http://<HOST>:<PORT>/logs-app-v1/_doc?refresh=true" \
-H "Content-Type: application/json" \
-d '{
"timestamp":"2026-09-18T03:10:00.000Z",
"level":"ERROR",
"service":"order-api",
"environment":"prod",
"host":"app-01",
"request_id":"req-demo-1404",
"message":"payment timeout while creating order",
"duration_ms":1520
}'预期输出
201201 表示新文档已经创建。若返回 400,优先查看响应体中的 mapper_parsing_exception,通常意味着字段值与 Mapping 类型不兼容,例如把 duration_ms 写成 "timeout"。
同时验证三类查询
下面的查询用时间范围限制数据集,用 match 对 message 做全文检索,并按 service 做 Terms 聚合。这样一次就能验证 date、text 和 keyword 三种核心类型是否按预期工作。
curl -s -X POST "http://<HOST>:<PORT>/logs-app-v1/_search?filter_path=hits.total,aggregations.services.buckets" \
-H "Content-Type: application/json" \
-d '{
"query": {
"bool": {
"filter": [
{
"range": {
"timestamp": {
"gte": "2026-09-18T03:00:00Z",
"lt": "2026-09-18T04:00:00Z"
}
}
}
],
"must": [
{
"match": {
"message": "payment timeout"
}
}
]
}
},
"aggs": {
"services": {
"terms": {
"field": "service"
}
}
}
}'预期结果
{"hits":{"total":{"value":1,"relation":"eq"}},"aggregations":{"services":{"buckets":[{"key":"order-api","doc_count":1}]}}}如果时间查询正常但聚合报错,检查聚合字段是否为 keyword;如果精确的 request_id 查询结果异常,检查它是否被误建成 text。Mapping 一旦已经用于现有数据,通常不能直接把同一字段改成不兼容类型,更稳妥的做法是创建新 Index、写入正确 Mapping,再通过重建索引或后续新数据迁移过去。