Configuration

OpenTSDB can be configured via a file on the local system, via command line arguments or a combination or both.

Configuration File

The configuration file conforms to the Java properties specification. Configuration names are lower-case, dotted strings without spaces. Each name is followed by an equals sign, then the value for the property. All OpenTSDB properties start with tsd. Comments or inactive configuration lines are blocked by a hash symbol #. For example:

# List of Zookeeper hosts that manage the HBase cluster
tsd.storage.hbase.zk_quorum = 192.168.1.100

will configure the TSD to connect to Zookeeper on 192.168.1.100.

When combining configuration files and command line arguments, the order of processing is as follows:

  1. Default values are loaded

  2. Configuration file values are loaded, overriding default values

  3. Command line parameters are loaded, overriding config file and default values

File Locations

You can use the --config command line argument to specify the full path to a configuration file. Otherwise if not specified, OpenTSDB and some of the command-line tools will attempt to search for a valid configuration file in the following locations:

  • ./opentsdb.conf

  • /etc/opentsdb.conf

  • /etc/opentsdb/opentsdb.conf

  • /opt/opentsdb/opentsdb.conf

In the event that a valid configuration file cannot be found and the required properties are not set, the TSD will not start. Please see the properties table below for a list of required configuration settings.

Properties

The following is a table of configuration options for all tools. When applicable, the corresponding command line override is provided. Please note that individual command line tools may have their own values so see their documentation for details.

Note

For additional parameters used for tuning the AsyncHBase client, see AsyncHBase Configuration

Property

Type

Required

Description

Default

CLI

tsd.core.auto_create_metrics

Boolean

Optional

Whether or not a data point with a new metric will assign a UID to the metric. When false, a data point with a metric that is not in the database will be rejected and an exception will be thrown.

False

–auto-metric

tsd.core.auto_create_tagks (2.1)

Boolean

Optional

Whether or not a data point with a new tag name will assign a UID to the tagk. When false, a data point with a tag name that is not in the database will be rejected and an exception will be thrown.

True

tsd.core.auto_create_tagvs (2.1)

Boolean

Optional

Whether or not a data point with a new tag value will assign a UID to the tagv. When false, a data point with a tag value that is not in the database will be rejected and an exception will be thrown.

True

tsd.core.connections.limit (2.3)

Integer

Optional

Sets the maximum number of connections a TSD will handle, additional connections are immediately closed.

0

tsd.core.enable_api (2.3)

Boolean

Optional

Whether or not to allow the 2.x HTTP API to function. When disabled, calls to endpoints such as /api/query or /api/suggest will return a 404.

True

–disable-api

tsd.core.enable_ui (2.3)

Boolean

Optional

Whether or not to allow the built-in GUI and legacy HTTP API to function. When disabled, calls to the root endpoint or other such as /logs or /suggest will return a 404.

True

–disable-ui

tsd.core.histograms.config (2.4)

JSON/File Path

Optional

A mapping of histogram codec class names to numeric identifications for storing multi-measurement data. For simple configurations, the value may be a quote-escaped JSON map, e.g. {"net.opentsdb.core.SimpleHistogramDecoder":0, "net.opentsdb.core.CompactQuantilesSketchCodec":1}. If the value ends with .json then it will be treated as a file path and the given file will be opened and parsed. Numeric IDs must be between 0 and 255.

tsd.core.meta.cache.enable (2.3)

Boolean

Optional

Whether or not the meta data caching plugin is enabled.

False

True

tsd.core.meta.cache.plugin (2.3)

String

Optional

The class name of a plugin implementing the meta cache interface.

tsd.core.meta.enable_realtime_ts

Boolean

Optional

Whether or not to enable real-time TSMeta object creation. See Metadata

False

tsd.core.meta.enable_realtime_uid

Boolean

Optional

Whether or not to enable real-time UIDMeta object creation. See Metadata

False

tsd.core.meta.enable_tsuid_incrementing

Boolean

Optional

Whether or not to enable tracking of TSUIDs by incrementing a counter every time a data point is recorded. See Metadata (Overrides tsd.core.meta.enable_tsuid_tracking)

False

tsd.core.meta.enable_tsuid_tracking

Boolean

Optional

Whether or not to enable tracking of TSUIDs by storing a 1 with the current timestamp every time a data point is recorded. See Metadata

False

tsd.core.plugin_path

String

Optional

A path to search for plugins when the TSD starts. If the path is invalid, the TSD will fail to start. Plugins can still be enabled if they are in the class path.

tsd.core.preload_uid_cache (2.1)

Boolean

Optional

Enables pre-population of the UID caches when starting a TSD.

False

tsd.core.preload_uid_cache.max_entries (2.1)

Integer

Optional

The number of rows to scan for UID pre-loading.

300,000

tsd.core.stats_with_port (2.3)

Boolean

Optional

Whether or not to export the listening network port of the TSD as a tag with stats when calling one of the stats endpoints.

False

True

tsd.core.storage_exception_handler.enable (2.2)

Boolean

Optional

Whether or not to enable the configured storage exception handler plugin.

False

tsd.core.storage_exception_handler.plugin (2.2)

String

Optional

The full class name of the storage exception handler plugin you wish to use.

tsd.core.tag.allow_specialchars (2.3)

String

Optional

An optional list of ASCII characters allowed in metric names, tag names and tag keys above those already allowed by TSDB. Spaces are allowed.

! ~/

tsd.core.timezone

String

Optional

A localized timezone identification string used to override the local system timezone used when converting absolute times to UTC when executing a query. This does not affect incoming data timestamps. E.g. America/Los_Angeles

System Configured

tsd.core.tree.enable_processing

Boolean

Optional

Whether or not to enable processing new/edited TSMeta through tree rule sets

false

tsd.core.uid.random_metrics (2.2)

Boolean

Optional

Whether or not to randomly assign UIDs to new metrics as they are created

false

tsd.core.bulk.allow_out_of_order_timestamps *(2.3.2)

Boolean

Optional

Whether or not to allow out-of-order values when bulk importing data from a text file.

false

tsd.core.authentication.enable *(2.4)

Boolean

Optional

Whether or not to enable the specified Authentication plugin

false

tsd.core.authentication.plugin *(2.4)

String

Optional

The class name of an authentication plugin to instantiate. If tsd.core.authentication.enable is set to false, this value is ignored.

tsd.http.cachedir

String

Required

The full path to a location where temporary files can be written. E.g. /tmp/opentsdb

–cachedir

tsd.http.query.allow_delete

Boolean

Optional

Whether or not to allow deleting data points from storage during query time.

False

tsd.query.enable_fuzzy_filter

Boolean

Optional

Whether or not to enable the FuzzyRowFilter for HBase when making queries using the explicitTags flag.

True

tsd.http.header_tag (2.4)

String

Optional

An optional HTTP header that, when passed to the HTTP /api/put API, will be extracted and added to the tags of the values posted with the content. Must match an HTTP header exactly.

X-CustomTag

tsd.http.request.cors_domains

String

Optional

A comma separated list of domain names to allow access to OpenTSDB when the Origin header is specified by the client. If empty, CORS requests are passed through without validation. The list may not contain the public wildcard * and specific domains at the same time.

tsd.http.request.cors_headers (2.1)

String

Optional

A comma separated list of headers sent to clients when executing a CORs request. The literal value of this option will be passed to clients.

Authorization, Content-Type, Accept, Origin, User-Agent, DNT, Cache-Control, X-Mx-ReqToken, Keep-Alive, X-Requested-With, If-Modified-Since

tsd.http.request.enable_chunked

Boolean

Optional

Whether or not to enable incoming chunk support for the HTTP RPC

false

tsd.http.request.max_chunk

Integer

Optional

The maximum request body size to support for incoming HTTP requests when chunking is enabled.

4096

tsd.http.rpc.plugins (2.2)

String

Optional

A comma delimited list of RPC plugins to load when starting a TSD. Must contain the entire class name.

tsd.http.show_stack_trace

Boolean

Optional

Whether or not to return the stack trace with an API query response when an exception occurs.

false

tsd.http.staticroot

String

Required

Location of a directory where static files, such as JavaScript files for the web interface, are located. E.g. /opt/opentsdb/staticroot

–staticroot

tsd.mode (2.1)

String

Optional

Whether or not the TSD will allow writing data points. Must be either rw to allow writing data or ro to block data point writes. Note that meta data such as UIDs can still be written/modified.

rw

tsd.network.async_io

Boolean

Optional

Whether or not to use NIO or traditional blocking IO

True

–async-io

tsd.network.backlog

Integer

Optional

The connection queue depth for completed or incomplete connection requests depending on OS. The default may be limited by the ‘somaxconn’ kernel setting or set by Netty to 3072.

See Description

–backlog

tsd.network.bind

String

Optional

An IPv4 address to bind to for incoming requests. The default is to listen on all interfaces. E.g. 127.0.0.1

0.0.0.0

–bind

tsd.network.keep_alive

Boolean

Optional

Whether or not to allow keep-alive connections

True

tsd.network.port

Integer

Required

The TCP port to use for accepting connections

–port

tsd.network.reuse_address

Boolean

Optional

Whether or not to allow reuse of the bound port within Netty

True

tsd.network.tcp_no_delay

Boolean

Optional

Whether or not to disable TCP buffering before sending data

True

tsd.network.worker_threads

Integer

Optional

The number of asynchronous IO worker threads for Netty

#CPU cores * 2

–worker-threads

tsd.no_diediedie (2.1)

Boolean

Optional

Enable or disable the diediedie HTML and ASCII commands to shutdown a TSD.

False

tsd.query.allow_simultaneous_duplicates (2.2)

Boolean

Optional

Whether or not to allow simultaneous duplicate queries from the same host. If disabled, a second query that comes in matching one already running will receive an exception.

False

tsd.query.filter.expansion_limit (2.2)

Integer

Optional

The maximum number of tag values to include in the regular expression sent to storage during scanning for data. A larger value means more computation on the HBase region servers.

4096

tsd.query.limits.bytes.allow_override, (2.4)

Boolean

Optional

Whether or not the query byte limiter can be overiden on a per-query basis.

False

True

tsd.query.limits.bytes.default (2.4)

Integer

Optional

A limit on the number of bytes fetched from storage. When this limit is hit, the query will return with an exception. A value of 0 disables the limitter.

0

268435456

tsd.query.limits.data_points.allow_override (2.4)

Boolean

Optional

Whether or not the query data point limiter can be overiden on a per-query basis.

False

True

tsd.query.limits.data_points.default (2.4)

Integer

Optional

A limit on the number of data points fetched from storage. When this limit is hit, the query will return with an exception. A value of 0 disables the limiter.

0

1000000

tsd.query.limits.overrides.interval (2.4)

Integer

Optional

How often, in milliseconds, to reload the byte and data point query limiter plugin configuration.

60000

tsd.query.limits.overrides.config (2.4)

JSON/File Path

Optional

The path or full config of a query limit configuration with options to match on metric names.

tsd.query.multi_get.enable (2.4)

Boolean

Optional

Whether or not multi-get queries are enabled in conjunction with the search plugin.

False

True

tsd.query.multi_get.batch_size (2.4)

Integer

Optional

The number of get requests sent to storage in a single request.

1024

tsd.query.multi_get.concurrent (2.4)

Integer

Optional

The number of simultaneous batches outstanding at any given time for multi-get queries.

20

tsd.query.multi_get.get_all_salts (2.4)

Boolean

Optional

Whether or not a get request is fired for every bucket of salt or if the proper bucket is calculated. Used when salting configurations have changed.

False

True

tsd.query.skip_unresolved_tagvs (2.2)

Boolean

Optional

Whether or not to continue querying when the query includes a tag value that hasn’t been assigned a UID yet and may not exist.

False

tsd.query.timeout (2.2)

Integer

Optional

How long, in milliseconds, before canceling a running query. A value of 0 means queries will not timeout.

0

tsd.rollups.config (2.4)

String

Optional

The path to a configuration file detailing available rollup tables and aggregations. Must set tsd.rollups.enable to true for this option to be parsed. See Rollup And Pre-Aggregates

rollup_config.json

tsd.rollups.enable (2.4)

Boolean

Optional

Whether or not to enable rollup and pre-aggregation storage and writing.

false

tsd.rollups.tag_raw (2.4)

Boolean

Optional

Whether or not to tag non-rolled-up and non-pre-aggregated values with the tag key configured in tsd.rollups.agg_tag_key and value configured in tsd.rollups.raw_agg_tag_value

false

tsd.rollups.agg_tag_key (2.4)

String

Optional

A special key to tag pre-aggregated data with when writing to storage

_aggregate

tsd.rollups.raw_agg_tag_value (2.4)

String

Optional

A special tag value to non-rolled-up and non-pre-aggregated data with when writing to storage. tsd.rollups.tag_raw must be set to true.

RAW

tsd.rollups.split_query.enable (2.4.1)

Boolean

Optional

Whether or not queries should merge both rollup and raw data in a single query, particularly when rolledup data is delayed.

false

“

tsd.rollups.block_derived (2.4)

Boolean

Optional

Whether or not to block storing derived aggregations such as AVG and DEV.

true

tsd.rpc.plugins

String

Optional

A comma delimited list of RPC plugins to load when starting a TSD. Must contain the entire class name.

tsd.rpc.telnet.return_errors (2.4)

Boolean

Optional

Whether or not to return errors to the Telnet style socket when writing data via put or rollup

true

tsd.rtpublisher.enable

Boolean

Optional

Whether or not to enable a real time publishing plugin. If true, you must supply a valid tsd.rtpublisher.plugin class name

False

tsd.rtpublisher.plugin

String

Optional

The class name of a real time publishing plugin to instantiate. If tsd.rtpublisher.enable is set to false, this value is ignored. E.g. net.opentsdb.tsd.RabbitMQPublisher

tsd.search.enable

Boolean

Optional

Whether or not to enable search functionality. If true, you must supply a valid tsd.search.plugin class name

False

tsd.search.plugin

String

Optional

The class name of a search plugin to instantiate. If tsd.search.enable is set to false, this value is ignored. E.g. net.opentsdb.search.ElasticSearch

tsd.stats.canonical

Boolean

Optional

Whether or not the FQDN should be returned with statistics requests. The default stats are returned with host=<hostname> which is not guaranteed to perform a lookup and return the FQDN. Setting this to true will perform a name lookup and return the FQDN if found, otherwise it may return the IP. The stats output should be fqdn=<hostname>

false

tsd.startup.enable (2.3)

Boolean

Optional

Whether or not a startu plugin should be loaded before the TSD.

False

True

tsd.startup.plugin (2.3)

String

Optional

The name of a plugin implementing the StartupPlugin interface.

tsd.storage.compaction.flush_interval (2.2)

Integer

Optional

How long, in seconds, to wait in between compaction queue flush calls

10

tsd.storage.compaction.flush_speed (2.2)

Integer

Optional

A multiplier used to determine how quickly to attempt flushing the compaction queue. E.g. a value of 2 means it will try to flush the entire queue within 30 minutes. A value of 1 would take an hour.

2

tsd.storage.compaction.max_concurrent_flushes (2.2)

Integer

Optional

The maximum number of compaction calls inflight to HBase at any given time

10000

tsd.storage.compaction.min_flush_threshold (2.2)

Integer

Optional

Size of the compaction queue that must be exceeded before flushing is triggered

100

tsd.storage.enable_appends (2.2)

Boolean

Optional

Whether or not to append data to columns when writing data points instead of creating new columns for each value. Avoids the need for compactions after each hour but can use more resources on HBase.

False

tsd.storage.enable_compaction

Boolean

Optional

Whether or not to enable compactions

True

tsd.storage.fix_duplicates (2.1)

Boolean

Optional

Whether or not to accept the last written value when parsing data points with duplicate timestamps. When enabled in conjunction with compactions, a compacted column will be written with the latest data points.

False

tsd.storage.flush_interval

Integer

Optional

How often, in milliseconds, to flush the data point storage write buffer

1000

–flush-interval

tsd.storage.get_date_tiered_compaction_start

Integer

Optional

A Unix Epoch timestamp in milliseconds when date tierd compactions were enabled on the HBase table. This is useful for existing OpenTSDB installations moving to DTC. Queries starting before this time period will not set time boundaries on queries. See Date Tierd Compaction.

0

1514764800000

tsd.storage.hbase.data_table

String

Optional

Name of the HBase table where data points are stored

tsdb

–table

tsd.storage.hbase.meta_table

String

Optional

Name of the HBase table where meta data are stored

tsdb-meta

tsd.storage.hbase.prefetch_meta (2.2)

Boolean

Optional

Whether or not to prefetch the regions for the TSDB tables before starting the network interface. This can improve performance.

False

tsd.storage.hbase.scanner.maxNumRows (2.3)

Integer

Optional

The maximum number of rows to fetch from HBase per call to the scanner’s nextRows() method.

128

4096

tsd.storage.hbase.tree_table

String

Optional

Name of the HBase table where tree data are stored

tsdb-tree

tsd.storage.hbase.uid_table

String

Optional

Name of the HBase table where UID information is stored

tsdb-uid

–uidtable

tsd.storage.hbase.zk_basedir

String

Optional

Path under which the znode for the -ROOT- region is located

/hbase

–zkbasedir

tsd.storage.hbase.zk_quorum

String

Optional

A comma-separated list of ZooKeeper hosts to connect to, with or without port specifiers. E.g. 192.168.1.1:2181,192.168.1.2:2181

localhost

–zkquorum

tsd.storage.repair_appends (2.2)

Boolean

Optional

Whether or not to re-write appended data point columns at query time when the columns contain duplicate or out of order data.

False

tsd.storage.max_tags (2.2)

Integer

Optional

The maximum number of tags allowed per data point. This value can be changed after cluster creation. NOTE Please be aware of the performance tradeoffs of overusing tags writing

8

tsd.storage.salt.buckets (2.2)

Integer

Optional

The number of salt buckets used to distribute load across regions. NOTE Changing this value after writing data may cause TSUID based queries to fail.

20

tsd.storage.salt.width (2.2)

Integer

Optional

The width, in bytes, of the salt prefix used to indicate which bucket a time series belongs in. A value of 0 means salting is disabled. WARNING Do not change after writing data to HBase or you will corrupt your tables and not be able to query any more.

0

tsd.timeseriesfilter.enable (2.3)

Boolean

Optional

Whether or not the data writing filter plugins are enabled.

False

True

tsd.timeseriesfilter.plugin (2.3)

String

Optional

The class path to a plugin that implements the WriteableDataPointFilterPlugin interface for filtering time series on writes.

tsd.storage.uid.width.metric (2.2)

Integer

Optional

The width, in bytes, of metric UIDs. Maximum value is 7. WARNING Do not change after writing data to HBase or you will corrupt your tables and not be able to query any more.

3

tsd.storage.uid.width.tagk (2.2)

Integer

Optional

The width, in bytes, of tag name UIDs. Maximum value is 7. WARNING Do not change after writing data to HBase or you will corrupt your tables and not be able to query any more.

3

tsd.storage.uid.width.tagv (2.2)

Integer

Optional

The width, in bytes, of tag value UIDs. Maximum value is 7. WARNING Do not change after writing data to HBase or you will corrupt your tables and not be able to query any more.

3

tsd.storage.use_max_value (2.4)

Boolean

Optional

Whether or not to choose the larger numeric value during TSDB compaction when duplicates are found and tsd.storage.use_otsdb_timestamp has been set to true.

True

False

tsd.storage.use_otsdb_timestamp (2.4)

Boolean

Optional

Uses the data point’s timestamp for the edits in storage instead of the default now. See Date Tierd Compaction.

False

True

tsd.uidfilter.enable (2.3)

Boolean

Optional

Whether or not the UID assignment plugin filter is enabled.

False

True

tsd.uidfilter.plugin (2.3)

String

Optional

A plugin implementing the UniqueIdFilterPlugin interface.

tsd.uid.lru.enable (2.4)

Boolean

Optional

Changes the UID caches from unbounded maps to LRU caches.

False

True

tsd.uid.lru.id.size (2.4)

Integer

Optional

The total number of entries in the reverse UID to string map. Multiply this by 3 to get the total number of entries available, one per UID type (metric, tag key, tag value).

5000000

1000000

tsd.uid.lru.name.size (2.4)

Integer

Optional

The total number of entries in the forward string to UID map. Multiply this by 3 to get the total number of entries available, one per UID type (metric, tag key, tag value).

5000000

1000000

tsd.uid.use_mode (2.4)

Boolean

Optional

Determines if the name and/or ID caches should be populated based on the tsd.mode setting.

False

True

Data Types

Some configuration values require special consideration:

  • Booleans - The following literals will parse to True:

    • 1

    • true

    • yes

    Any other values will result in a False. Parsing is case insensitive

  • Strings - Strings, even those with spaces, do not require quotation marks, but some considerations apply:

    • Special characters must be escaped with a backslash include: #, !, =, and : E.g.:

      my.property = Hello World\!

    • Unicode characters must be escaped with their hexadecimal representation, e.g.:

      my.property = \u0009