- Metric Sources
- Using Instrumental
- Where to Start
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!
- 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 (
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 $>
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
The collector resides at
collector.instrumentalapp.com:8000 (standard) or
collector.instrumentalapp.com:8001 (SSL). The collector has a TCP connection timeout of
Connect to the collector by sending a
hello handshake message in the following format:
hello version AGENT_VERSION [hostname HOSTNAME] [pid PID] [platform PLATFORM]
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.
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.
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.
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,
gauge, take the following arguments:
increment test.increment_metric 1 1326735451
gauge test.gauge_metric 75.8232 1326735451
The format of these messages is:
- The command name (
- The name of the metric
- 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.
- 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
increment command. If your data is improperly formatted, your agent will be disconnected.
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
- Timestamps are expressed as integer values representing the number of seconds since 1970 (Unix timestamp).
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
- The command name (
- 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
gauge commands, the server will not return any data upon receiving this command. Improperly formatted commands will cause your agent to be disconnected.