message Command


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


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, otherwise the message is dropped silently.
  • Entity name, 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"


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 Time in Unix seconds.
ms integer Time in Unix milliseconds.
d string Time in ISO format.
  • Messages with timestamps that are more than 1 minute behind or ahead of the current server time are ignored by the rule engine.

Special Tags

Special tags supported by the message command:

Name Description
type Message type.
source Message source.
severity Criticality level in numeric or text format.

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.


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


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 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 -w 1 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\"");
  • curl
curl https://atsd_hostname:8443/api/v1/command \
  --insecure --include --user username:password \
  --header "Content-Type: text/plain" \
  --data-binary $'message e:server001 t:type=deploy m:"Hello World"'


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 -w 1 atsd_hostname 8081
$ echo -e "debug message e:server001 t:type=deploy m:\"branch: master\"" \
>   | nc -w 1 atsd_hostname 8081

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.