Skip to content

HTTP API

Lorenzo Mangani edited this page Mar 10, 2023 · 25 revisions


LOGQL HTTP API

qryn API Functions are loosely implemented as documented by the LogQL 2.0 API reference.

LogQL

Alertmanager

  • /api/prom/rules
  • /api/prom/rules/{namespace}
  • /api/prom/rules/{namespace}/{groupName}
  • /api/prom/rules/{namespace}
  • /api/prom/rules/{namespace}/{groupName}
  • /api/prom/rules/{namespace}

Tempo (experimental)

  • /tempo/api/push
  • /api/v2/spans
  • /api/traces/{traceId}
  • /api/search/tags
  • /api/search/tag/{tags}/values

API Detail

/loki/api/v1/push

Method

POST

Content-Type

application/x-protobuf (snappy compressed) or application/json

Data Format

{
  "streams": [
    {
      "stream": {
        "label": "value"
      },
      "values": [
          [ "<unix epoch in nanoseconds>", "<log line>" ],
          [ "<unix epoch in nanoseconds>", "<log line>" ]
      ]
    }
  ]
}

/loki/api/v1/query

Method

GET

URL Query Parameters

  • query : The LogQL query
  • limit : Limit of returned lines
  • time : Nanosecond Unix Epoch evaluation time, Default is Now
  • direction : Determines sort order of logs. Either forward or backward. Default is backward

Response Format

{
  "status": "success",
  "data": {
    "resultType": "stream",
    "result": {
      "stream": {
        "labelKey" : "labelValue",
        ...
      },
      "values": [
        [ 
          "<string: nanosecond unix epoch>",
          "<string: log line>"
        ],
        ...
      ]
    }
  }
}

/loki/api/v1/query_range

Method

GET

URL Query Parameters

  • query : The LogQL query
  • limit : Limit of returned lines
  • start : The start time for the query as a nanosecond Unix epoch. Defaults to one hour ago
  • end : The end time for the query as a nanosecond Unix epoch. Defaults to now
  • step : Resolution step width in either a duration [1s, 5s, 5m etc] or number of seconds
  • direction : Determines sort order of logs. Either forward or backward. Default is backward

Response Format

{
  "status": "success",
  "data": {
    "resultType": "stream",
    "result": {
      "stream": {
        "labelKey" : "labelValue",
        ...
      },
      "values": [
        [ 
          "<string: nanosecond unix epoch>",
          "<string: log line>"
        ],
        ...
      ]
    }
  }
}

/loki/api/v1/label

Method

GET

URL Query Parameters

  • start : The start time for the query as a nanosecond Unix epoch. Defaults to 6 hours ago
  • end : The end time for the query as a nanosecond Unix epoch. Defaults to now

Response Format

{
  "status": "success",
  "data": [
    "labelKey",
    ...
  ]
}

/loki/api/v1/label/name/values

Method

GET

URL Query Parameters

  • name : Replace name in url with labelKey
  • start : The start time for the query as a nanosecond Unix epoch. Defaults to 6 hours ago
  • end : The end time for the query as a nanosecond Unix epoch. Defaults to now

Response Format

{
  "status": "success",
  "data": [
    "labelValue",
    ...
  ]
}

/loki/api/v1/tail

Method

GET

URL Query Parameters

  • query : The LogQL query
  • delay_for : The number of seconds to delay retrieving logs to let slow loggers catch up. Defaults to 0 and cannot be larger than 5
  • limit : Limit of returned lines
  • start : The start time for the query as a nanosecond Unix epoch. Defaults to one hour ago

**Note: ** The Tail API endpoint is a Websocket endpoint. It will stream results in below format.

Response Format (streamed)

{
  "status": "success",
  "data": {
    "resultType": "stream",
    "result": {
      "stream": {
        "labelKey" : "labelValue",
        ...
      },
      "values": [
        [ 
          "<string: nanosecond unix epoch>",
          "<string: log line>"
        ],
        ...
      ]
    }
  }
}

API Examples

INSERT Labels & Logs
curl -i -XPOST -H "Content-Type: application/json" http://localhost:3100/loki/api/v1/push \
     --data '{"streams":[{"labels":"{\"__name__\":\"up\"}","entries":[{"timestamp":"2021-12-26T16:00:06.944Z", "line":"zzz"}]}]}'
QUERY Logs
curl -G -s localhost:3100/loki/api/v1/query_range --data-urlencode 'query={__name__="up"}'
{
    "streams": [
        {
            "labels": "{\"__name__\":\"up\"}",
            "entries": [
                {
                    "timestamp":"1545840006944",
                    "line":"zzz"
                },
                {
                    "timestamp":"1545840006944",
                    "line":"zzz"
                },
                {
                    "timestamp":"1545840006944",
                    "line":"zzz"
                }
            ]
        }
    ]
}
QUERY Labels
# curl localhost:3100/loki/api/v1/label
{"status": "success", "data":["__name__"]}
QUERY Label Values
# curl 'localhost:3100/loki/api/v1/label/__name__/values'
{"status": "success", "data":["up"]}

API Experimental

INSERT Labels & Metrics (experimental)

Both below variations are accepted to insert labeled metrics, or a hybrid of metrics and logs.

curl -i -XPOST -H "Content-Type: application/json" http://localhost:3100/loki/api/v1/push \
     --data '{"streams":[{"labels":"{\"__name__\":\"metric\"}","entries":[{"timestamp":"2021-12-26T16:00:06.944Z", "value":100}]}]}'
curl -i -XPOST -H "Content-Type: application/json" http://localhost:3100/loki/api/v1/push \
     --data '{"streams":[{"labels":"{\"__name__\":\"hybrid\"}","entries":[{"timestamp":"2021-12-26T16:00:06.944Z", "line":"zzz", "value":100}]}]}'
{
    "streams": [
        {
            "labels": "{\"__name__\":\"up\"}",
            "entries": [
                {
                    "timestamp":"1545840006944",
                    "line":"zzz"
                },
                {
                    "timestamp":"1545840006945",
                    "value": 100
                },
                {
                    "timestamp": "1545840006946",
                    "line":"zzz",
                    "value": 100
                }
            ]
        }
    ]
}
Clone this wiki locally