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:

1. Open a connection and provide agent details
2. Authenticate with your project token
3. 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 1627271932
 > ^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

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:

1. The command name (increment or gauge)
2. The name of the metric
3. The value to be recorded. In increment's case, it is the value to increment the metric by. In gauge's case, it is a new measurement to record.
4. 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

1. The command name (notice)
2. The time when the event occurred. This value should be expressed as a Unix timestamp (seconds since 1970)
3. The duration of the event in seconds. You may specify 0 for events which have no specific duration.
4. 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.