Skip to content

Latest commit

 

History

History
172 lines (130 loc) · 6.25 KB

README.md

File metadata and controls

172 lines (130 loc) · 6.25 KB
Raw

influxdb-java

Build Status codecov.io Issue Count

This is the Java Client library which is only compatible with InfluxDB 0.9 and higher. Maintained by @majst01.

To connect to InfluxDB 0.8.x you need to use influxdb-java version 1.6.

This implementation is meant as a Java rewrite of the influxdb-go package. All low level REST Api calls are available.

Usages

Basic Usages:

InfluxDB influxDB = InfluxDBFactory.connect("http://172.17.0.2:8086", "root", "root");
String dbName = "aTimeSeries";
influxDB.createDatabase(dbName);

BatchPoints batchPoints = BatchPoints
				.database(dbName)
				.tag("async", "true")
				.retentionPolicy("autogen")
				.consistency(ConsistencyLevel.ALL)
				.build();
Point point1 = Point.measurement("cpu")
					.time(System.currentTimeMillis(), TimeUnit.MILLISECONDS)
					.addField("idle", 90L)
					.addField("user", 9L)
					.addField("system", 1L)
					.build();
Point point2 = Point.measurement("disk")
					.time(System.currentTimeMillis(), TimeUnit.MILLISECONDS)
					.addField("used", 80L)
					.addField("free", 1L)
					.build();
batchPoints.point(point1);
batchPoints.point(point2);
influxDB.write(batchPoints);
Query query = new Query("SELECT idle FROM cpu", dbName);
influxDB.query(query);
influxDB.deleteDatabase(dbName);

Note : If you are using influxdb < 1.0.0, you should use 'default' instead of 'autogen'

If your application produces only single Points, you can enable the batching functionality of influxdb-java:

InfluxDB influxDB = InfluxDBFactory.connect("http://172.17.0.2:8086", "root", "root");
String dbName = "aTimeSeries";
influxDB.createDatabase(dbName);

// Flush every 2000 Points, at least every 100ms
influxDB.enableBatch(2000, 100, TimeUnit.MILLISECONDS);

Point point1 = Point.measurement("cpu")
					.time(System.currentTimeMillis(), TimeUnit.MILLISECONDS)
					.addField("idle", 90L)
					.addField("user", 9L)
					.addField("system", 1L)
					.build();
Point point2 = Point.measurement("disk")
					.time(System.currentTimeMillis(), TimeUnit.MILLISECONDS)
					.addField("used", 80L)
					.addField("free", 1L)
					.build();

influxDB.write(dbName, "autogen", point1);
influxDB.write(dbName, "autogen", point2);
Query query = new Query("SELECT idle FROM cpu", dbName);
influxDB.query(query);
influxDB.deleteDatabase(dbName);

Note that the batching functionality creates an internal thread pool that needs to be shutdown explicitly as part of a graceful application shut-down, or the application will not shut down properly. To do so simply call: influxDB.close()

Also note that any errors that happen during the batch flush won't leak into the caller of the write method. By default, any kind of errors will be just logged with "SEVERE" level.

If you need to be notified and do some custom logic when such asynchronous errors happen, you can add an error handler with a BiConsumer<Iterable<Point>, Throwable> using the overloaded enableBatch method:

// Flush every 2000 Points, at least every 100ms
influxDB.enableBatch(2000, 100, TimeUnit.MILLISECONDS, Executors.defaultThreadFactory(), (failedPoints, throwable) -> { /* custom error handling here */ });

Advanced Usages:

Gzip's support (version 2.5+ required):

influxdb-java client doesn't enable gzip compress for http request body by default. If you want to enable gzip to reduce transfer data's size , you can call:

influxDB.enableGzip()

UDP's support (version 2.5+ required):

influxdb-java client support udp protocol now. you can call followed methods directly to write through UDP.

public void write(final int udpPort, final String records);
public void write(final int udpPort, final List<String> records);
public void write(final int udpPort, final Point point);

note: make sure write content's total size should not > UDP protocol's limit(64K), or you should use http instead of udp.

chunking support (version 2.6+ required, unreleased):

influxdb-java client now supports influxdb chunking. The following example uses a chunkSize of 20 and invokes the specified Consumer (e.g. System.out.println) for each received QueryResult

Query query = new Query("SELECT idle FROM cpu", dbName);
influxDB.query(query, 20, queryResult -> System.out.println(queryResult));

Other Usages:

For additional usage examples have a look at InfluxDBTest.java

Version

The latest version for maven dependence:

<dependency>
  <groupId>org.influxdb</groupId>
  <artifactId>influxdb-java</artifactId>
  <version>2.5</version>
</dependency>

For version change history have a look at ChangeLog.

Build Requirements

  • Java 1.8+
  • Maven 3.0+
  • Docker daemon running

Then you can build influxdb-java with all tests with:

$ mvn clean install

If you don't have Docker running locally, you can skip tests with -DskipTests flag set to true:

$ mvn clean install -DskipTests=true

If you have Docker running, but it is not at localhost (e.g. you are on a Mac and using docker-machine) you can set an optional environment variable INFLUXDB_IP to point to the correct IP address:

$ export INFLUXDB_IP=192.168.99.100
$ mvn test

For convenience we provide a small shell script which starts a influxdb server locally and executes mvn clean install with all tests inside docker containers.

$ ./compile-and-test.sh

Publishing

This is a link to the sonatype oss guide to publishing. I'll update this section once the jira ticket is closed and I'm able to upload artifacts to the sonatype repositories.