Axibase Time Series Database

message Command

Description

Inserts a timestamped text message for a given entity and tags into the database.

Syntax

message d:${time} e:${entity} t:type=${type} t:source=${source} t:severity=${severity} t:${tag-name}=${tag-value} m:${message}
  • If time fields are omitted, the record is inserted with the current server time.
  • Message text or at least one tag is required.
  • Entity name and tag names are case-insensitive and are converted to lower case when stored.
  • Tag values and message text are case-sensitive and are stored as submitted.
# Input command
message e:nurSWG t:type=Security t:FS_type=NFS m:"Initiation complete"

# Stored database record
message e:nurswg t:type=Security t:fs_type=NFS m:"Initiation complete"

Fields

Field Type Description
e string [Required] Entity name.
t string Tags, including reserved tags: type, source, severity.
m string Message text.
p boolean Persist message in the database.
Default: true.
If set to false, the message is processed only by the rule engine.
s integer Unix time in seconds.
ms integer Unix time in milliseconds.
d string Time in ISO format.

Special Tags

Special tags supported by the message command:

Name Description
type Message type.
source Message source.
severity Message severity as an integer or text code.

The type and source tags are indexed and including them in the message command is recommended for faster retrieval times.

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.

Limits

Refer to limits.

ABNF Rules

Parent rules inherited from Base ABNF.

; message or at least one tag is required
command = "message" MSP entity [MSP tag-type] [MSP tag-source] [MSP tag-severity] *(MSP tag) [MSP time] [MSP persist] [MSP message]
entity = "e:" NAME
tag-type = "t:type=" VALUE
tag-source = "t:source=" VALUE
  ; severity value is case-insensitive
  ; https://tools.ietf.org/html/rfc7405#section-2.1
tag-severity = "t:severity=" (%x30-37 / %i("UNDEFINED"/"UNKNOWN"/"NORMAL"/"WARNING"/"MINOR"/"MAJOR"/"CRITICAL"/"FATAL") )
tag = "t:" NAME "=" VALUE
message = "m:" VALUE
persist = "p:" BOOLEAN
time = time-millisecond / time-second / time-iso
time-millisecond = "ms:" POSITIVE_INTEGER
time-second = "s:" POSITIVE_INTEGER
time-iso = "d:" ISO_DATE

Examples

Command Examples

  • ISO date
message d:2016-03-04T12:43:20Z e:server001 t:type=application t:source=cron t:job=backup m:"Task completed"
  • Unix time in seconds
message s:1464076784 e:server001 t:type=logger t:source=Ruby.main
  • Server time
message e:server001 t:type=collector-job t:job=nginx-check t:status=OK

Send Examples

  • netcat
echo -e "message e:server001 t:type=deploy m:\"branch: master\"" \
  | nc -q 0 atsd_hostname 8081
  • bash command
echo -e "message e:server001 t:type=deploy m:\"branch: master\"" \
  > /dev/tcp/atsd_hostname/8081
  • bash script
#!/usr/bin/env bash

msg="message e:server001 t:type=deploy t:source=docs m:\"${1}\""

echo -e ${msg} > /dev/tcp/atsd_hostname/8081
  • Java
Socket s = new Socket("atsd_hostname", 8081);
PrintWriter writer = new PrintWriter(s.getOutputStream(), true);
writer.println("message e:server001 t:type=job m:\"Job failed\"");
s.close();
  • curl
curl https://atsd_hostname:8443/api/v1/command \
  -k --user username:password \
  --header "Content-Type: text/plain" \
  --data-binary $'message e:server001 t:type=deploy m:"Hello World"'

Troubleshooting

Activate Debug Mode

Append debug in front of the command to check server reply. If the command is accepted, the server replies with ok

echo -e "debug message e:server001 t:type=deploy m:\"branch: master\"" \
  | nc -q 0 atsd_hostname 8081

$ echo -e "debug message e:server001 t:type=deploy m:\"branch: master\"" \
>   | nc -q 0 atsd_hostname 8081
ok

View Command Logging

Invalid message commands are discarded by the server and recorded in the command_malformed.log.

tail -F /opt/atsd/atsd/logs/command_malformed.log

All accepted commands are stored in the /opt/atsd/atsd/logs/command.log.

← csv →