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:

  • Default values are loaded

  • Configuration file values are loaded, overriding default values

  • 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

PropertyTypeRequiredDescriptionDefaultCLI
tsd.core.auto_create_metricsBooleanOptionalWhether 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)BooleanOptionalWhether 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)BooleanOptionalWhether 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)IntegerOptionalSets the maximum number of connections a TSD will handle, additional connections are immediately closed.0
tsd.core.enable_api (2.3)BooleanOptionalWhether 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)BooleanOptionalWhether 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 PathOptionalA 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)BooleanOptionalWhether or not the meta data caching plugin is enabled.FalseTrue
tsd.core.meta.cache.plugin (2.3)StringOptionalThe class name of a plugin implementing the meta cache interface.
tsd.core.meta.enable_realtime_tsBooleanOptionalWhether or not to enable real-time TSMeta object creation. See MetadataFalse
tsd.core.meta.enable_realtime_uidBooleanOptionalWhether or not to enable real-time UIDMeta object creation. See MetadataFalse
tsd.core.meta.enable_tsuid_incrementingBooleanOptionalWhether 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_trackingBooleanOptionalWhether or not to enable tracking of TSUIDs by storing a 1 with the current timestamp every time a data point is recorded. See MetadataFalse
tsd.core.plugin_pathStringOptionalA 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)BooleanOptionalEnables pre-population of the UID caches when starting a TSD.False
tsd.core.preload_uid_cache.max_entries (2.1)IntegerOptionalThe number of rows to scan for UID pre-loading.300,000
tsd.core.stats_with_port (2.3)BooleanOptionalWhether or not to export the listening network port of the TSD as a tag with stats when calling one of the stats endpoints.FalseTrue
tsd.core.storage_exception_handler.enable (2.2)BooleanOptionalWhether or not to enable the configured storage exception handler plugin.False
tsd.core.storage_exception_handler.plugin (2.2)StringOptionalThe full class name of the storage exception handler plugin you wish to use.
tsd.core.tag.allow_specialchars (2.3)StringOptionalAn 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.timezoneStringOptionalA 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_AngelesSystem Configured
tsd.core.tree.enable_processingBooleanOptionalWhether or not to enable processing new/edited TSMeta through tree rule setsfalse
tsd.core.uid.random_metrics (2.2)BooleanOptionalWhether or not to randomly assign UIDs to new metrics as they are createdfalse
tsd.core.bulk.allow_out_of_order_timestamps *(2.3.2)BooleanOptionalWhether or not to allow out-of-order values when bulk importing data from a text file.false
tsd.core.authentication.enable *(2.4)BooleanOptionalWhether or not to enable the specified Authentication pluginfalse
tsd.core.authentication.plugin *(2.4)StringOptionalThe class name of an authentication plugin to instantiate. If tsd.core.authentication.enable is set to false, this value is ignored.
tsd.http.cachedirStringRequiredThe full path to a location where temporary files can be written. E.g. /tmp/opentsdb --cachedir
tsd.http.query.allow_deleteBooleanOptionalWhether or not to allow deleting data points from storage during query time.False
tsd.query.enable_fuzzy_filterBooleanOptionalWhether or not to enable the FuzzyRowFilter for HBase when making queries using the explicitTags flag.True
tsd.http.header_tag (2.4)StringOptionalAn 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_domainsStringOptionalA 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)StringOptionalA 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_chunkedBooleanOptionalWhether or not to enable incoming chunk support for the HTTP RPCfalse
tsd.http.request.max_chunkIntegerOptionalThe maximum request body size to support for incoming HTTP requests when chunking is enabled.4096
tsd.http.rpc.plugins (2.2)StringOptionalA comma delimited list of RPC plugins to load when starting a TSD. Must contain the entire class name.
tsd.http.show_stack_traceBooleanOptionalWhether or not to return the stack trace with an API query response when an exception occurs.false
tsd.http.staticrootStringRequiredLocation 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)StringOptionalWhether 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_ioBooleanOptionalWhether or not to use NIO or traditional blocking IOTrue--async-io
tsd.network.backlogIntegerOptionalThe 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.bindStringOptionalAn IPv4 address to bind to for incoming requests. The default is to listen on all interfaces. E.g. 127.0.0.10.0.0.0--bind
tsd.network.keep_aliveBooleanOptionalWhether or not to allow keep-alive connectionsTrue
tsd.network.portIntegerRequiredThe TCP port to use for accepting connections --port
tsd.network.reuse_addressBooleanOptionalWhether or not to allow reuse of the bound port within NettyTrue
tsd.network.tcp_no_delayBooleanOptionalWhether or not to disable TCP buffering before sending dataTrue
tsd.network.worker_threadsIntegerOptionalThe number of asynchronous IO worker threads for Netty#CPU cores * 2--worker-threads
tsd.no_diediedie (2.1)BooleanOptionalEnable or disable the diediedie HTML and ASCII commands to shutdown a TSD.False
tsd.query.allow_simultaneous_duplicates (2.2)BooleanOptionalWhether 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)IntegerOptionalThe 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)BooleanOptionalWhether or not the query byte limiter can be overiden on a per-query basis.FalseTrue
tsd.query.limits.bytes.default (2.4)IntegerOptionalA 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.0268435456
tsd.query.limits.data_points.allow_override (2.4)BooleanOptionalWhether or not the query data point limiter can be overiden on a per-query basis.FalseTrue
tsd.query.limits.data_points.default (2.4)IntegerOptionalA 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.01000000
tsd.query.limits.overrides.interval (2.4)IntegerOptionalHow often, in milliseconds, to reload the byte and data point query limiter plugin configuration.60000
tsd.query.limits.overrides.config (2.4)JSON/File PathOptionalThe path or full config of a query limit configuration with options to match on metric names.
tsd.query.multi_get.enable (2.4)BooleanOptionalWhether or not multi-get queries are enabled in conjunction with the search plugin.FalseTrue
tsd.query.multi_get.batch_size (2.4)IntegerOptionalThe number of get requests sent to storage in a single request.1024
tsd.query.multi_get.concurrent (2.4)IntegerOptionalThe number of simultaneous batches outstanding at any given time for multi-get queries.20
tsd.query.multi_get.get_all_salts (2.4)BooleanOptionalWhether 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.FalseTrue
tsd.query.skip_unresolved_tagvs (2.2)BooleanOptionalWhether 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)IntegerOptionalHow long, in milliseconds, before canceling a running query. A value of 0 means queries will not timeout.0
tsd.rollups.config (2.4)StringOptionalThe 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)BooleanOptionalWhether or not to enable rollup and pre-aggregation storage and writing.false
tsd.rollups.tag_raw (2.4)BooleanOptionalWhether 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_valuefalse
tsd.rollups.agg_tag_key (2.4)StringOptionalA special key to tag pre-aggregated data with when writing to storage_aggregate
tsd.rollups.raw_agg_tag_value (2.4)StringOptionalA 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.block_derived (2.4)BooleanOptionalWhether or not to block storing derived aggregations such as AVG and DEV .true
tsd.rpc.pluginsStringOptionalA 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)BooleanOptionalWhether or not to return errors to the Telnet style socket when writing data via put or rolluptrue
tsd.rtpublisher.enableBooleanOptionalWhether or not to enable a real time publishing plugin. If true, you must supply a valid tsd.rtpublisher.plugin class nameFalse
tsd.rtpublisher.pluginStringOptionalThe 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.enableBooleanOptionalWhether or not to enable search functionality. If true, you must supply a valid tsd.search.plugin class nameFalse
tsd.search.pluginStringOptionalThe 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.canonicalBooleanOptionalWhether 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)BooleanOptionalWhether or not a startu plugin should be loaded before the TSD.FalseTrue
tsd.startup.plugin (2.3)StringOptionalThe name of a plugin implementing the StartupPlugin interface.
tsd.storage.compaction.flush_interval (2.2)IntegerOptionalHow long, in seconds, to wait in between compaction queue flush calls10
tsd.storage.compaction.flush_speed (2.2)IntegerOptionalA 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)IntegerOptionalThe maximum number of compaction calls inflight to HBase at any given time10000
tsd.storage.compaction.min_flush_threshold (2.2)IntegerOptionalSize of the compaction queue that must be exceeded before flushing is triggered100
tsd.storage.enable_appends (2.2)BooleanOptionalWhether 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_compactionBooleanOptionalWhether or not to enable compactionsTrue
tsd.storage.fix_duplicates (2.1)BooleanOptionalWhether 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_intervalIntegerOptionalHow often, in milliseconds, to flush the data point storage write buffer1000--flush-interval
tsd.storage.get_date_tiered_compaction_startIntegerOptionalA 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.01514764800000
tsd.storage.hbase.data_tableStringOptionalName of the HBase table where data points are storedtsdb--table
tsd.storage.hbase.meta_tableStringOptionalName of the HBase table where meta data are storedtsdb-meta
tsd.storage.hbase.prefetch_meta (2.2)BooleanOptionalWhether 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)IntegerOptionalThe maximum number of rows to fetch from HBase per call to the scanner's nextRows() method.1284096
tsd.storage.hbase.tree_tableStringOptionalName of the HBase table where tree data are storedtsdb-tree
tsd.storage.hbase.uid_tableStringOptionalName of the HBase table where UID information is storedtsdb-uid--uidtable
tsd.storage.hbase.zk_basedirStringOptionalPath under which the znode for the -ROOT- region is located/hbase--zkbasedir
tsd.storage.hbase.zk_quorumStringOptionalA 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:2181localhost--zkquorum
tsd.storage.repair_appends (2.2)BooleanOptionalWhether 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)IntegerOptionalThe 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 writing8
tsd.storage.salt.buckets (2.2)IntegerOptionalThe 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)IntegerOptionalThe 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)BooleanOptionalWhether or not the data writing filter plugins are enabled.FalseTrue
tsd.timeseriesfilter.plugin (2.3)StringOptionalThe class path to a plugin that implements the WriteableDataPointFilterPlugin interface for filtering time series on writes.
tsd.storage.uid.width.metric (2.2)IntegerOptionalThe 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)IntegerOptionalThe 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)IntegerOptionalThe 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)BooleanOptionalWhether 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.TrueFalse
tsd.storage.use_otsdb_timestamp (2.4)BooleanOptionalUses the data point's timestamp for the edits in storage instead of the default now. See Date Tierd Compaction.FalseTrue
tsd.uidfilter.enable (2.3)BooleanOptionalWhether or not the UID assignment plugin filter is enabled.FalseTrue
tsd.uidfilter.plugin (2.3)StringOptionalA plugin implementing the UniqueIdFilterPlugin interface.
tsd.uid.lru.enable (2.4)BooleanOptionalChanges the UID caches from unbounded maps to LRU caches.FalseTrue
tsd.uid.lru.id.size (2.4)IntegerOptionalThe 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).50000001000000
tsd.uid.lru.name.size (2.4)IntegerOptionalThe 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).50000001000000
tsd.uid.use_mode (2.4)BooleanOptionalDetermines if the name and/or ID caches should be populated based on the tsd.mode setting.FalseTrue

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