Plugins

OpenTSDB 2.0 introduced a plugin framework, allowing varous contributors to quickly and easily customize their TSDs. This document gives you an overview of the plugin system and will link to some available implementations.

General

Plugins are loaded at run time by a TSD or command line utility. Once the program or daemon is running, plugin configurations cannot be changed. You must restart the program for changes to take effect.

Plugins are JAR files that must be downloaded to a directory accessible by OpenTSDB. Once a directory is created, it must be specified in the opentsdb.conf config file via the tsd.core.plugin_path property. If the plugin has dependency JARs that were not compiled into the plugin and are not located in the standard class path, they must be copied to this plugin directory as well.

Once the JARs are in place, they must be selected in the configuration file for the type of plugin specified. Usually this will be the fully qualified Java class name such as "net.opentsdb.search.ElasticSearch". Each plugin should have an "enabled" property as well that must be set to true for the plugin to be loaded. Plugins may also have configuration settings that must be added to the opentsdb.conf file before they can operate properly. See your plugin's documentation. See Configuration for details.

When starting a TSD or CLI tool, a number of errors may prevent a successful launch due to plugin issues. If something happens you should see an exception in the logs related to a plugin. Some things to troubleshoot include:

• Make sure the tsd.core.plugin_path is configured
• Check that the path is readable for the user OpenTSDB is running under, i.e. check permissions
• Check for typos in the config file. Case matters for plugin names.
• The plugin may not have access to the dependencies it needs. If it has dependencies that are not included with OpenTSDB or packaged into it's own JAR you need to drop the dependencies in the plugin path.
• The plugin may be missing configuration settings required for it to be initialized. Read the docs and see if anything is missing.

Serializers

The HTTP API provides a plugin interface for serializing and deserializing data in formats other than the default JSON formats. These plugins do not require a plugin name or enable flag in the configuration file. Instead simply drop the plugin in the plugin directory and it will be loaded when the TSD is launched. More than one serializer plugin can be loaded on startup. Serializer plugins may require configuration properties, so check the documentation before using them.

Startup and Service Discovery

OpenTSDB is sometimes used within environments where additional initialization or registration is desired beyond what OpenTSDB typically can do out of the box. Startup plugins can be enabled which will be called when OpenTSDB is initializing, when it is ready to serve traffic, and when it is being shutdown. The tsd.startup.plugin property can be used to specify the plugin class and tsd.startup.enable will instruct OpenTSDB to attempt to load the startup plugin.

Search

OpenTSDB can emit meta data and annotations to a search engine for complex querying. A single search plugin can be enabled for a TSD to push data or execute queries. The tsd.search.plugin property lets you select a search plugin and tsd.search.enable will start sending data and queries. Search plugins will be loaded by TSDs and select command line tools such as the UID Manager tool.

Real Time Publishing

Every data point received by a TSD can be sent to another destination for real time processing. One plugin for this type may be enabled at a time. The tsd.rtpublisher.plugin property lets you select a plugin and tsd.rtpublisher.enable will start sending data.

RPC

Natively, OpenTSDB supports ingesting data points via Telnet or HTTP. The RPC plugin interface allows users to implement and choose alternative protocols such as Protobufs, Thrift, Memcache or any other means of storing information. More than one plugin can be loaded at a time via the tsd.rpc.plugins or tsd.http.rpc.plugins` configuration property. Simply list the class name of any RPC plugins you wish to load, separated by a comma if you have more than one. RPC plugins are only initialized when running a TSD.

Storage Exception Handler

If a write to the underlying storage layer fails for any reason, an exception is raised. When this happens, if a a storage exception handler plugin is enabled, the data points that couldn't be written can be retried at a later date by spooling to disk or passing to a messaging system. (v2.2)

HTTP RPC Plugin

This is an interface used to implement additional HTTP API endpoints for OpenTSDB. (v2.2)