可观测性与稳定性 / 系统课时

建立日志 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 中,但不会自动建立可搜索字段,从而降低日志格式漂移造成类型冲突的风险。

bash
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" }
      }
    }
  }'

预期结果

json
{"acknowledged":true,"shards_acknowledged":true,"index":"logs-app-v1"}

如果平台已经存在同名 Index,创建请求会失败。练习时可以换一个新版本名;生产环境通常通过 Index Template 和 Alias 管理后续滚动,而不是反复修改已有字段类型。

写入测试文档

用 HTTP 状态码确认文档创建成功,可以避免被动态 _id 干扰。refresh=true 只适合练习和立即验证,不应在高吞吐写入路径中对每条日志都开启。

bash
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
  }'

预期输出

text
201

201 表示新文档已经创建。若返回 400,优先查看响应体中的 mapper_parsing_exception,通常意味着字段值与 Mapping 类型不兼容,例如把 duration_ms 写成 "timeout"。

同时验证三类查询

下面的查询用时间范围限制数据集,用 match 对 message 做全文检索,并按 service 做 Terms 聚合。这样一次就能验证 date、text 和 keyword 三种核心类型是否按预期工作。

bash
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"
        }
      }
    }
  }'

预期结果

json
{"hits":{"total":{"value":1,"relation":"eq"}},"aggregations":{"services":{"buckets":[{"key":"order-api","doc_count":1}]}}}

如果时间查询正常但聚合报错,检查聚合字段是否为 keyword;如果精确的 request_id 查询结果异常,检查它是否被误建成 text。Mapping 一旦已经用于现有数据,通常不能直接把同一字段改成不兼容类型,更稳妥的做法是创建新 Index、写入正确 Mapping,再通过重建索引或后续新数据迁移过去。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

建立日志 Index 与 Mapping

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通