Oodle Logs — Search and Index Pattern Discovery

Oodle Logs — 搜索与索引模式发现

This skill teaches the agent to search log data using the OpenSearch-compatible query DSL and to discover available log index patterns.

本技能指导Agent使用兼容OpenSearch的Query DSL搜索日志数据，并发现可用的日志索引模式。

Prerequisites

前提条件

bash

brew install oodle-ai/oodle/oodle
oodle configure

Confirm the logs endpoint works:

bash

oodle logs index-patterns -o json | jq 'length'

bash

brew install oodle-ai/oodle/oodle
oodle configure

确认日志端点正常工作：

bash

oodle logs index-patterns -o json | jq 'length'

Command Execution Order

命令执行顺序

Before running any log query:

Run
```
oodle logs index-patterns -o json
```
to discover available log index patterns.
Pick the appropriate index pattern
```
title
```
for your query.
Build the NDJSON query file using the discovered index pattern and OpenSearch Query DSL.
Set
```
--start
```
and
```
--end
```
to cover the time range you need. They default to
```
-1h
```
and
```
now
```
.
Do not guess index names — always confirm with
```
index-patterns
```
first.

运行任何日志查询之前：

执行
```
oodle logs index-patterns -o json
```
以发现可用的日志索引模式。
为你的查询选择合适的索引模式
```
title
```
。
使用发现的索引模式和OpenSearch Query DSL构建NDJSON查询文件。
设置
```
--start
```
和
```
--end
```
参数以覆盖你需要的时间范围，它们的默认值为
```
-1h
```
和
```
now
```
。
不要猜测索引名称——务必先通过
```
index-patterns
```
命令确认。

Quick Reference

快速参考

Task	Command
List log index patterns	`oodle logs index-patterns -o json`
Search logs	`oodle logs query -f query.ndjson --start <start> --end <end> -o json`

任务	命令
列出日志索引模式	`oodle logs index-patterns -o json`
搜索日志	`oodle logs query -f query.ndjson --start <start> --end <end> -o json`

Common Operations

常见操作

List log index patterns

列出日志索引模式

Discover available log index patterns before building log queries. The returned

title

field is used as the

index

value in NDJSON query files.

bash

undefined

在构建日志查询之前，先发现可用的日志索引模式。返回的

title

字段将作为NDJSON查询文件中的

index

值使用。

bash

undefined

CORRECT — list all available index patterns

CORRECT — 列出所有可用的索引模式

oodle logs index-patterns -o json

CORRECT — extract just the pattern titles

CORRECT — 仅提取模式标题

oodle logs index-patterns -o json | jq '.[].title'

CORRECT — use a discovered pattern in a log query

CORRECT — 在日志查询中使用已发现的模式

oodle logs index-patterns -o json | jq '.[].title'

Then use the title in your NDJSON file:

然后在你的NDJSON文件中使用该标题：

{"index": "oodle_internal_dev_logs"}

{"query": {"match_all": {}}, "size": 10}

undefined

undefined

Log query

日志查询

Search log data using the OpenSearch-compatible multi-search API. The request body uses NDJSON format with exactly two JSON lines: the first selects the index, the second contains the search query using OpenSearch Query DSL. Pass the body via

-f <file>

.

Important constraints:

The CLI only supports a single search body (exactly 2 NDJSON lines: one header + one search). Multiple search pairs are not supported.
Use
```
--start
```
and
```
--end
```
flags for time range filtering. Values can be epoch milliseconds (e.g.,
```
1716825600000
```
),
```
now
```
, or relative expressions (e.g.,
```
-1h
```
,
```
-24h
```
,
```
-7d
```
).
--start
defaults to
-1h
and
--end
defaults to
now
. If you are searching for data older than 1 hour, you must pass an explicit
```
--start
```
or the query will silently return 0 results.
Do not put range filters on
```
timestamp
```
in the query body — the CLI auto-injects a
```
timestamp
```
range filter from
```
--start
```
/
```
--end
```
.

bash

undefined

使用兼容OpenSearch的多搜索API搜索日志数据。请求体采用NDJSON格式，恰好包含两行JSON：第一行选择索引，第二行包含使用OpenSearch Query DSL编写的搜索查询。通过

-f <file>

参数传入请求体。

重要约束：

CLI仅支持单个搜索体（恰好2行NDJSON：一个头部 + 一个搜索语句）。不支持多组搜索对。
使用
```
--start
```
和
```
--end
```
标志进行时间范围过滤。值可以是纪元毫秒数（例如：
```
1716825600000
```
）、
```
now
```
，或相对表达式（例如：
```
-1h
```
、
```
-24h
```
、
```
-7d
```
）。
--start
默认值为
-1h
，
--end
默认值为
now
。如果你要搜索早于1小时的数据，必须显式传入
```
--start
```
参数，否则查询将静默返回0条结果。
不要在查询体中对
```
timestamp
```
添加范围过滤器——CLI会自动从
```
--start
```
/
```
--end
```
参数注入
```
timestamp
```
范围过滤器。

bash

undefined

CORRECT — basic query (searches last 1 hour by default)

CORRECT — 基础查询（默认搜索最近1小时）

cat > query.ndjson <<'EOF' {"index": "logs-*"} {"query": {"match_all": {}}, "size": 10} EOF oodle logs query -f query.ndjson -o json

CORRECT — search for specific log messages with explicit time range

CORRECT — 使用显式时间范围搜索特定日志消息

cat > query.ndjson <<'EOF' {"index": "logs-*"} {"query": {"bool": {"must": [{"match_phrase": {"message": "error"}}]}}, "size": 50, "sort": [{"timestamp": {"order": "desc"}}]} EOF oodle logs query -f query.ndjson --start -6h --end now -o json

CORRECT — search older data using relative time

CORRECT — 使用相对时间搜索更早的数据

cat > query.ndjson <<'EOF' {"index": "logs-*"} {"query": {"bool": {"must": [{"match_phrase": {"message": "OOMKilled"}}]}}, "size": 100} EOF oodle logs query -f query.ndjson --start -7d --end -6d -o json

CORRECT — search older data using epoch milliseconds

CORRECT — 使用纪元毫秒数搜索更早的数据

cat > query.ndjson <<'EOF' {"index": "logs-*"} {"query": {"match_phrase": {"message": "connection refused"}}, "size": 50} EOF oodle logs query -f query.ndjson --start 1716825600000 --end 1716912000000 -o json

WRONG — omitting --start when searching for data older than 1 hour

WRONG — 搜索早于1小时的数据时省略--start参数

cat > query.ndjson <<'EOF' {"index": "logs-*"} {"query": {"match_phrase": {"message": "yesterday's deploy error"}}, "size": 50} EOF oodle logs query -f query.ndjson -o json

^^^ Returns 0 results! --start defaults to -1h, so older data is excluded.

^^^ 返回0条结果！--start默认值为-1h，因此更早的数据被排除。

FIX: add --start -24h (or whatever range covers the target timeframe)

修复：添加--start -24h（或其他覆盖目标时间范围的参数）

WRONG — putting a range filter on timestamp in the query body

WRONG — 在查询体中对timestamp添加范围过滤器

cat > query.ndjson <<'EOF' {"index": "logs-*"} {"query": {"bool": {"must": [{"range": {"timestamp": {"gte": "now-1h", "lte": "now"}}}]}}, "size": 100} EOF

The CLI already injects a timestamp range from --start/--end. In-query range filters conflict.

CLI已从--start/--end参数注入timestamp范围过滤器。查询体中的范围过滤器会产生冲突。

FIX: use --start and --end flags instead.

修复：改用--start和--end标志。

WRONG — passing the query inline without -f

WRONG — 不使用-f参数直接传入内联查询

oodle logs query --body '{"index":"logs-*"}'

WRONG — using JSON instead of NDJSON format

WRONG — 使用JSON而非NDJSON格式

oodle logs query -f query.json # file must be valid NDJSON (exactly two lines)

undefined

oodle logs query -f query.json # 文件必须是有效的NDJSON（恰好两行）

undefined

Best Practices

最佳实践

Discover index patterns before querying

查询前先发现索引模式

Always run

oodle logs index-patterns

to find the correct index name. Guessing index names may return empty results or errors.

bash

undefined

务必先执行

oodle logs index-patterns

命令找到正确的索引名称。猜测索引名称可能会返回空结果或错误。

bash

undefined

CORRECT — discover first, then query

CORRECT — 先发现，再查询

oodle logs index-patterns -o json | jq '.[].title'

Use the discovered title in your NDJSON file

在你的NDJSON文件中使用已发现的标题

WRONG — guessing index names

WRONG — 猜测索引名称

cat > query.ndjson <<'EOF' {"index": "my-logs"} {"query": {"match_all": {}}, "size": 10} EOF oodle logs query -f query.ndjson -o json

undefined

cat > query.ndjson <<'EOF' {"index": "my-logs"} {"query": {"match_all": {}}, "size": 10} EOF oodle logs query -f query.ndjson -o json

undefined

Always use

--start

and

--end

for time range filtering

始终使用--start和--end进行时间范围过滤

The CLI injects a

timestamp

range filter automatically from

--start

/

--end

. Do not add your own range filter on

timestamp

in the query body — it conflicts with the CLI-injected one.

bash

undefined

CLI会自动从

--start

/

--end

参数注入

timestamp

范围过滤器。不要在查询体中自行添加对

timestamp

的范围过滤器——这会与CLI注入的过滤器冲突。

bash

undefined

CORRECT — use CLI flags for time range

CORRECT — 使用CLI标志设置时间范围

oodle logs query -f query.ndjson --start -24h --end now -o json

CORRECT — use epoch milliseconds for precise ranges

CORRECT — 使用纪元毫秒数设置精确范围

oodle logs query -f query.ndjson --start 1716825600000 --end 1716912000000 -o json

WRONG — relying on the default 1-hour window for older data

WRONG — 依赖默认的1小时窗口搜索更早的数据

oodle logs query -f query.ndjson -o json

^^^ Only searches the last 1 hour. If the data you need is older, you get 0 results.

^^^ 仅搜索最近1小时的数据。如果所需数据更早，将返回0条结果。

WRONG — putting range filters on timestamp in the query body

WRONG — 在查询体中对timestamp添加范围过滤器

{"query": {"bool": {"must": [{"range": {"timestamp": {"gte": "now-6h"}}}]}}}

FIX: remove the range from the query body and use --start -6h instead.

修复：从查询体中移除范围过滤器，改用--start -6h参数。

undefined

undefined

Use

-o json

for log query results

对日志查询结果使用-o json参数

Log query responses contain nested JSON structures. Always use

-o json

and pipe through

jq

for extraction.

bash

undefined

日志查询响应包含嵌套的JSON结构。始终使用

-o json

参数并通过

jq

工具进行提取。

bash

undefined

CORRECT — extract log messages from the response

CORRECT — 从响应中提取日志消息

oodle logs query -f query.ndjson -o json | jq '.responses[].hits.hits[]._source.message'

WRONG — using table output for complex nested log data

WRONG — 对复杂的嵌套日志数据使用表格输出

oodle logs query -f query.ndjson -o table

undefined

oodle logs query -f query.ndjson -o table

undefined

Use index pattern fields to build precise queries

使用索引模式字段构建精确查询

Each index pattern includes a

fields

array with field names and types. Use these to build targeted queries instead of

match_all

.

bash

undefined

每个索引模式包含一个

fields

数组，包含字段名称和类型。使用这些字段构建针对性查询，而非使用

match_all

。

bash

undefined

CORRECT — check available fields first

CORRECT — 先检查可用字段

oodle logs index-patterns -o json | jq '.[0].fields[].name'

Then build a query using confirmed field names

然后使用已确认的字段名称构建查询

undefined

undefined

Failure Handling

故障处理

Error	Cause	Fix
401 Unauthorized	Invalid or missing API key	Run `oodle configure` or set `OODLE_API_KEY`
400 Bad Request	Invalid NDJSON body or Query DSL	Validate the NDJSON file has exactly two lines; check OpenSearch Query DSL syntax
Empty result (not an error)	No matching logs in the index or time range	Widen the time range or check the index name with `oodle logs index-patterns`
0 results for older data	`--start` defaults to `-1h` ; data outside that window is excluded	Pass explicit `--start` for older data, e.g. `--start -24h` or `--start <epoch_ms>`
connection refused	Wrong `OODLE_DEPLOYMENT` URL	Check `OODLE_DEPLOYMENT` env var, ensure no trailing slash
429 Too Many Requests	Rate limited	Add `--retries 3` , back off, reduce query frequency
`required flag "file"`	Missing required flag for log query	Add `-f` flag with path to NDJSON file

错误	原因	修复方案
401 Unauthorized	API密钥无效或缺失	执行 `oodle configure` 或设置 `OODLE_API_KEY` 环境变量
400 Bad Request	NDJSON体或Query DSL无效	验证NDJSON文件恰好包含两行；检查OpenSearch Query DSL语法
空结果（非错误）	索引或时间范围内无匹配日志	扩大时间范围或通过 `oodle logs index-patterns` 检查索引名称
早于1小时的数据返回0条结果	`--start` 默认值为 `-1h` ；超出该窗口的数据被排除	为更早的数据传入显式的 `--start` 参数，例如 `--start -24h` 或 `--start <epoch_ms>`
connection refused	`OODLE_DEPLOYMENT` URL错误	检查 `OODLE_DEPLOYMENT` 环境变量，确保没有尾部斜杠
429 Too Many Requests	触发速率限制	添加 `--retries 3` 参数，重试后退，降低查询频率
`required flag "file"`	日志查询缺少必填标志	添加 `-f` 参数并指定NDJSON文件路径

oodle-logs

Original

Translation

Oodle Logs — Search and Index Pattern Discovery

Oodle Logs — 搜索与索引模式发现

Prerequisites

前提条件

Command Execution Order

命令执行顺序

Quick Reference

快速参考

Common Operations

常见操作

List log index patterns

列出日志索引模式

CORRECT — list all available index patterns

CORRECT — 列出所有可用的索引模式

CORRECT — extract just the pattern titles

CORRECT — 仅提取模式标题

CORRECT — use a discovered pattern in a log query

CORRECT — 在日志查询中使用已发现的模式

Then use the title in your NDJSON file:

然后在你的NDJSON文件中使用该标题：

{"index": "oodle_internal_dev_logs"}

{"index": "oodle_internal_dev_logs"}

{"query": {"match_all": {}}, "size": 10}

{"query": {"match_all": {}}, "size": 10}

Log query

日志查询

CORRECT — basic query (searches last 1 hour by default)

CORRECT — 基础查询（默认搜索最近1小时）

CORRECT — search for specific log messages with explicit time range

CORRECT — 使用显式时间范围搜索特定日志消息

CORRECT — search older data using relative time

CORRECT — 使用相对时间搜索更早的数据

CORRECT — search older data using epoch milliseconds

CORRECT — 使用纪元毫秒数搜索更早的数据

WRONG — omitting --start when searching for data older than 1 hour

WRONG — 搜索早于1小时的数据时省略--start参数

^^^ Returns 0 results! --start defaults to -1h, so older data is excluded.

^^^ 返回0条结果！--start默认值为-1h，因此更早的数据被排除。

FIX: add --start -24h (or whatever range covers the target timeframe)

修复：添加--start -24h（或其他覆盖目标时间范围的参数）

WRONG — putting a range filter on timestamp in the query body

WRONG — 在查询体中对timestamp添加范围过滤器

The CLI already injects a timestamp range from --start/--end. In-query range filters conflict.

CLI已从--start/--end参数注入timestamp范围过滤器。查询体中的范围过滤器会产生冲突。

FIX: use --start and --end flags instead.

修复：改用--start和--end标志。

WRONG — passing the query inline without -f

WRONG — 不使用-f参数直接传入内联查询

WRONG — using JSON instead of NDJSON format

WRONG — 使用JSON而非NDJSON格式

Best Practices

最佳实践

Discover index patterns before querying

查询前先发现索引模式

CORRECT — discover first, then query

CORRECT — 先发现，再查询

Use the discovered title in your NDJSON file

在你的NDJSON文件中使用已发现的标题

WRONG — guessing index names

WRONG — 猜测索引名称

Always use --start and --end for time range filtering

始终使用--start和--end进行时间范围过滤

CORRECT — use CLI flags for time range

CORRECT — 使用CLI标志设置时间范围

CORRECT — use epoch milliseconds for precise ranges

CORRECT — 使用纪元毫秒数设置精确范围

WRONG — relying on the default 1-hour window for older data

WRONG — 依赖默认的1小时窗口搜索更早的数据

^^^ Only searches the last 1 hour. If the data you need is older, you get 0 results.

^^^ 仅搜索最近1小时的数据。如果所需数据更早，将返回0条结果。

WRONG — putting range filters on timestamp in the query body

WRONG — 在查询体中对timestamp添加范围过滤器

FIX: remove the range from the query body and use --start -6h instead.

修复：从查询体中移除范围过滤器，改用--start -6h参数。

Use -o json for log query results

对日志查询结果使用-o json参数

CORRECT — extract log messages from the response

Always use
`--start`
and
`--end`
for time range filtering

Use
`-o json`
for log query results