binconfig.md

Toolbelt, Daemon, and Webapi configuration

Executables that use Capillaries need to be able to access the message queue (RabbitMQ) and the database (Cassandra). There are also some settings that may be helpful during troubleshooting and performance tuning in specific environments. All these settings are managed by EnvConfig (capi*.json file residing in the binary's directory).

handler_executable_type

Name of the queue this executable consumes messages from. Also used by the logger to identify the source of each log message, so it makes sense to assign a distinct handler_executable_type value to each binary - Daemon, Toolbelt, Webapi.

cassandra

Cassandra-related settings, mostly mimicking gocql.ClusterConfig settings.

hosts

List of host names/addresses passed to gocql.NewCluster

port

Port number (usually 9042), passed to gocql.ClusterConfig.Port

username

As is, passed to gocql.PasswordAuthenticator

password

As is, passed to gocql.PasswordAuthenticator

keyspace_replication_config

The string passed to CREATE KEYSPACE IF NOT EXISTS <keyspace_name> WITH REPLICATION = ... when a keyspace is created

writer_workers

Capillaries processors that write to data tables produce data at a rate much higher than a single-thread code writing to Cassandra can handle. Capillaries inserts into data and index from multiple threads, and the number of those threads is specified here. 10 threads may be considered conservative, 50 threads is aggressive. Choose these settings according to your hardware environment specifics.

min_inserter_rate

If average number of records written per second by all writer workers used by a single worker thread from the thread pool (see thread_pool_size) falls below this value, chances are that Cassandra cluster performance has degraded substantially, and the user will wait for the results for too long. In this case, table inserter throws an error and the batch is marked as failed.

num_conns

Passed to gocql.ClusterConfig.NumConns

timeout

Milliseconds, passed to gocql.ClusterConfig.Timeout. It is expected to be larger than write_request_timeout_in_ms/read_request_timeout_in_ms set in cassandra.yaml, otherwise it may be trigger before Cassandra coordinator has a chance to handle therequest.

connect_timeout

Milliseconds, passed to gocql.ClusterConfig.ConnectTimeout

amqp

RabbitMQ settings, used in github.com/rabbitmq/amqp091-go

url

RabbitMQ url, passed to amqp.Dial()

exchange

Name of RabbitMQ exchange used by the daemon/toolbelt to send messages passed to amqp.Channel.ExchangeDeclare()

prefetch_count

As is, passed to amqp.Channel.Qos()

prefetch_size

As is, passed to amqp.Channel.Qos()

private_keys

Username->private_key_file_path map used for SFTP upload and download. For example, if anything in your script configuration or API call parameters (like script_file or script_params URIs) points to sftp://ubuntu@somehost/some/file/path, you will need an entry like this: ubuntu -> /local/path/to/ubuntu_user_private_key in your:

• Daemon capidaemon.json env config file (if this sftp URI points to data or configuration files)
• Webapi capiwebapi.json env config file (if this sftp URI points to configuration files)
• Toolbelt capitoolbelt.json env config file (if this sftp URI points to configuration files)

custom_processors

Placeholder for custom processor configurations.

thread_pool_size

Number of threads processing RabbitMQ messages consumed by the binary. Choose this setting according to your hardware environment specifics.

Default: 5 threads

ca_path

Path to the directory containing PEM certificates for all supported CAs. Required only if any of the following is referenced by HTTPS:

• script file
• script parameter file
• tag_criteria_uri
• input data files

To obtain the PEM cert, navigate to the file URI with a browser, open certificate information, navigate to the root certificate, save it as DER/CER (say, digicert.cer), and convert it to pem using this command:

openssl x509 -inform der -in digicert.cer -out digicert.pem

and copy the result PEM file to ca_path location. Do not pollute ca_path directory with unused certificates.

Proper ca_path setting is crucial for running HTTPS version of Capillaries tag_and_denormalize integration test, as it pulls configuration file and input data via HTTPS from github.com.

If ca_path is empty, Go uses the host's root CA set (/usr/ssl/certs etc).

dead_letter_ttl

x-message-ttl setting passed to amqp.Channel.QueueDeclare(). After RabbitMQ detects a message that was consumed but not handled successfully (actively rejected or not acknowledged), it places the message in the dead letter queue, where it resides for dead_letter_ttl milliseconds and RabbitMQ makes another delivery attempt.

1s is very aggressive, may work well for small and time-critical cases. 5-10s are more reasonable values.

Default: 5000 milliseconds

Read more about Capillaries dead-letter-exchange.

zap_config

Directly deserialized to zap.Config

webapi

This section is required by Webapi only.

webapi_port

Webapi uses this port for incomig HTTP requests.

Default: 6543

access_control_allow_origin

Used by Webapi for CORS. Can contain either "*" or a comma-separated list of allowed origin URLs.

Default: http://localhost:8080,http://127.0.0.1:8080