Configuration Options

The following is a list of available agent configuration options. All of them can and should be placed in the global.conf configuration file, which is read by all agents.

When using these options as environment variables (such as in a container), the syntax of agent options is slightly different; in order to not conflict with other variables, all options are prefixed with “VC_”. For example, if setting hostname through an environment variable one would use VC_HOSTNAME. Likewise, drv-manual-host-uri would become VC_DRV_MANUAL_HOST_URI.

Installation options are described here; however it is strongly recommended that you follow the appropriate installation instructions for your database setup. Setting these options is not required when adding databases using the web application and you should consult the relevant documentation for container or advanced installations.

Configuration Option Description
ignore-bindings Comma-separated list of bindings to ignore. Only relevant for on-host installation where autodiscovery is finding hosts that are not relevant and should not be monitored. Bindings are almost always the IP:port combination and typically look like the following (for example): 0.0.0.0:25675,[::]:25675. Adding that as the value of ignore-bindings would make the associated host not register. See here for more information about using this option.
drv-manual-host-uri Manually specify the address of the database you wish to monitor. There are a number of circumstances in which you would use this option, for both on-host and off-host installations. For an on-host installation it is used to specify a single database to monitor if there are multiple running on one host. For all installation types, it is used to automate the installation process if using the web application’s install flow is not a possibility. For more information on the uses of this option, see the Advanced and Containerized installation documentation.
drv-DRIVER-query-capture There is one configuration flag per supported database technology and the manual driver, and multiple possible values for each. This is generally handled automatically by the installation process. It needs to be set when doing a manual, non-standard configuration. For more information on the uses of this option, see the Advanced and Containerized installation documentation.
use-drv-DRIVER Indicates whether to use a specific database driver; it indicates whether the agent should detect databases of a certain type. There is a flag for each DRIVER, which can be one of mysql, pgsql, mongo, and redis. Default is true; setting it to false will prevent the detection of that database type. This is useful if a host is running two different database types and only one type needs to be monitored. Note that only MySQL, PostgreSQL, MongoDB, and Redis are automatically detected.
drv-DRIVER-daemon Sets the process name that the supervisor should look for when auto-detecting databases. A flag with each DRIVER exists for each auto-detected database (mysql, pgsql, mongo, redis). The default for each flag is the usual process name; for example, drv-mysql-daemon defaults to mysqld. This can be changed if the host is running a detectable database but has changed the process name for some reason.
host-discovery-limit Sets the maximum number of hosts that the supervisor will detect. Typically the only useful values are 0 and -1. Default is -1 which allows the agent to detect any number of running databases. 0 is used for off-host installations to prevent detection of unwanted local databases. This option is typically never changed manually and is set automatically by the install process.
enable-perf-schema Determines whether to fetch data from performance_schema. This is set automatically by the Add New Host installation and is typically only configured manually when changing installation types in place. Options are true and false.
enable-stat-stmts Determines whether to fetch data from pg_stat_statements. This is set automatically by the Add New Host installation and is typically only configured manually when changing installation types in place. Options are true and false.

Hosts & Tags

Configuration Option Description
hostname Sets a custom hostname to identify the host in DPM. This is useful when monitoring a managed database such as RDS and the host running the DPM software is likely to change. For more details on using this option, see our Hosts documentation.
enable-query-tags When set to true this will parse query tags and associate query digests with them, which allows you to filter by tag in the Profiler (i.e. see only query families with a specific tag).
host-tags A comma-separated list of tags to apply to this host. Spaces are not permitted. See our host tags documentation for more information.
enable-cloud-tags When set to true the agent will apply any AWS host tags found for that host. For example, if an RDS host is tagged with server_env and the value is stage, the agent will tag the host in DPM with server_env=stage. This option can be used for both database instances and EC2 instances (when configured with the vc-os-metrics agent). When an EC2 instance is detected, the tags are applied to any databases running on that instance. See also tags-sync-mode. See our host tags documentation for more information.
cloud-tags-interval How often to refresh the tags provided by AWS. Done once on startup and then at this interval. Default is 30m0s.
tags-sync-mode Controls how AWS tags interact with any DPM host tags. Can be set to merge and mirror. merge will add the AWS tags to any other tags you add to a host; mirror will overwrite any other DPM tags so that the host has the same tags in DPM and AWS. See our host tags documentation for more information.

Resource Utilization

Configuration Option Description
num-procs Sets the maximum number of processor cores the agent can use. Default is 1. Allowing the agent to utilize additional cores can be used to mitigate packet loss in the query agent (e.g. vc-mysql-query) when using TCP monitoring. Start by testing with 2, then 3 if necessary. When changing num-procs you must also change capture-mode (below).
capture-mode Sets how the query agent should process packets. Default is sync; it is most efficient but does not allow the agent to use multiple cores. Other values are async, which decodes packets in different threads, and auto, which lets the agent determine what to use on a per request basis. Depending on query workload you will need to test the performance of async vs. auto when changing num-procs.
capture-buflen Sets the size of the buffer for storing packet data when they are being received faster than can be processed. Default is 8MB. If a host is dropping packets this should be set to at least 32MB; more than ~160MB usually does not bring additional benefit. If the packet loss is particularly variable from moment to moment increasing this value sometimes resolves packet loss.

Event Configuration

Configuration Option Description
long-running-event-threshold Enables creation of Events for long-running queries and configures the threshold, in seconds. Default is 0, which turns the feature off. It is expressed as time and units; for example, “60s”. We recommend setting this for an entire environment through the Settings page in the webapp. However, this environment setting can be overridden with a configuration file on a specific host, if that host should have a different threshold.
pg-vacuum-events Comma-separated list of level:duration, where a vacuum lasting more than duration will trigger an event, e.g. “info:1m,warn:30m,crit:60m”. We recommend setting this for an entire environment through the Settings page in the webapp. However, this environment setting can be overridden with a configuration file on a specific host, if that host should have a different threshold.
disk-full-threshold-warn Configures the percent remaining disk space that will trigger a warning-level event that disk space is low. Default is 10. Note that this is only applicable to installations where the agent runs on the same server as the database; use a CloudWatch or Stackdriver metric to create an Alert when monitoring remotely.
disk-full-threshold-crit Configures the percent remaining disk space that will trigger a critical-level event that disk space is critically low. Note that this is only applicable to installations where the agent runs on the same server as the database; use a CloudWatch or Stackdriver metric to create an Alert when monitoring remotely.
max-db-conns-threshold Sets the threshold for generating the DB connections warning alert. Defaults to ‘95’, meaning 95% of the maximum number of connections are in use.

Metric & Other Data Collection

Configuration Option Description
tag-delimiters Sets the characters used to identify and parse query tags in query comments into key/value pairs. The value is two characters; the first identifies what separates a key from a value, and the second separates pairs. The default value is equals (=) then a space (), meaning that it expects tags to look like foo=bar baz=xyzzy. This should be configured for an entire environment with the Settings page in the webapp. More information about query tags can be found in our documentation
digest-metrics Controls whether to digest numbers in database and table size metrics. For example, when this value is set to true, table_1 and table_2 would both become table_? for the purpose of table size metrics. Can be set to false.
enable-table-sizes Indicates whether to fetch database and table size information (data size, index size, total size, number of rows). Defaults to true; can be set to false. If this is set to true but the agent does not appear to be fetching table size data, restart the agent and check a) that the database does not exceed the 50,000 table maximum or b) that time-abort/time-size-abort was triggered.
time-abort (MySQL only) Sets the maximum latency of our query to fetch database and table sizes before the feature is automatically disabled. Defaults to 3s. Must include the s (seconds). Note that if the query times out the agent will disable the feature and NOT try to enable it again until the agent is restarted. For a number of clients 3 seconds is too low since a single slow execution, even if the query is otherwise performant, will disable the data.
time-size-abort (databases other than MySQL) Sets the maximum latency of our query to fetch database and table sizes before the feature is automatically disabled. Defaults to 3s. Must include the s (seconds). Note that if the query times out the agent will disable the feature and NOT try to enable it again until the agent is restarted. For a number of clients 3 seconds is too low since a single slow execution, even if the query is otherwise performant, will disable the data.
max-subbatch-size Sets the maximum number of databases and tables to fetch size information for at one time. Helps to keep the execution cost of the query low. Default is 50. See also top-table-limit and top-schema-limit.
top-table-limit Sets the maximum number of tables to fetch size data for. Tables ranked below the values (based on size) will be grouped into an Others row. Default is 50. Larger values may have performance implications. See also top-schema-limit.
top-schema-limit Sets the maximum number of databases to fetch size data for. Databases ranked below the values (based on size) will be grouped into an Others row. Default is 50. Larger values may have performance implications. See also totp-table-limit.
schema-blacklist Comma separated list of schema names to not fetch database size metrics for.
repl-heartbeat (MySQL only) Indicates whether to fetch replication delay information using a heartbeat table instead of database-provided functions such as SHOW SLAVE STATUS. The table must exist on both the primary and the secondary. The agent must have SELECT, INSERT, and UPDATE privileges on the table specified by repl-heartbeat-table. Default is false; can be set to true.
repl-heartbeat-table (MySQL only) Defaults to vividcortex.heartbeat. Database and table of where to store heartbeat information, if used to track replication delay. The table must exist on both the master and the slave. The agent must have SELECT, INSERT, and UPDATE privileges on the table. Must also set repl-heartbeat to true.
repl-heartbeat-ttl (MySQL only) The maximum age for a heartbeat row, after which it is considered invalid. The default is 300 seconds. After this time the replica database simply ignores the row.
show-status Configures whether to run MySQL’s show-status to collect data. Default is true; other option is false, which can be used if show-status causes database performance issues (typically the result of a known bug in MySQL). Setting this to false is rare and non-query data collection is severely limited when this is enabled.
disable-system-metrics Disables collection of system metrics by vc-os-metrics. Default is false. This is typically used in off-host configurations, where the OS metrics of the agent are not the metrics for the database. OS metrics are sometimes (rarely) needed to diagnose agent deployment issues, so this can be set from false to true temporarily if that might be necessary.
enable-plist-lock-detector Whether or not to try to detect queries waiting on a lock and queries holding a lock other threads desire. Default is true. Disabling can improve performance, and the query is automatically disabled if too many long-running threads are detected.
enable-cloudwatch Defaults to auto. Sets whether or not to fetch CloudWatch metrics; can be set to true or false in addition to auto.
processlist-query (MySQL only) Specify which query to use to fetch running processlist information. Default is auto which lets the metrics agent choose the least expensive option available for fetching this information. performance_schema.threads is the most efficient; then the agent will try information_schema.processlist and then SHOW PROCESSLIST. Options are performance_schema, information_schema, or processlist in addition to auto.
track-offhost-prep-stmt (MySQL only) Instruct the agent to track prepared statement queries when monitoring MySQL in off-host mode. This is done by querying the performance_schema.prepared_statements_instances table, which is available in MySQL v5.7 and newer. Option defaults to disabled. NOTE: MySQL only stores information on active prepared statements, so enabling this option may not help for workloads that have many short-lived prepared queries.

Digest Options

Configuration Option Description
max-prep-stmts Controls the maximum number of prepared statements per connection to track. Default is 500. When an execute is sent for a prepared statement, we will associate the data (latency, count, etc.) with the appropriate prepared statement assuming we saw the prior prepare. This option controls the number of prepared statements we will “remember” in this manner, per connection. Only relevant for MySQL and PostgreSQL installations monitoring with packet sniffing.
max-digest-length Controls the maximum length of characters to examine before truncation. Default is 2046; maximum is 32000. Smaller values will group long queries together which only differ at the end of the query; larger values will create more digests. Note that for off-host installations, enlarging this value will have no effect if the digest is truncated by the database before DPM collection. For more information, see this FAQ.
truncate-digests-length (Postgres off-host) - After digestion has already taken place for both query digests (from pg_stat_statements) and samples (from pg_stat_activity) truncate the resulting digest down to this length. This is in order to make the digested version from both sources match. Without using this option, they are more or less guaranteed to not match if the query is longer than max-digest-length. Set to some value smaller than max-digest-length.
force-offhost-digests Configures the MySQL metrics agent to attempt to turn on the statements_digest consumer, for an off-host installation, if it is disabled. Options are true and false; default is false. Using this feature requires the agent’s user to have the UPDATE privilege on performance_schema.setup_consumers. See also force-offhost-samples. This should be configured for an entire environment with the Settings page in the web app.
digest-tags Specifies whether to digest query tags. Defaults to no. Can also be set to both, name, or value.
ps-truncate-events-summary Whether or not to have the agent truncate performance_schema.events_statements_summary_by_digest when it is putting too many digests into the “others” row. Defaults to false and can be set to true. When enabled, the agent needs the DROP privilege on performance_schema.events_statements_summary_by_digest. The threshold for truncation is set by ps-others-tolerance (below). For example, setting ps-others-tolerance to 0.1 means the agent will truncate the table when 10% of queries are attributed to the “others” row. You can monitor when agent truncation events occur with the agents.vc_mysql_metrics.rds.events_truncated metric. More information about performance_schema_digest_lost can be found in our FAQ.
ps-others-tolerance The maximum percentage (expressed as a decimal) of queries being caught by the events_statements_summary_by_digest “others” row before triggering an event. Default is 0.5, but generally you do not want any queries caught by the “others” row. See the metric performance_schema_digest_lost for a count of the number of lost digests per second, and the agents.vc_mysql_metrics.rds.others_ratio for the current “others” percentage. More information about performance_schema_digest_lost can be found in our FAQ.

Sample Options

These are the options which control the collection and behavior of query samples. Many of these settings can be changed through the Settings page in the webapp. For complete details about samples and collection options check our Query Samples documentation.

Configuration Option Description
max-sample-slots When determining what queries to sample we keep track of the last time each query has been seen. We keep track of the last time we’ve seen any query in a group of queries; the number of groups is given by max-sample-slots. Default is 7500. Each group consumes 40 bytes. If this value is too small, queries which run infrequently may not be sampled due to hash collisions with more frequent queries which update the last seen data.
disable-sampling Disables sample collection entirely for a host when set to true. Default is false. This eliminates collection of all aspects of query samples: metadata, execution plans, and raw query text. Setting this to true overrides any other sample collection option. This should be configured for an entire environment with the Settings page in the webapp.
disable-sampling-text Disables collection of raw query text, as well as removes possibly-sensitive portions of execution plans, but still captures most execution plan information as well as execution metadata (e.g. latency, connection ID, etc.) when set to true. Default is false. This should be configured for an entire environment with the Settings page in the webapp.
dyn-sample-text When set to true allows the agent to begin collecting query samples when otherwise disabled without requiring an agent restart. This does not enable collection; it only enables the possibility of dynamically enabling and disabling collection via the Inventory page.
enable-explains Enables the capture of execution plans when set to true. Default is true; can also be set to false. Changing this value is rare. If you are missing execution plans, check this FAQ.
max-sample-length Controls the maximum length of raw query text in samples. Default is 4096; maximum is 32000. Note that for off-host installations, enlarging this value will have no effect if the sample is truncated by the database before DPM collection; see this FAQ for more information.
max-execute-payload Maximum size (number of bytes) of a prepared statement that we will try to reconstruct into a query sample using values seen during an execute. Statements longer than this maximum will have their sample replaced with a “max size exceeded” message. Raising this will reconstruct longer statements at the cost of CPU time. Only applicable to MySQL and PostgreSQL databases which use the on-host (network sniffing) installation type.
query-whitelist-pattern A regular expression which describes the queries to sample. All queries which do not match the whitelist will not be sampled. Do not also enable disable-sampling or disable-sampling-text as those options supercede this one. See also query-blacklist-pattern. This should be configured for an entire environment with the Settings page in the webapp.
query-blacklist-pattern A regular expression which describes the queries to not sample. All queries which do not match the blacklist will be sampled. Do not also enable disable-sampling or disable-sampling-text as those options supercede this one. See also query-whitelist-pattern. This should be configured for an entire environment with the Settings page in the webapp.
query-comment-pattern A regular expression which describes the query comments to keep. This option discards query text and only keeps query comments which match the expression. Default is blank (keep all query text and all comments). Typical use is to specify * which will discard query text and keep all comments. (This is not a valid regular expression but it is handled appropriately.) This should be configured for an entire environment with the Settings page in the webapp.
force-offhost-samples Configures the MySQL metrics agent to attempt to turn on events_statements_history_long, for an off-host installation, if it is disabled. Options are true and false; default is false. Using this feature requires the agent’s user to have the UPDATE privilege on performance_schema.setup_consumers. See also force-offhost-digests. This should be configured for an entire environment with the Settings page in the webapp.

Logging & File Options

Configuration Option Description
log-type Sets the destination of agent log messages. Default is file. Other options are stderr and syslog. Changing this option from file makes the log inaccessible from the webapp (and therefore inaccessible to DPM technical support), which makes debugging more difficult.
log-dir Sets the directory to store log files when log-type is set to file. Defaults to /var/log/vividcortex/. This is not commonly changed, but can be useful if the file permissions on the host are restrictive and the agent is allowed access to a specific directory.
log-level Sets the verbosity of the log messaging. Default is 4. Can be set to 10 which will enable Debug messages.
download-dir Sets the directory where agent binaries will be downloaded when updating. Default is /tmp/vividcortex/download/. This is not commonly changed, but can be useful if the file permissions on the host are restrictive and the agent is allowed access to a specific directory.
agent-install-dir Sets the directory where agent binaries will be installed. Default is /usr/local/bin/. This is not commonly changed, but can be useful if the file permissions on the host are restrictive and the agent is allowed access to a specific directory.
lock-dir Sets the directory where the agent will write its lock file. Default is /var/lock/vividcortex/. This is not commonly changed, but can be useful if the file permissions on the host are restrictive and the agent is allowed access to a specific directory.
pid-dir Sets the directory where the agent will write its pid file. Default is /var/run/vividcortex/. This is not commonly changed, but can be useful if the file permissions on the host are restrictive and the agent is allowed access to a specific directory.
run-dir Sets the directory the agent will use for inter-process communication (IPC). Default is /var/run/vividcortex. This is not commonly changed, but can be useful if the file permissions on the host are restrictive and the agent is allowed access to a specific directory.

API Communication

Configuration Option Description
skip-certs When set to true the agent will use any TLS certificate even if not accepted by the host server. Setting this is not recommended as it presents a huge security vulnerability. Agent traffic can be intercepted by an actor other than the DPM API and expose data. Use only during non-production proof-of-concept installations on very old hosts.
override-os-certs Use embedded CA certificates instead of the ones supplied by the OS. See above for security concerns.
api-uri Sets the address of the API. Defaults to https://app.vividcortex.com/api. This should generally not be changed. To use a proxy, use proxy-uri.
cdn-uri Sets the address of where agent updates will be downloaded from. Defaults to https://download.vividcortex.com/. This should generally not be changed.
proxy-uri Address of a proxy for the agents to use when contacting the API, such as when sending metrics. More information about using a proxy can be found here.
api-token The token used when communicating with the API. This should NOT be a token created through Settings -> API Tokens, but created only during the installation process automatically by the agent or the Containerized token. The token displayed by the webapp during the On-Host or Off-Host install process is temporary and CANNOT be used here. The token should also be considered secret and not shared. This typically does not need to be set manually.