Skip to main content
Glama

Query logs

query_logs
Read-only

Search historical logs across pods and restarts in a connected or Ankra hosted store (Loki, Elasticsearch, OpenSearch, VictoriaLogs). get_pod_logs reads one live pod. Use structured filters (namespaces/pods/containers plus a text search) or raw_query for a provider expression (LogQL on Loki, a JSON query-DSL clause on Elasticsearch/OpenSearch, LogsQL on VictoriaLogs). Results are normalized {timestamp, line, labels, fields} entries, newest first by default, truncated to the limit. Every result carries cluster_attribution, because one log store can be shared by several clusters (the Ankra platform clusters ship their platform namespace into the same OpenSearch indices with identical pod names): when the store attributes lines to clusters (a cluster field on Elasticsearch/OpenSearch, a cluster stream label on Loki, stamped by the shipper) the query is scoped to this cluster's value, and lines attributed to other clusters or carrying no attribution are excluded and counted (other_clusters_hits, unattributed_hits; absent when the store cannot count them). cluster_attribution.state is "attributed" (scoped; this cluster's lines exist in the window), "requested_absent" (the store attributes other clusters' lines but none in the window carries this cluster's value - the result is empty and nothing in the store can be attributed to this cluster; report that, never substitute unattributed lines), or "none" (no line in the window carries the field; the result is NOT scoped and, if the store is shared, may include other clusters' lines - say so). Relay the note. On a scoped Loki store raw_query is refused; use the structured filters, which are scoped automatically. On Elasticsearch/OpenSearch each entry's fields object carries the requested extra _source paths (default: level and extra, the platform's structured-attribute container - cluster_id, error, etc.); pass fields to pick different paths. Attributes indexed as flat_object match on exact full leaf values only, via dotted paths in raw_query (e.g. {"match": {"extra.cluster_id": ""}}) - substring search inside attribute values is not supported by the store. total_hits_relation says how to read total_hits: "eq" means it is the exact number of matches, "gte" means the store stopped counting (Elasticsearch and OpenSearch cap at index.max_result_window, 10,000 by default) and total_hits is only a floor - in that case say "at least N", never state it as the exact count. Use this for 'what errored around 14:00', cross-pod correlation, and logs from restarted/deleted pods. group_by="signature" answers 'what errored in this window' without the error text: errors grouped into signatures (container, normalised message, count, first/last seen, sample, history new/recurring/unknown vs the prior 7 days; never call unknown new). counts_are_exact false means counts are floors. Read-only.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "cluster_id": "<cluster_id>"
    },
    "name": "query_logs"
  }
}

Input Schema

NameRequiredDescriptionDefault
endNoRFC3339 window end (default now).
podsNoOnly logs from these pod names.
limitNoMax log lines to return (default 100, max 200).
sinceNoLook-back window, e.g. '15m', '1h', '24h', '7d' (default 1h). Ignored when start is set.
startNoRFC3339 window start, e.g. 2026-01-02T14:00:00Z.
fieldsNoExtra _source paths to return per entry on Elasticsearch/OpenSearch, dotted paths allowed (e.g. 'extra.cluster_id'). Default: level, extra. Ignored on Loki.
searchNoCase-sensitive substring the log line must contain.
sourceNoauto (default): connected, then hosted if absent. Explicit choices never fall back; match queries and labels.
group_byNosignature: group errors into signatures instead of returning lines.
directionNobackward = newest first (default), forward = oldest first.
min_levelNoOnly lines whose severity field is at or above this (default error with group_by, none on a raw_query read). Not with raw_query.
raw_queryNoProvider query expression instead of the structured filters: a LogQL expression on Loki (e.g. {namespace="payments"} |= "timeout"), a JSON query-DSL clause on Elasticsearch/OpenSearch (e.g. {"match_phrase": {"message": "timeout"}}), a LogsQL expression on VictoriaLogs (e.g. _msg:~"timeout" | stats by (kubernetes.pod_name) count()). The time range still applies.
cluster_idYesAnkra cluster id (UUID) the call targets. Discover ids with list_clusters.
containersNoOnly logs from these container names.
namespacesNoOnly logs from these namespaces.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changed
    • changedInput schema / properties / min_level / description
      Previous value: -"Only lines whose severity field is at or above this. With group_by it defaults to error, except on a raw_query read, which gets no default and keeps its own conditions. Not with raw_query."New value: +"Only lines whose severity field is at or above this (default error with group_by, none on a raw_query read). Not with raw_query."
  2. Changed1 schema field changed
    • changedInput schema / properties / min_level / description
      Previous value: -"Only lines whose severity field is at or above this (default error with group_by). Not with raw_query."New value: +"Only lines whose severity field is at or above this. With group_by it defaults to error, except on a raw_query read, which gets no default and keeps its own conditions. Not with raw_query."
  3. Changed2 schema fields changed
    • addedInput schema / properties / group_by
      Added value: +{
      +  "description": "signature: group errors into signatures instead of returning lines.",
      +  "enum": [
      +    "signature"
      +  ],
      +  "type": "string"
      +}
    • addedInput schema / properties / min_level
      Added value: +{
      +  "description": "Only lines whose severity field is at or above this (default error with group_by). Not with raw_query.",
      +  "enum": [
      +    "warning",
      +    "error",
      +    "critical"
      +  ],
      +  "type": "string"
      +}
  4. Changed1 schema field changed
    • addedInput schema / properties / source
      Added value: +{
      +  "description": "auto (default): connected, then hosted if absent. Explicit choices never fall back; match queries and labels.",
      +  "enum": [
      +    "auto",
      +    "connected",
      +    "ankra_hosted"
      +  ],
      +  "type": "string"
      +}
  5. First observed

TDQS

A4.7/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

The only annotation is readOnlyHint=true, and the description goes far beyond it: cluster_attribution states and their consequences, exclusion and counting of other-cluster/unattributed hits, total_hits_relation semantics with the 10,000 Elasticsearch cap, counts_are_exact floors, and default ordering/truncation. It explicitly confirms "Read-only", so there is no conflict with the annotation.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness3/5

Is the description appropriately sized, front-loaded, and free of redundancy?

It is front-loaded with purpose and the get_pod_logs disambiguation, and nearly every clause carries real information. However, the bulk is a single dense run-on paragraph where cluster_attribution, total_hits_relation, and group_by semantics are interleaved, making it hard to scan for the parameter an agent actually needs.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With 15 parameters and no output schema, the description supplies the missing return shape ({timestamp, line, labels, fields}), the fields default on Elasticsearch/OpenSearch, the meaning of total_hits_relation, and the cluster_attribution envelope. An agent has everything needed to call it and to report results honestly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the baseline is 3; the description earns extra credit by explaining store-level behavior the schema cannot, such as flat_object attributes matching only exact full leaf values via dotted paths and no substring search inside attribute values. It also clarifies group_by="signature" output semantics (signature fields, 7-day history, and that unknown must never be called new). Most other parameter detail duplicates the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The first two sentences give a specific verb and resource ("Search historical logs across pods and restarts in a connected or Ankra hosted store") and immediately name the sibling it is not ("get_pod_logs reads one live pod"). It also enumerates the supported backends, so an agent can tell it apart from the pod-level tools without opening a schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

It states concrete usage scenarios ("what errored around 14:00", cross-pod correlation, logs from restarted/deleted pods) and routes between the two query modes by naming the conditions (structured filters when the Loki store is scoped, raw_query otherwise). It also spells out an exclusion — raw_query is refused on a scoped Loki store — and warns never to substitute unattributed lines.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Try in Browser

Glama MCP Gateway

Add one secure layer between your agents and this server.