openstack
/
monasca-log-api
Code Issues Proposed changes
monasca-log-api/documentation/monasca-log-api-spec.md

9.7 KiB
Raw Permalink Blame History

Monasca Log API

Date: May 27, 2016

Document Version: v2.2.2

Logs

The logs resource allows logs to be created and queried.

Create Logs

Create logs.

POST /v3.0/logs

Headers

  • X-Auth-Token (string, required) - Keystone auth token
  • Content-Type (string, required) - application/json

Path Parameters

None.

Query Parameters

  • tenant_id (string, optional, restricted) - Tenant ID to create log on behalf of. Usage of this query parameter requires the monitoring-delegate role.

Request Body

JSON object which can have a maximum size of 5 MB. It consists of global dimensions (optional) and array of logs. Each single log message with resulting envelope can have a maximum size of 1 MB. Dimensions is a dictionary of key-value pairs and should be consistent with metric dimensions.

Logs is an array of JSON objects describing the log entries. Every log object can have individual set of dimensions which has higher precedence than global ones. It should be noted that dimensions presented in each log record are also optional.

If both global (at the root level) and local (at log entry level)
dimensions would be present, they will be merged into one dictionary.
Please note that local dimensions are logically considered as more
specific thus in case of conflict (i.e. having two entries with the same
key in both global and local dimensions) local dimensions take
precedence over global dimensions.

Request Examples

POST logs

POST /v3.0/logs HTTP/1.1
Host: 192.168.10.4:5607
Content-Type: application/json
X-Auth-Token: 27feed73a0ce4138934e30d619b415b0
Cache-Control: no-cache

{
    "dimensions":{
        "hostname":"mini-mon",
        "service":"monitoring"
    },
    "logs":[
        {
            "message":"msg1",
            "dimensions":{
                "component":"mysql",
                "path":"/var/log/mysql.log"
            }
        },
        {
            "message":"msg2",
            "dimensions":{
                "component":"monasca-api",
                "path":"/var/log/monasca/monasca-api.log"
            }
        }
    ]
}

Response

Status Code

  • 204 - No content

Response Body

This request does not return a response body.

List logs

Get precise log listing filtered by dimensions.

Note that this API is in development, and is not currently implemented.

This interface can used to obtain log entries for a time range, based on matching a set of exact dimension values. By default, entries will be returned in descending timestamp order (newest first). The log entries returned by this API will not necessarily be identical to those POST-ed to the service, as the data returned will have been subjected to deployment-specific transformation stages (i.e. the "monasca-log-transform" service).

GET /v3.0/logs

Headers

  • X-Auth-Token (string, required) - Keystone auth token
  • Accept (string) - application/json

Path Parameters

None.

Query Parameters

  • tenant_id (string, optional, restricted) - Tenant ID from which to get logs from. This parameter can be used to get logs from a tenant other than the tenant the request auth token is scoped to. Usage of this query parameter is restricted to users with the monasca admin role, as defined in the monasca-log-api configuration file, which defaults to monasca-admin.
  • dimensions (string, optional) - A dictionary to filter logs by specified as a comma separated array of (key, value) pairs as key1:value1,key2:value2, ..., multiple values for a key may be specified as key1:value1|value2|...,key2:value4,.... If the value is omitted in the form key1,key2, ..., then entries are returned where the dimension exists with any value.
  • start_time (string, optional) - The start time in ISO 8601 combined date and time format in UTC.
  • end_time (string, optional) - The end time in ISO 8601 combined date and time format in UTC.
  • offset (integer, optional) - Number of log entries to skip (Default: 0).
  • limit (integer, optional) - Limit number of logs returned (Default: 10).
  • sort_by (string, optional) - Comma separated list of fields or dimensions to sort by. Fields may be followed by 'asc' or 'desc' to set the direction, e.g. 'timestamp asc'. Allowed fields for sort_by are currently: 'timestamp'. (Default: no sorting)

Request Body

None.

Request Examples

GET /v3.0/logs?dimensions=hostname:devstack&start_time=2015-03-00T00:00:01Z HTTP/1.1
Host: 192.168.10.4:5607
Content-Type: application/json
X-Auth-Token: 2b8882ba2ec44295bf300aecb2caa4f7
Cache-Control: no-cache

Response

Status Code

  • 200 - OK

Response Body

Returns a JSON object with a 'links' array of links and an 'elements' array of log entry objects with the following fields:

  • timestamp (timestamp) - The originating time in ISO 8601 combined date and time format in UTC, with millisecond resolution if available.
  • message (string) - The contents of the log message.
  • dimensions ({string(255): string(255)}) - Dimensions of the log, either supplied with the log or added by transformation.

Response Examples

{
    "links": [
        {
            "rel": "prev",
            "href": "http://192.168.10.4:5607/v3.0/logs?start_time=2015-03-00T00%3A00%3A00Z&dimensions=hostname%3Adevstack"
        },
        {
            "rel": "self",
            "href": "http://192.168.10.4:5607/v3.0/logs?offset=10&start_time=2015-03-00T00%3A00%3A00Z&dimensions=hostname%3Adevstack"
        },
        {
            "rel": "next",
            "href": "http://192.168.10.4:5607/v3.0/logs?offset=20&start_time=2015-03-00T00%3A00%3A00Z&dimensions=hostname%3Adevstack"
        }
    ],
    "elements": [
        {
            "timestamp":"2015-03-03T05:24:55.202Z",
            "message":"msg1",
            "dimensions":{
                "hostname":"devstack",
                "component":"mysql",
                "path":"/var/log/mysql.log"
            }
        },
        {
            "timestamp":"2015-03-01T02:22:09.112Z",
            "message":"msg2",
            "dimensions":{
                "hostname":"devstack",
                "component":"monasca-api",
                "path":"/var/log/monasca/monasca-api.log"
            }
        }
    ]
}

Healthcheck

Note that following part is updated for Python implementation.

The Monasca Log API comes with a built-in health check mechanism. It is available in two flavors, both accessible under /healthcheck endpoint.

Complex check

The complex check not only returns a response with success code if Monasca Log API is up and running but it also verifies if peripheral components, such as Kafka, are healthy too.

Monasca Log API will respond with following codes:

  • 200 - both API and external components are healthy.
  • 503 - API is running but problems with peripheral components have been spotted.

Example: curl -XGET 192.168.10.4:5607/healthcheck

Peripheral checks

  • Kafka is considered healthy if connection to broker can be established and configured topics can be found.

Simple check

The simple check only returns response only if Monasca Log API is up and running. It does not return any data because it is accessible only for HEAD requests. If the Monasca Log API is running the following response code: 204 is expected.

Example: curl -XHEAD 192.168.10.4:5607/healthcheck

=======

POST /v2.0/log/single (deprecated)

Headers

  • X-Auth-Token (string, required) - Keystone auth token
  • Content-Type (string, required) - application/json; text/plain
  • X-Application-Type (string(255), optional) - Type of application
  • X-Dimensions ({string(255):string(255)}, required) - A dictionary consisting of (key, value) pairs used to structure logs.

Path Parameters

None.

Query Parameters

  • tenant_id (string, optional, restricted) - Tenant ID to create log on behalf of. Usage of this query parameter requires the monitoring-delegate role.

Request Body

Consists of a single plain text message or a JSON object which can have a maximum length of 1048576 characters.

Request Examples

Plain text log - single line

POST a single line of plain text log.

POST /v2.0/log/single HTTP/1.1
Host: 192.168.10.4:5607
Content-Type: text/plain
X-Auth-Token: 27feed73a0ce4138934e30d619b415b0
X-Application-Type: apache
X-Dimensions: applicationname:WebServer01,environment:production
Cache-Control: no-cache

Hello World
Plain text log - multi lines

POST a multiple lines of plain text log.

POST /v2.0/log/single HTTP/1.1
Host: 192.168.10.4:5607
Content-Type: text/plain
X-Auth-Token: 27feed73a0ce4138934e30d619b415b0
X-Application-Type: apache
X-Dimensions: applicationname:WebServer01,environment:production
Cache-Control: no-cache

Hello\nWorld
JSON log

POST a JSON log

POST /v2.0/log/single HTTP/1.1
Host: 192.168.10.4:5607
Content-Type: application/json
X-Auth-Token: 27feed73a0ce4138934e30d619b415b0
X-Application-Type: apache
X-Dimensions: applicationname:WebServer01,environment:production
Cache-Control: no-cache

{
  "message":"Hello World!",
  "from":"hoover"
}

Response

Status Code

  • 204 - No content

Response Body

This request does not return a response body.

# Copyright 2016-2017 FUJITSU LIMITED
#
# Licensed under the Apache License, Version 2.0 (the "License"); you may
# not use this file except in compliance with the License. You may obtain
# a copy of the License at
#
#      http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
# WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
# License for the specific language governing permissions and limitations
# under the License.