Sign in
Logs

Ask about logs

Changed on

Answer a natural-language question about one project's stored logs. Returns a plain-language answer, what was measured over which window (explanation, window), how exact and complete the numbers are (meta), and a queryId. An overview (what is broken, recent errors, what changed, what is new, with no specific topic, field or request for lines) is searched: its results are the window's kinds of log lines, with their counts in the window and the window before and example lines; every other question is measured exactly. A question may be asked in any language, and is answered in it. The period it names is read from it, on the clock of timeZone ("the last 6 hours", "this afternoon", "since midnight", "between 18:00 and 19:00", "this hour against the previous hour", which reads both hours and compares them); a window replaces that period, and the answer says so. A period that cannot be read is said to be, and the last hour is read instead. With results: true it also returns the rows, value, table, series or kinds of log lines the answer was written from. Pass the queryId to logs.executeQuery to run the same query again over any window with no model involved. When nothing matches, status is not_found: the answer names the window that was read, interpretedAs how the question was read, and the queryId runs the same query over a wider window. A question that asks nothing about the project's logs, or about another project's, is refused with nothing searched (status error, rejection.code not_about_logs or other_project, no queryId), and one no query can answer as asked is refused as unsupported_question; one that asks to change or delete logs is answered with the lines it names (writeDeclined), since logs are read-only.

post/logs/ask

Request

  • Base URL: https://api.sazabi.com/v1
  • URL: https://api.sazabi.com/v1/logs/ask
  • Auth: none declared

Request body

projectIdstring uuid

Project to ask about. Auto-filled from CLI and SDK context when omitted.

questionstring required

Natural-language question about the project's stored logs, at most 2,000 characters.

timeZonestring

The asker's IANA time zone, such as America/Los_Angeles. Calendar periods the question names ("this afternoon", "since midnight", "yesterday") are read on its clock, and the answer names times in it. Defaults to UTC; a time zone the question names ("since midnight UTC") wins. The CLI sends its local time zone.

limitinteger

Maximum rows, groups, points or kinds in results (1-5,000). It only pages results: the answer, and each result's matched and total, are computed over every matching line whatever the limit. Rows are the newest (or earliest) matching lines, up to this many; tables, series and top messages are cut to this many of the groups or points the question asks for (its top 20, or the top N it names); a search's results show at most 50 kinds of log lines. truncated says when more matched than results shows.

resultsboolean

Also return the rows, table, series or kinds of log lines the answer was written from. Defaults to false.

Response

OK

queryIdstring uuid

Id of this query. Pass it to logs.executeQuery to run the same query again with no model involved, a not_found answer's included (over a wider window, say). Absent only when nothing was planned (a refused question, or an error before any query), so there is nothing to run again.

parentIdstring uuid

With logs.executeQuery by queryId only: the queryId that was run. Absent when a spec was run.

status'ok' | 'not_found' | 'partial' | 'error' required

ok answered; partial answered in part: for part of the window, or without a detail the logs do not record, such as request status codes (the answer says which); not_found the query ran and nothing matched in window, for the question as read (interpretedAs); error the question could not be answered, or was refused (rejection).

answerstring

The plain-language answer. Present on every logs.ask reply.

explanationstring required

What was measured, over which window, in plain words.

interpretedAsstring

How the question was read, so it can be rephrased.

writeDeclinedunknown

Changes

  • d38ac5e79789Revision changes
    • ▲

      removed the required property from the response with the status

    • ○

      added the new optional request property

    • ○

      added the optional property // to the response with the status

    • ○

      added the optional property to the response with the status

    • ○

      added the optional property to the response with the status

    • ○

      added the optional property to the response with the status

    • ○

      added subschema #2 subschema #3 subschema #4 subschema #5 subschema #6 subschema #7 to the response property anyOf list for the response status

    • ○

      removed subschema #2 subschema #3 subschema #4 subschema #5 subschema #6 subschema #7 from the response property anyOf list for the response status

  • 947411a2cffdRevision changes
    • ○

      added subschema #1 to the response property anyOf list for the response status