Messages: Insert

Description

Inserts messages.

  • Entity name, source, type, severity, and tag names cannot contain non-printable characters. They are case-insensitive and are converted to lower case when stored.
  • Message text or at least one tag is required, otherwise the message are dropped silently.
  • Message text and message tag values are case-sensitive and are stored as submitted.
  • Field values are trimmed of leading and trailing non-printable characters including tab, line feed, and space.
  • Primary key of the message is composed of type, source, entity, severity, and time. Messages that have the same primary key but different values in other fields, such as message text or tags, are deduplicated by retaining only the last copy.
  • The number of message tags cannot exceed 1024.

Date limits:

  • Minimum time that can be stored in the database is 1970-01-01T00:00:00.000Z, or 0 milliseconds from Unix time.
  • Maximum date that can be stored by the database is 2106-02-07T06:59:59.999Z, or 4294969199999 milliseconds from Unix time.
  • If the date field is not specified, the record is inserted with the current server time.

Request

Method Path Content-Type Header
POST /api/v1/messages/insert application/json

Parameters

None.

Fields

An array of message objects.

Field Type Description
type string Message type.
source string Message source.
entity string [Required] Entity name.
date string ISO 8601 date, for example 2016-05-25T00:15:00Z.
Set to current server time if omitted.
severity string Severity name.
tags object An object containing name=value pairs, for example tags: {"path": "/", "name": "sda"}.
message string Message text.
persist boolean Persist message in the database.
Default: true.
If disabled, the message is only processed by the rule-engine.
  • Reserved fields type and source must be specified as fields, not as tags.
    In case of collision, tags with the same names as reserved fields are discarded.
  • In order for alerts generated by the rule engine to inherit message severity, set severity to 'unknown' on the Logging tab in the rule editor.
  • Messages with timestamps that are more than 1 minute behind or ahead of the current server time are ignored by the rule engine.

Response

Fields

None.

Errors

None.

Example

Request

URI

POST /api/v1/messages/insert

Payload

[
  {
    "entity": "nurswgvml007",
    "type": "application",
    "message": "NURSWGVML007 ssh: error: connect_to localhost port 8881: failed.",
    "severity": "MAJOR",
    "source": "atsd"
  }
]

curl

curl https://atsd_hostname:8443/api/v1/messages/insert \
  --insecure --include --user {username}:{password} \
  --header "Content-Type: application/json" \
  --data @file.json

Additional Examples