Axibase Time Series Database

Database Message Functions

Overview

The db_message_count and db_message_last functions retrieve message records from the database and can be used to check the existence of events or to correlate time series and messages.

Reference

db_message_count

db_message_count(string interval, string type, string source
                          [, string tags | map tags
                                    [, string entity[, string expression]]]) long

Returns the number of messages matching the specified interval, message type, message source, tags, entity, and expression. See matching rules below.

Note

End of the selection interval is set to the timestamp of the last command in the window (not current time).

/*
  Returns message count for the same type, source, tags, and entity as in the current message.
  The current message is excluded.
*/
db_message_count('15 minute', type, source, tags, entity)

/*
  Returns message count for the same type, source, and entity as in the current message and specific tags
  The current message is excluded.
*/
db_message_count('15 minute', type, source, ['api_app_id':'583'])

/*
  Returns message count for the same type, source, entity as in the current command and ANY tags.
  The current message is excluded.
*/
db_message_count('12 hour', type, source, null, entity)

db_message_last

db_message_last(string interval, string type, string source
                          [, string tags | map tags
                                    [, string entity[, string expression]]]) Message

Returns the most recent message record for the specified interval, message type, message source, tags, entity, and expression. See Matching Rules.

/*
  Returns the most recent message for the same type, source as in the current window and ANY entity and tags.
  The current message is excluded.
*/
db_message_last('15 minute', type, source)

The record fields can be accessed using dot notation, for example:

db_message_last('1 hour', 'webhook', 'github').timestamp
Name Type Description
entity string Entity name.
type string Message type.
source string Message source.
tags map Message tags.
severity string Message severity code.
timestamp string Record time as Unix time in milliseconds.
message string Message text.
date string null. Use timestamp field instead.

db_messages

db_messages(string interval, string type, string source
                          [, string tags | map tags
                                    [, string entity[, string expression]]]) [Message]

Returns a list of message records matching the specified interval, message type, message source, tags, entity, and expression. See Matching Rules.

If no message is found, an empty [] list is returned.

The messages in the list are sorted by time in the ascending order, with the most recent message at the start of the list.

  • To access the n-th element in the list, use square brackets [index] or get(index) method.
  • To access the first (most recent) record use index 0, for example db_messages('1 hour', type, source)[0].
  • The first (most recent) record can be also retrieved with the db_message_last function.

Fields of the returned Message objects can be accessed using dot notation, for example db_messages('1 hour', 'webhook', '')[0].timestamp.

{
  "entity": "nurswgvml007",
  "type": "backup",
  "source": "rm",
  "severity": "UNDEFINED",
  "tags": {
    "exit_code": "0",
    "source_dir": "/app/backup/dev_axibase/svn"
  },
  "timestamp": 1548991802674,
  "message": "rm complete svn_dev"
}

Message Date

The date field in the message object is null. The record time is stored in the timestamp field as Unix time in milliseconds.

To print all message fields as a table in notifications, use the addTable function:

addTable(msgs, 'markdown')

To print specific messages, iterate through the list manually:

| date | type | source | message |
|--------|------|--------|---------|
@foreach{m : msgs}|@{date_format(m.timestamp, "HH:mm:ss")}|@{m.type}|@{m.source}| @{truncate(m.message, 128)} |
@end{}

Matching Rules

Interval

  • Selection interval is specified in count units, for example, 1 hour.
  • End of the selection interval is set to the timestamp of the last command in the window (not current time). As a result, the current command is excluded from counting.

Type

  • If the message type argument is specified as null or an empty string '', all types are matched.

Source

  • If the message source argument is specified as null or an empty string '', all sources are matched.

Entity

  • If the entity argument is not specified, the current entity in the window is used for matching.
  • If the entity argument is specified as null or empty string '' or * wildcard, all entities are matched.

Tags

  • tags argument can be specified as follows:
    • String containing name=value pairs separated with comma: 'tag1=value1,tag2=value2'.
    • Map: ['tag1':'value1', 'tag2':'value2']
    • The tags field representing the grouping tags of the current window.
  • If tags is specified as null or an empty string '', all tags are matched.
  • To match records with empty tags use 'tags.isEmpty() = true' or 'tags.size() = 0' in expression.
  • tags argument matches records containing the specified tags but can also include other tags.

Expression

  • The expression field can include the following fields and supports wildcards in field values:
    • message
    • type
    • source
    • severity
    • entity
    • tags and tags.{name}

Examples

db_message_count Examples

/* Checks if the average exceeds 20 and the 'compaction' message is not received
within the last hour for the current entity. */
avg() > 20 && db_message_count('1 hour', 'compaction', '') == 0

/* Checks if the average exceeds 80 and there is an event with 'type=backup-error'
received within the last 15 minutes for entity 'nurswgvml006'. */
avg() > 80 && db_message_count('15 minute', 'backup-error', '', '', 'nurswgvml006') > 0

/* Counts messages within the previous 60 minutes
for 'type=compaction', any source, any tags and all entities. */
db_message_count('1 hour', 'compaction', '',  '', '*')

/* Counts messages with the same text as in the last command, but from different users. */
db_message_count('1 minute', 'webhook', 'slack', 'event.type=' + tags.event.type, entity,
                 'message=' + message + 'AND tags.event.user!=' + tags.event.user)

db_message_last Examples

last_msg = db_message_last('60 minute', 'logger', '')
/* Check that the average exceeds 50 and the severity of the last message with type 'logger'
for the current entity is greater than or equal to 'ERROR'. */
avg() > 50 && last_msg != null && last_msg.severity.toString() >= "6"

/* Retrieves the last message with text beginning 'docker start sftp*'. */
db_message_last('1 minute', 'webhook', 'slack', 'event.channel=D7UKX9NTG,event.type=message',
                'slack', 'message LIKE "docker start sftp*"')

/* Returns the most recent message within 1 day for the current entity,
containing tag 'api_app_id=583' and regardless of type or source. */
db_message_last('1 day', null, null, ["api_app_id":"583"], entity)

/* Returns message with type 'webhook' and empty tags. */
db_message_last('15 second', 'webhook', '',  '', '', "tags.isEmpty()=true")

db_messages Examples

/* Retrieves messages with the text ending '*Selected' and any tags. */
db_messages('30 second', 'webhook', 'axibase-bot', '', 'slack', 'message LIKE "*Selected"')

/* Retrieves messages with severety 'Warning' within 15 second and send values of 'command' tag in notification. */
msgs = db_messages('15 second', 'logger', '', '', '', 'severity="warning"')

@foreach{m : msgs}
@{m.tags.get('command')}
@end{}