用于 Datadog 日志搜索的自然语言界面

Source: Dev.to

介绍

现在是凌晨 2 点。PagerDuty 触发警报。支付服务出现问题。
你打开 Log Explorer，盯着查询栏。是 service:payment 还是 @service:payment？否定使用 NOT 还是 -？认证失败的 facet 是什么来着？

日志里有答案，但语法是瓶颈。本文将演示如何构建一个将自然语言翻译成有效 Datadog 日志搜索查询的工具，并拆解 Datadog 特有的坑点，让这个问题变得有趣。

日志搜索语法让人卡住的地方

@ 前缀规则

保留属性 不使用 @。这些是 Datadog 提供的核心字段：

service:payment-service
status:error
host:web-server-01

自定义 facet 和日志属性 必须 使用 @。任何你自己索引的字段：

@http.status_code:500
@duration:>2000000000
@error.message:*timeout*

把前缀弄反会返回空结果——没有错误，只是空集合。这在紧急调试时尤其让人沮丧。

时长陷阱

Datadog 将时长存储为 纳秒，而不是秒或毫秒。

过滤超过 2 秒的请求：

@duration:>2000000000

少写一个零会过滤 200 毫秒；多写一个零则会寻找 20 秒的请求。事故期间，这个错误会浪费时间。

不常用的 Facet

在使用 Cloud SIEM 或审计日志时，你会遇到类似的 facet：

@evt.name:authentication
@evt.outcome:failure
@network.client.geoip.country_name:*

这些并非日常使用，记不住，但在调查可疑活动时恰恰是必需的查询。

对 LLM 的提示工程

LLM 在训练数据中见过 Datadog 查询，但不足以可靠。它们常会生成看似合理却细微错误的语法。解决办法是使用 系统提示，明确规则：

保留属性（无 @ 前缀）

service:payment-service
status:error
host:web-server-01

Facet 和自定义属性（需要 @ 前缀）

@http.status_code:500
@duration:>1000000000   # 纳秒
@error.message:*timeout*

常见错误要避免

• @service:payment – 错误（保留属性）
• @duration:>2 – 错误（不是纳秒）

纳秒的说明至关重要；否则模型可能会为 “请求超过 2 秒” 生成 @duration:>2，这完全错误。

安全模式

对于不可猜测的 facet，需要提供显式示例：

# 认证失败
@evt.name:authentication @evt.outcome:failure

# CloudTrail 控制台登录
source:cloudtrail @evt.name:ConsoleLogin

# 仅外部 IP
NOT @network.client.ip:10.* NOT @network.client.ip:192.168.*

这些提示可以让准确率达到 80 %。剩下的 20 % 是边缘案例、晦涩的 facet 名称、集成特定属性以及静态提示无法覆盖的语法变体。

检索增强生成

为处理边缘案例，我们索引 Datadog 文档，并在查询时检索相关章节，注入提示中。

双重检索方法

1. 密集嵌入（例如 OpenAI text-embedding-3-large）捕获语义相似性。
2. 稀疏嵌入（例如 SPLADE）捕获精确关键词重叠，确保能找到 @evt.outcome 之类的字符串。

我们使用 Reciprocal Rank Fusion (RRF) 合并两套结果：

results = qdrant_client.query_points(
    collection_name=collection,
    prefetch=[
        Prefetch(query=dense_vector, using="dense", limit=limit * 2),
        Prefetch(query=sparse_vector, using="sparse", limit=limit * 2),
    ],
    query=FusionQuery(fusion=Fusion.RRF),
    limit=limit,
)

这种组合既能呈现概念匹配，也能捕获精确语法匹配，覆盖了让静态提示失效的边缘情况。

使用系统

解释作为验证工具

当接手一个带有复杂查询的仪表盘时：

@evt.name:authentication @evt.outcome:failure \
NOT @network.client.ip:10.* NOT @network.client.ip:192.168.* \
NOT @network.client.ip:172.16.*

你可以问助手 “这段查询做了什么？” 并得到：

“来自内部网络范围之外 IP 的失败认证尝试。”

这加速了理解，并且可以通过让模型解释查询来验证生成的查询是否正确。

自然语言 → 日志搜索示例

安全类查询价值最高：工程师记得 observability 查询（如 service:api status:error），但很少使用 SIEM 风格的 facet，这使得该工具尤为有用。

结论

这个项目有趣的部分并不是 LLM 集成——那相对直接——而是深入学习 Datadog 的细节并教会模型。@ 前缀规则、纳秒陷阱以及安全 facet 模式将一个可用查询和一个悄然失效的查询区分开来。将这些知识显式编码并结合检索到的文档，使工具可靠。

如果想查看实现细节，代码已放在 GitHub 上。

本文观点仅代表本人，不代表雇主。