command line arguments

Over time, carbon-c-relay grew a lot of options. Here is a list of flags that control the behaviour of the relay.

• -v

  Shows version of the relay. When a release, shows the (build) date, when built from git, shows the latest hash and dirty marker.

• -f

  File to read main configuration rules from. Clusters, matches, aggregates, rewrites etc. go in this file. Reading from stdin is not supported.

• -p

  Port to listen on for incoming connections for graphite line mode protocol This usually is port 2003, but can be anything. Based on your system, the relay will open up listeners on both IPv4 and IPv6 sockets, in TCP and UDP mode. In addition, a unix socket in /tmp/.s.carbon-c-relay.2003 is created, where /tmp can be overridden at compile time by defining TMPDIR and 2003 is replaced with the port number given as argument to this flag.

• -i

  Interface to restrict listening for incoming connections to. This should be a hostname or IP address of the interface. When not specified, the relay listens on all available interfaces, see -p.

• -l

  Log output to file, instead of writing to stdout and stderr. To re-open this logfile while running, send SIGHUP to the process.

• -w

  Number of workers to use. In the statistics metrics, called "dispatchers". The dispatchers are the threads reading from incoming connections and performing the necessary (routing) steps on the metrics. The idea is that more dispatchers can handle more connections at the same time. In practice you might find you don't need that many to handle a large amount of connections.

• -b

  Batch size used when sending metrics to a server. Each server target comes with an associated queue to detach clients sending metrics from the actual delivering to servers, see -q. When reading from this queue, the batch size determines how many are read and attempted to be sent at a time. A small setting here will introduce a relatively large overhead in fetching items from the queue, a large setting increases the memory usage of the relay somewhat. Note that most of the overhead is in sending, which is still done metric one by one, so changing this setting may not cause any noticable change.

• -q

  Queue size associated to server targets. For each individual server, the relay maintains a (delivery) queue. This queue is fixed in size in order not to grow unbounded, risking too much resource (memory) consumption. The size of the queue is fairly dependant on the environment the relay is used in. The average throughput (metrics per second) per server, defines how long a server can be unreachable before metrics have to be dropped for a given queue size. Also, the amount of disruptions that are normally seen, as well as the importance of the metrics obviously influences the size chosen (and hence memory allocated for) the queues.

• -S

  Statistics sending interval. The relay emits metrics about its own doing as carbon.relays.<hostname>.-metrics. The frequency in which it does this is defined by this setting in seconds.

• -B

  Backlog for accepting connections. This is a connection setting where the kernel keeps the number of connections without rejecting them without the relay picking them up. In environments where a lot of connections per second are made to the relay (thousands) and also roughly at the same time, the thread in the relay that is handling new connections cannot possibly succeed in time for each new connection. For this scenario it is nice when the backlog is large enough not to make those connections fail. Note that connections should not have to wait long in this backlog, this is about microseconds.

• -T

  Connection timeout for outbound server connections. In order to control how long the relay should wait before giving up on a connection to a server, use this value. In general, a small (<1s) value here is good, since it means the relay can quickly determine a server is unreachable, and therefore start dropping metrics if the queue is full, instead of slowing down clients. In some cases with WAN links it may be necessary to have a larger connection timeout though.

• -m

  Disable cumulative metric statistics. By default, the relay submits ever increasing values for its statistics. This means to make sense of them, e.g. the nonNegativeDerivative() graphite function has to be used. When this gives you extra trouble, enabling this flag will reset the counters each time the values are sent, such that no derivative function is necessary.

• -c

  The relays cleans up metrics because of a number of reasons. One being that when stored as whisper files, their filename on disk better be sane, another that graphite-web cannot deal with certain characters in metric names. This flag defines the characters next to numbers and letters that are allowed. This way characters like ; and / can be allowed which normally would be replaced with _ because they would cause problems.

• -d

  Enable debug mode. Like the option suggests, don't run this unless you're trying to debug what the relay is doing. In debug mode, the relay will not send statistics to the graphite stream, but send them to stdout instead. It also emits extra information while running, such as hash ring positions for consistent-hash clusters. When combined with -t more elaborate information is displayed. When combined with -s, an iostat like secondly statistics counters is printed.

• -s

  Enable submission mode. In this mode, the relay does not produce any statistics. As such the relay is transparent to the graphite stream, very suitable when used as smart buffer for submitting metrics from a local machine. Because no statistics are produced, the most important about queue usage and drop rates are reported on stdout for easy reviewing in the logs.

• -t

  Enable configuration test mode. The configuration can become complex or large, and regular expressions differ in syntax in each language. Therefore, in this mode the relay accepts input from stdin, and will print for each input line the matches and actions the relay would take. This includes the members of each consistent-hash cluster the metric would end up at.

• -H

  Override hostname used in statistics. This can basically be anything, since it is only used in the creation of the statistics metrics. It ends up in the metric here: carbon.relays.<hostname>.

• -D

  Daemonise. The relay will fork into the background and detach from the controling terminal.

• -P Write PID of the relay to file. This comes in handy when daemonised to signal the relay.