TCP Collector
The TCP Collector Protocol allows for a direct connection to the Instrumental metric collection interface. Use of this protocol is rare as most monitoring scenarios can be easily handled by our application monitoring or server monitoring integrations. But if you wish to develop a custom integration, we are happy to answer any questions! And if you open source your work, please send us a link!
Connection Process & Formatting
Each connection should follow three steps:- Open a connection and provide agent details
- Authenticate with your project token
- Submit as many metrics and/or notices (separated by newlines) as you want!
All messages sent to the collector must be terminated by newlines (\n
).
Interactive Command Line Example
The following example uses an interactive netcat
session to connect to the server, perform an authentication handshake, and record an increment
metric for a project.
$> nc collector.instrumentalapp.com 8000 > hello version bash/nc/1.0.0 ok > authenticate PROJECT_TOKEN ok > increment test.metric 1 1614503553 > ^C $>
Bash / Zsh scripts
If you're unable to use one of our agents, it's possible to use the TCP collector endpoint directly via command line. Here's a command-line friendly version of the interactive example above:
echo -e "hello version bash/nc/1.0.0\nauthenticate PROJECT_TOKEN\nincrement test.metric 1 `date +%s`" | nc collector.instrumentalapp.com 8000 > /dev/null 2>&1
Note that this example uses date +%s
to get a unix timestamp for the increment
command.
Open a Connection
The collector resides at collector.instrumentalapp.com:8000
(standard) or collector.instrumentalapp.com:8001
(SSL). The collector has a TCP connection timeout of 120
seconds.
Connect to the collector by sending a hello
handshake message in the following format:
hello version AGENT_VERSION [hostname HOSTNAME] [pid PID] [platform PLATFORM]
For example:
hello version ruby/instrumental_agent/0.12.5 hostname doom.local pid 49310 runtime ruby/2.1.2p95 platform x86_64-darwin14.0
hello version node/statsd-instrumental-backend/0.10.0 hostname doom.local pid 49692 runtime node/0.10.28 platform darwin-x64
AGENT_VERSION
must be a string specifying the agent's current version. Format: language/agent-name/version (no spaces allowed).
HOSTNAME
must be a string specifying the agent's FQDN for it's host (no spaces allowed).
PID
must be a string specifying the agent's process id (no spaces allowed).
PLATFORM
must be a string specifying the agent's operating system and version (no spaces allowed).
RUNTIME
may be a string specifying the agent's execution runtime environment and version (no spaces allowed).
Upon receiving this message, the collector will return a string that says ok
if it is able to receive metrics from your agent.
Authentication
After notifying the collector of your agent version, you must authenticate your agent for the project whose metrics you will be submitting. You will do this with the authenticate command, which uses your project token to identify your agent.
authenticate PROJECT_TOKEN
Upon successful authentication, the collector will send back the message ok
, at which point you may submit metrics to the collector. If authentication fails, then the collector will print a diagnostic message and disconnect your agent.
Sending Metrics
After successfully authenticating your agent, you may submit multiple metrics to the server, bound by the 120 second TCP connection timeout.
The two commands for this, increment
and gauge
, take the following arguments:
increment test.increment_metric 1 1326735451
gauge test.gauge_metric 75.8232 1326735451
Message Format
The format of these messages is:
- The command name (
increment
orgauge
) - The name of the metric
- The value to be recorded. In
increment
's case, it is the value to increment the metric by. Ingauge
's case, it is a new measurement to record. - The time when the datapoint should be recorded. This value should be expressed as a Unix timestamp (seconds since 1970).
The collector will not return a value after receiving a gauge
or increment
command. If your data is improperly formatted, your agent will be disconnected.
Data Format
The collector expects your data to be formatted according to these rules:
- Metric names may not contain whitespace
- Metric values are expressed as integers or floating point numbers of the form
24.38343
- Timestamps are expressed as integer values representing the number of seconds since 1970 (Unix timestamp).
Sending Notices
After successfully authenticating your agent, you may submit multiple notices to the server, bound by the 120 second TCP connection timeout. Notices are simply text descriptions of an event, such as a code deployment.
Submit information regarding project specific events using the notice
command. This command allows you to specify a timestamp, a duration, and a description of what occurred. This message follows the format:
notice 1326735451 0 Deployed revision 038ade4 to production
Message Format
- The command name (
notice
) - The time when the event occurred. This value should be expressed as a Unix timestamp (seconds since 1970)
- The duration of the event in seconds. You may specify 0 for events which have no specific duration.
- A string describing the event
As with the increment
and gauge
commands, the server will not return any data upon receiving this command. Improperly formatted commands will cause your agent to be disconnected.