Monasca Log Service APIs

Logs

Accepts logs send from log-agents. Logs are basically raw lines, as collected from physical resources, enriched with dimensions.

POST
/v3.0/logs

Send logs

Accepts multiple logs (i.e. bulk mode). Each log can be enriched with set of dimensions. If necessary some of the dimensions can be specified as global dimensions (that is particularly useful, to make request smaller, if there is a lot of duplicates among each log entry dimensions)

Success

Code

Reason

204 - No Content

Normal response code, everything went as expected (or even better).

Error

Code

Reason

400 - Bad Request

Sent data was malformed.

401 - Unauthorized

User must authenticate before making a request.

403 - Forbidden

Policy does not allow current user to do this operation.

411 - Length Required

Content-Length header was not found in request.

413 - Request Entity Too Large

Sent body is too large to be processed.

422 - Unprocessable Entity

Log property must have message.

422 - Unprocessable Entity

Failed to create an envelope.

503 - Service Unavailable

The server is currently unable to handle the request due to a temporary overload or scheduled maintenance. This will likely be alleviated after some delay.

Request

Name

In

Type

Description

dimensions (Optional)

body

object

Dimensions sent in request body are known as global dimensions. Each dimension applies to each log entry sent in a bulk request. Dimensions are simple map (thus having key-value structure).

New in version 3.0

logs

body

object

Array containing each log entry, sent in bulk request.

New in version 3.0

Example 1: Simple request with single log

{
    "dimensions":{},
    "logs":[
        {
            "message":"msg1",
            "dimensions":{
                "component":"mysql",
                "path":"/var/log/mysql.log"
            }
        }
    ]
}

Example 2: Send multiple logs at once

{
    "dimensions":{},
    "logs":[
        {
            "message":"msg1",
            "dimensions":{
                "component":"mysql",
                "path":"/var/log/mysql.log"
            }
        },
        {
            "message":"msg2",
            "dimensions":{
                "component":"monasca-api",
                "path":"/var/log/monasca/monasca-api.log"
            }
        },
        {
            "message":"msg3",
            "dimensions":{
                "component":"monasca-log-api",
                "path":"/var/log/monasca/monasca-log-api.log"
            }
        }
    ]
}

Example 3: Specify global dimensions for each log entry

{
    "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

No body content is returned on a successful POST

Version

Healthcheck

The Monasca Log API comes with a built-in health check mechanism. It is available in two flavors (simple and complex).

HEAD
/healthcheck

Simple check

The simple check only returns response only if API is up and running. It does not return any data because it is accessible only for `HEAD` requests.

Success

Code

Reason

204 - No Content

API is up and running.

GET
/healthcheck

Complex check

# TODO(trebskit) add note to api-guide about peripheral checks

The complex check not only returns a response with success code if API is up and running but it also verifies if peripheral components are in expected condition.

Success

Code

Reason

200 - OK

API is up and running.

Error

Code

Reason

503 - Service Unavailable

API is running but there are problems with peripheral components.

Deprecated APIs

This section contains the reference for APIs that are depracted in the Monasca Log Service

Log

Accepts just a single log entry sent from log-agent of another client. Can work with logs specified as json (application/json) and text (text/plain)

POST
/v2.0/log/single

Send logs

Accepts single log entry.

Success

Code

Reason

204 - No Content

Normal response code, everything went as expected (or even better).

Error

Code

Reason

422 - Unprocessable Entity

Dimensions are required.

422 - Unprocessable Entity

Application type {type} must be {length} characters or less.

422 - Unprocessable Entity

Dimension name {name} must be 255 characters or less.

422 - Unprocessable Entity

Dimension name {name} cannot start with underscore (_).

422 - Unprocessable Entity

Dimension name {name} may not contain: “> < = { } ( ) ‘ ” , ; &”.

422 - Unprocessable Entity

Dimension name cannot be empty.

422 - Unprocessable Entity

Dimension value {value} must be 255 characters or less.

422 - Unprocessable Entity

Dimension value cannot be empty.

422 - Unprocessable Entity

Log property must have message.

422 - Unprocessable Entity

Failed to create an envelope.

503 - Service Unavailable

The server is currently unable to handle the request due to a temporary overload or scheduled maintenance. This will likely be alleviated after some delay.

Request

Name

In

Type

Description

log_json

body

object

Single log entry specified as application/json

log_text

body

string

Single log entry specified as text/plain

X_Dimensions

header

dict

A dictionary consisting of (key, value) pairs used to uniquely identify a log.

New in version 2.0

X_Application_Type

header

string

A single string value representing the application that has generated given log entry

New in version 2.0

Example 1: Simple request with single log (json)

{
  "message":"Hello World!"
}

Example 2: Simple request with single log (text)

Hello World

Response

No body content is returned on a successful POST