Sentinel can be easily installed using docker. The docker compose file is provided for convenience.

Download sentinel

git clone

Now that you have the source code, you can either use docker to start sentinel, or you can build and package from source.

Using docker-compose

Change into 'docker-support' subfolder under the root folder of the git repo clone. Then execute docker-compose as shown below:

docker-compose up

This command brings all the dependencies needed for sentinel:

  • Grafana - grafana/grafana:4.6.1
  • InfluxDB - influxdb:1.2.4-alpine
  • Java8 - rolvlad/alpine-oraclejdk8
  • Kafka - spotify/kafka:latest

The sentinel framework allows certain parameters to be set via environment variables. An example environment block is shown next:

      - STREAM_ADMINPASS=pass1234
      - STREAM_DBENDPOINT=influxdb:8086
      - STREAM_ACCESSURL=localhost:8083
      - STREAM_DBTYPE=influxdb
      - ZOOKEEPER_ENDPOINT=kafka:2181
      - KAFKA_ENDPOINT=kafka:9092
      - INFLUX_URL=http://influxdb:8086
      - INFLUX_URL_GRAFANA=http://localhost:8086
      - GRAFANA_URL=http://grafana:3000
      - GRAFANA_ADMIN=admin
      - GRAFANA_PASSWORD=1ccl@b2017
      - INFLUX_USER=root
      - INFLUX_PASSWORD=pass1234
      - SENTINEL_DB_ENDPOINT=/data/sentinel.db
      - ADMIN_TOKEN=somevalue
      - DASHBOARD_TITLE=elastest
      - DASHBOARD_ENDPOINT=localhost:3000

Currently, sentinel works only with InfluxDB time-series backend. Support for emerging alternatives such as Timescaledb is planned and will be added very soon.

  • STREAM_ADMINUSER - the admin user for InfluxDB
  • STREAM_ADMINPASS - choose a secure password for the just declared admin user
  • STREAM_DBENDPOINT - the API endpoint of InfluxDB service, typically it is at port 8086
  • STREAM_ACCESSURL - the InfluxDB UI URL that sentinel will return back to users, if your service is running on an externally accessible node, change localhost with the FQDN or the IP of the node.
  • ZOOKEEPER_ENDPOINT - the endpoint of the Zookeeper service
  • KAFKA_ENDPOINT - the endpoint where Kafka cluster is reachable by sentinel
  • TOPIC_CHECK_INTERVAL - defined in milliseconds, denotes the time interval between Kafka Topic query by topic manager in Sentinel.

The next 8 variables are for prepopulating Grafana dashboard using the InfluxDB credentials and the dashboard.json file located in the source repository.

  • INFLUX_URL - address where InfluxDB API service can be reached
  • INFLUX_GRAFANA_URL - the InfluxDB URL as would have been entered by an user if s/he was using the admin dashboard
  • GRAFANA_URL - address where the Grafana service can be accessed
  • GRAFANA_ADMIN - the admin user that should be created
  • GRAFANA_PASSWORD - the desired admin account password for the Grafana dashboard
  • INFLUX_USER - the user account in InfluxDB to be used in Grafana
  • INFLUX_PASSWORD - the account password used in Grafana while setting up the DB account
  • SENTINEL_DB_ENDPOINT - the location of the sqlite db file so that preconfigured user, monitoring space and series entries are created for ElasTest services to start using sentinel monitoring seamlessly

The last 3 fields are to configuring sentinel admin account and the dashboard rendering by the service.

  • DASHBOARD_TITLE - the title for the Grafana embedded dashboard
  • DASHBOARD_ENDPOINT - the Grafana service url from which the dashboard is embedded as iframe by sentinel

Configuring Kafka container

The kafka container allows certain parameters to be set via environment block.

      - ADVERTISED_PORT=9092
      - ADVERTISED_HOST=kafka

Care must be taken in defining ADVERTISED_HOST value. The best solution is to provide a FQDN or a public IP if Kafka is to be accessed by external processes which will be the most common use-case of sentinel. Setting an incorrect value of this parameter may leave your kafka cluster unreachable for external services, or even sentinel process running in a container.

Our recommendation is to setup kafka cluster is a separate node entirely, and configure KAFKA_ENDPOINT parameter for sentinel as a FQDN string.

Install from source

Sentinel framework is written in Java and requires Oracle Java 8 for proper working. OpenJDK 8 should also work but the codebase has not been tested with openJDK 8.


  • Maven 3.0.5 and higher
  • Oracle Java 8


mvn clean package

The self-contained jar file is created under ./target/ folder. Unless the pom file was changed, the self contained jar file is named sentinel-0.1.jar

To execute, simply run the jar as follows -

$ java -jar /path/to/jar/sentinel-0.1.jar

The above assumes that the file is in the classpath, or in the same folder as the jar file. In case the file is kept some other location, please use the following command instead -

$ java -jar /path/to/jar/sentinel-0.1.jar --spring.config.location=/path/to/config/

Configuration options

All application configuration is provided via file. A sample file content is listed below.

# stream.db.type=postgres
# stream.db.endpoint=localhost:5432
# stream.db.adminuser=postgres
# stream.db.adminpass=postgres

Many of the entries in the file are self-explanatory. A few non-obvious ones are explained next -

  • server.port - on what port number sentinel APIs are accessible
  • displayexceptions - set this to true if you want to include exceptions full trace in the log outputs
  • sentinel.db.type - currently only sqlite is supported
  • sentinel.db.endpoint - relative or absolute path of the DB file
  • topic.check.interval - value in milliseconds indicating the gap between checking list of monitoring spaces for subscription
  • stream.dbtype - the time series DB where the monitor stream will be stored, currently only influxdb is supported
  • stream.accessurl - the url /IP where the InfluxDB admin UI is accessible to the user (if enabled), this should be an externally accessible FQDN ideally
  • stream.adminuser - the name of the admin account in the stream DB (here influxdb), this value is meaningful only when authentication and authorization is enabled in InfluxDB, otherwise the values are not enforced by the DB
  • admin.token - this is the master token using which a new user account can be created within sentinel, this value should be accessible only to the administrators of the system, or within the API engine in case you wish to support self registration by general public.
  • series.format.cache.size - number of series signatures to be maintained in the in-memory cache of sentinel