oodle-ai/agent-skills

oodle-logs

Search, query, and aggregate log data using OpenSearch Query DSL, and discover available log index patterns.

Quelltext ansehen

Verwendung

  1. Installationsbefehl kopieren und das Quellpaket vor der Installation in der eigenen Agentenumgebung prüfen.
  2. Benötigte Werkzeuge, Zugangsdaten und Hosts im Original prüfen.
  3. Eingabe und gewünschtes Ergebnis beschreiben und die Ausgabe mit den Quellen abgleichen.
npx skills add https://github.com/oodle-ai/agent-skills --skill oodle-logs

Vor dem Start

  • Die Installation umfasst weder Modellabo noch API-Kontingent oder Dateizugriffsrechte.
  • Sterne und Installationen zeigen Aktivität, keine unabhängige Qualitäts- oder Sicherheitsprüfung.
Originales Skill-Dokument

Aus dem Quell-Repository gerendert; Überschriften, Beispiele, Code, Tabellen, Links und Bilder bleiben erhalten.

Oodle Logs — Search and Index Pattern Discovery

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

Prerequisites

bash
brew install oodle-ai/oodle/oodle
oodle configure

Confirm the logs endpoint works:

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

Command Execution Order

Before running any log query:

  1. Run oodle logs index-patterns -o json to discover available log index patterns.
  2. Pick the appropriate index pattern title for your query.
  3. Build the NDJSON query file using the discovered index pattern and OpenSearch Query DSL.
  4. Set --start and --end to cover the time range you need, 3 days or less (see "Query Cost"). They default to -1h and now.
  5. Do not guess index names — always confirm with index-patterns first.

Query Cost

A log query has a server time limit. A slow query also slows log queries for other users, and a query that times out returns nothing. Write every query so that it reads as few log lines as possible:

  1. Search text in `message`. message is indexed for word search, so a match_phrase on message reads only the parts of the logs that hold the words. The search matches whole words: for finds "blocked for 5s" but not "for180seconds", so no match does not prove that part of a word is absent. To match part of a word, use a wildcard (rule 5): {"query_string": {"query": "message:*for*"}}. A wildcard on message reads the whole message field of every line, so use a window of a few hours.
  2. Queries on `raw_log` are slow. raw_log is not indexed, so a search on it reads every log line in the time range. Search message first. Search raw_log only when message does not hold the text. Then:
  • use a window of a few hours, not days;
  • put the raw_log search in its own query. In a bool should clause next to a message search, the raw_log search makes the message search read every line too, so the whole query is as slow as a raw_log search.
  1. Query JSON fields by subfield. A JSON field holds nested values, for example a field log with the subfields log.level and log.session_id. Check the field names with oodle logs index-patterns.
  • Do not filter on the JSON field itself (log). That reads the whole field of every line. Query a subfield (log.level).
  • On a subfield, a match_phrase or query_string term without .keyword is a contains search. It reads the whole JSON field of every line and can time out over a few hours. For an exact value, such as an ID, use the .keyword form: {"term": {"log.session_id.keyword": "<id>"}}.
  • For part of a value in a subfield, use a .keyword wildcard (rule 5). It reads only that subfield, not the whole JSON field.
  • To find text inside log lines, such as an ID in the log message, search message, not a subfield such as log.message. Do not add a log.message term for the same text.
  1. Use `.keyword` for exact values, such as an ID or a service name: {"term": {"service.keyword": "checkout"}}. Without .keyword, the match is a substring search.
  2. Put wildcards in a `query_string` clause. ? matches one character and * matches zero or more characters.
  • Write them outside quotes. Inside quotes, and in a term clause, * is a literal character. wildcard, prefix and regexp clauses are not supported.
  • On a .keyword field, the pattern must match the whole value, and case matters: log.logger.keyword:uvicorn* finds uvicorn.error, and log.file.keyword:*server.py finds /app/server.py. This is the fast way to match part of a JSON subfield value.
  • Use a .keyword wildcard also for "starts with" or "ends with" on any field: container_name.keyword:payment* finds payment-api but not legacy-payment. Without .keyword, container_name:payment* is a contains search and finds both.
  1. Use windows of 3 days or less. Start with the shortest window that can hold the answer. For a longer period, split it into windows of 3 days or less, and stop when you have found what you need.
  2. Run log queries one at a time. Do not run log queries in parallel.
  3. Count with `aggs` and `"size": 0` when you need numbers, not log lines.
  4. When a query times out, make it narrower. Do not run it again unchanged. Use a shorter window, message instead of raw_log, a JSON subfield instead of the whole JSON field, .keyword for exact values, and a .keyword wildcard for part of a value. The CLI prints this hint on stderr when a query times out.
bash
# CORRECT — phrase search on the indexed message field, over one day
cat > query.ndjson <<'EOF'
{"index": "logs-*"}
{"query": {"bool": {"filter": [{"match_phrase": {"message": "still behind after the maximum wait"}}, {"term": {"environment.keyword": "production"}}]}}, "size": 100}
EOF
oodle logs query -f query.ndjson --start -24h --end now -o json

# CORRECT — message has no match: search raw_log alone, over a few hours
cat > query.ndjson <<'EOF'
{"index": "logs-*"}
{"query": {"match_phrase": {"raw_log": "still behind after the maximum wait"}}, "size": 100}
EOF
oodle logs query -f query.ndjson --start -4h --end now -o json

# WRONG — message OR raw_log over 7 days: the query reads every line in 7 days and times out
cat > query.ndjson <<'EOF'
{"index": "logs-*"}
{"query": {"bool": {"minimum_should_match": 1, "should": [{"match_phrase": {"message": "still behind after the maximum wait"}}, {"match_phrase": {"raw_log": "still behind after the maximum wait"}}]}}, "size": 500}
EOF
oodle logs query -f query.ndjson --start -7d --end now -o json
# FIX: search message alone, in windows of 3 days or less. If message has no match, search raw_log in a separate query over a few hours.

# CORRECT — exact ID in a JSON subfield: the .keyword form reads only that subfield
cat > query.ndjson <<'EOF'
{"index": "logs-*"}
{"query": {"term": {"log.session_id.keyword": "0b7e5c2a-1f3d-4a8e-9c6b-2d4f8a1e7b90"}}, "size": 100}
EOF
oodle logs query -f query.ndjson --start -24h --end now -o json

# WRONG — the same ID as a contains search on the subfield: reads the whole JSON field of every line
cat > query.ndjson <<'EOF'
{"index": "logs-*"}
{"query": {"match_phrase": {"log.session_id": "0b7e5c2a-1f3d-4a8e-9c6b-2d4f8a1e7b90"}}, "size": 100}
EOF
# FIX: use {"term": {"log.session_id.keyword": "<id>"}}. To find the ID anywhere in the log text, search message instead.

# CORRECT — part of a JSON subfield value: a .keyword wildcard in query_string reads only that subfield
cat > query.ndjson <<'EOF'
{"index": "logs-*"}
{"query": {"query_string": {"query": "log.logger.keyword:uvicorn*"}}, "size": 100}
EOF
oodle logs query -f query.ndjson --start -24h --end now -o json

# WRONG — the same search as a contains search on the subfield: reads the whole JSON field of every line
{"query": {"match_phrase": {"log.logger": "uvicorn"}}}
# FIX: use {"query_string": {"query": "log.logger.keyword:uvicorn*"}}. Use *uvicorn* if the text can be in the middle of the value.

# WRONG — a wildcard inside quotes or in a term clause: * is a literal character, so nothing matches
{"query": {"query_string": {"query": "log.logger.keyword:\"uvicorn*\""}}}
{"query": {"term": {"log.logger.keyword": "uvicorn*"}}}
# FIX: write the wildcard in query_string, outside quotes.

# WRONG — filtering on the whole JSON field
{"query": {"match_phrase": {"log": "timeout"}}}
# FIX: query a subfield such as log.error, or search message for text.

# WRONG — log queries in parallel
oodle logs query -f week1.ndjson --start -7d --end -6d -o json &
oodle logs query -f week2.ndjson --start -14d --end -13d -o json &
wait
# FIX: run the queries one after the other, and stop when you have the answer.

Quick Reference

TaskCommand
List log index patternsoodle logs index-patterns -o json
Search logsoodle 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
# CORRECT — list all available index patterns
oodle logs index-patterns -o json

# CORRECT — extract just the pattern titles
oodle logs index-patterns -o json | jq '.[].title'

# CORRECT — use a discovered pattern in a log query
oodle logs index-patterns -o json | jq '.[].title'
# Then use the title in your NDJSON file:
# {"index": "logs-*"}
# {"query": {"match_all": {}}, "size": 10}

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), RFC 3339 (e.g., 2026-01-02T00:00:00Z), 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
# CORRECT — basic query (searches last 1 hour by default)
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
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
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
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
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.
# FIX: add --start -24h (or whatever range covers the target timeframe)

# WRONG — putting a range filter on timestamp in the query body
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.
# FIX: use --start and --end flags instead.

# WRONG — passing the query inline without -f
oodle logs query --body '{"index":"logs-*"}'

# WRONG — using JSON instead of NDJSON format
oodle logs query -f query.json   # file must be valid NDJSON (exactly two lines)

Aggregations

Put OpenSearch aggregations in an aggs block. Set "size": 0 when you need only the aggregation. Read the result with jq '.responses[0].aggregations'. The field names below are examples; confirm them with oodle logs index-patterns. Numeric aggregations need a numeric field, not text inside message.

bash
# CORRECT — error lines per service (top 20)
cat > query.ndjson <<'EOF'
{"index": "logs-*"}
{"size": 0, "query": {"term": {"level": "error"}}, "aggs": {"by_service": {"terms": {"field": "service_name", "size": 20}}}}
EOF
oodle logs query -f query.ndjson --start -24h --end now -o json \
  | jq -r '.responses[0].aggregations.by_service.buckets[] | "\(.key)\t\(.doc_count)"'

# CORRECT — error lines per hour
cat > query.ndjson <<'EOF'
{"index": "logs-*"}
{"size": 0, "query": {"match_phrase": {"message": "error"}}, "aggs": {"per_hour": {"date_histogram": {"field": "timestamp", "fixed_interval": "1h"}}}}
EOF
oodle logs query -f query.ndjson --start -24h --end now -o json \
  | jq -r '.responses[0].aggregations.per_hour.buckets[] | "\(.key_as_string)\t\(.doc_count)"'

Values inside plain-text log lines

regexp queries, scripts, and runtime fields are not supported. So a log query cannot filter on, or group by, a value that is only inside the text of a plain-text line. For lines like tool Bash ok in 12345 ms, a query cannot select "more than 10000 ms" or group by the tool name. Do not tell the user that Oodle cannot do it. Offer one of these:

  1. Log metrics rule (oodle-log-metrics skill): extracts the value with a regex into a metric with labels. Use it for counts, latency, and alerts on new logs.
  2. Past data: find the lines with match_phrase, and extract the value on the client with jq.
NeedUse
Find lines, read events, investigate the pastoodle logs query
Count or group by a real field, over the pastoodle logs query with aggs
Filter or group by a value only inside plain textLog metrics rule (new data), or jq on the client (past data)
Alert on log lines (count, rate, latency, per user)Log metrics rule + monitor
Trend over weeks on a dashboardLog metrics rule

Worked example: whose credit ran out in the last 24 hours?

First check if a log metrics rule already counts these lines: oodle log-metrics list -o json. If one does, read its metric, for example oodle metrics query --query 'sum by (user) (increase(oodle_logs_credit_exhausted[24h])) > 0' -o json. A rule counts only lines that arrived after it was made, so use the logs below for older data.

bash
cat > credit.ndjson <<'EOF'
{"index": "logs-*"}
{"query": {"match_phrase": {"message": "credit exhausted"}}, "size": 1000, "sort": [{"timestamp": {"order": "desc"}}]}
EOF

# If the user is a real field (for example user_id): use a terms aggregation on it.
# If the user is only inside the text ("... for user=alice ..."): extract it on the client.
oodle logs query -f credit.ndjson --start -24h --end now -o json \
  | jq -r '.responses[0].hits.hits[]._source.message | capture("user=(?<user>[^ ]+)").user' \
  | sort | uniq -c | sort -rn

If the query returns size lines, there can be more: split the time range (for example, four 6-hour queries) and combine the results. To alert per user from now on, create a log metrics rule that extracts user with the regex user=(\S+), and a monitor on sum by (user) (increase(oodle_logs_credit_exhausted[10m])). The oodle-log-metrics skill has the rule JSON.

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
# CORRECT — discover first, then query
oodle logs index-patterns -o json | jq '.[].title'
# Use the discovered title in your NDJSON file

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

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

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
# CORRECT — use CLI flags for time range
oodle logs query -f query.ndjson --start -24h --end now -o json

# CORRECT — use epoch milliseconds for precise ranges
oodle logs query -f query.ndjson --start 1716825600000 --end 1716912000000 -o json

# WRONG — relying on the default 1-hour window for older data
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.

# WRONG — putting range filters on timestamp in the query body
{"query": {"bool": {"must": [{"range": {"timestamp": {"gte": "now-6h"}}}]}}}
# FIX: remove the range from the query body and use --start -6h instead.

Use -o json for log query results

Log query responses contain nested JSON structures. Always use -o json and pipe through jq for extraction.

bash
# CORRECT — extract log messages from the response
oodle logs query -f query.ndjson -o json | jq '.responses[].hits.hits[]._source.message'

# WRONG — using table output for complex nested log data
oodle logs query -f query.ndjson -o table

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
# CORRECT — check available fields first
oodle logs index-patterns -o json | jq '.[0].fields[].name'
# Then build a query using confirmed field names

Failure Handling

ErrorCauseFix
401 UnauthorizedInvalid or missing API keyRun oodle configure or set OODLE_API_KEY
400 Bad RequestInvalid NDJSON body or Query DSLValidate 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 rangeWiden 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 excludedPass explicit --start for older data, e.g. --start -24h or --start <epoch_ms>
connection refusedWrong OODLE_DEPLOYMENT URLCheck OODLE_DEPLOYMENT env var, ensure no trailing slash
429 Too Many RequestsRate limitedAdd --retries 3, back off, reduce query frequency
Timeout exceeded or TIMEOUT_EXCEEDED in responses[].errorThe query read too many log lines before the server time limitDo not run it again unchanged. Use a shorter window, search message instead of raw_log, query a JSON subfield instead of the whole JSON field, use .keyword for exact values, and run queries one at a time (see "Query Cost")
400 on regexp, script, or runtime fieldNot supportedUse match_phrase, or a log metrics rule (see "Values inside plain-text log lines")
required flag(s) "file" not setMissing required flag for log queryAdd -f flag with path to NDJSON file

References

aus demselben Repository

Weitere Skills

Alle Skills