Axibase Time Series Database API Client for Java
Java Shell
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Failed to load latest commit information.
src
.gitignore
LICENSE
README.md
circle.yml
make-bin.sh
pom.xml

README.md

CircleCI codebeat badge codecov

Axibase Time Series Database Client for Java

The ATSD Client for Java enables Java developers to build reporting, analytical, and alerting applications that read and write data and metadata from the Axibase Time Series Database.

Get started by downloading the zip file from GitHub or by importing this API client with Maven:

        <dependency>
            <groupId>com.axibase</groupId>
            <artifactId>atsd-api-java</artifactId>
            <version>0.5.14</version>
        </dependency>

Implemented Methods

The ATSD Client for Java provides an easy-to-use client for interfacing with ATSD metadata and data REST API services. It has the ability to read and write time series values, statistics, properties, alerts, and messages.

  • Data API

    • Series
      • QUERY
      • INSERT
      • CSV INSERT
    • Properties
      • QUERY
      • INSERT
    • Alerts
      • QUERY
    • Alerts History
      • QUERY
  • Metadata API

    • Metrics
      • Get Metrics
      • Get Metric
      • Create/Update Metric
      • Delete Metric
      • Get Entities and Series Tags for Metric
    • Entities
      • Get Entities
      • Get Entity
      • Create/Update Entity
      • Delete Entity
      • Get Metrics for Entity
    • Entity Groups
      • Get Entity Groups
      • Get Entity Group
      • Create/Update Entity Group
      • Delete Entity Group
      • Entities for Entity Group
      • Add Entities to Entity Group
      • Set (Replace) Entities in Entity Group
      • Delete Entities from Entity Group

Getting Started

Before you begin installing the ATSD Client for Java, you need to install a copy of the Axibase Time Series Database. Download the latest version of ATSD that is available for your Linux distribution.

Minimum requirements for running the ATSD Client: Java 1.7+.

We recommend installing the ATSD Client for Java by using Maven. Build the ATSD Client with Maven after checking out the code from GitHub.

git clone https://github.com/axibase/atsd-api-java.git
cd atsd-api-java
mvn clean dependency:copy-dependencies compile jar:jar
cd target
java -cp "atsd-api-java-0.5.14.jar:dependency/*" -Daxibase.tsd.api.client.properties=./client.properties com.axibase.tsd.example.AtsdClientWriteExample

Examples

See:

Client Configuration

Option 1

Use -Daxibase.tsd.api.client.properties=./client.properties:

        ClientConfiguration clientConfiguration = ClientConfigurationFactory
            .createInstance()
            .createClientConfiguration();
        HttpClientManager httpClientManager = new HttpClientManager(clientConfiguration);
        DataService dataService = new DataService(httpClientManager);
        MetaDataService metaDataService = new MetaDataService(httpClientManager);

client.properties example:

        axibase.tsd.api.server.name=atsd_server
        axibase.tsd.api.server.port=8080
        #axibase.tsd.api.server.port=8443
        #axibase.tsd.api.protocol=https
        #axibase.tsd.api.ssl.errors.ignore=true
        axibase.tsd.api.username=username
        axibase.tsd.api.password=pwd

Usage:

        AtsdClientWriteExample atsdClientWriteExample = new AtsdClientWriteExample();
        atsdClientWriteExample.configure();
        atsdClientWriteExample.writeData();
        atsdClientWriteExample.printData();

Option 2

Use pure Java:

        ClientConfigurationFactory configurationFactory = new ClientConfigurationFactory(
                "http", "atsd_server", 8080, // serverPort
                "/api/v1", "/api/v1",
                "username", "pwd",
                3000, // connectTimeoutMillis
                3000, // readTimeoutMillis
                600000, // pingTimeout
                false, // ignoreSSLErrors
                false // skipStreamingControl
        );
        ClientConfiguration clientConfiguration = configurationFactory
            .createClientConfiguration();
        System.out.println("Connecting to ATSD: " + clientConfiguration.getMetadataUrl());
        HttpClientManager httpClientManager = new HttpClientManager(clientConfiguration);

        GenericObjectPoolConfig objectPoolConfig = new GenericObjectPoolConfig();
        objectPoolConfig.setMaxTotal(5);
        objectPoolConfig.setMaxIdle(5);

        httpClientManager.setObjectPoolConfig(objectPoolConfig);
        httpClientManager.setBorrowMaxWaitMillis(1000);

        DataService dataService = new DataService(httpClientManager);
        MetaDataService metaDataService = new MetaDataService(httpClientManager);

Usage:

        AtsdClientWriteExample atsdClientWriteExample = new AtsdClientWriteExample();
        atsdClientWriteExample.pureJavaConfigure();
        atsdClientWriteExample.writeData();
        atsdClientWriteExample.printData();

Option 3

Use Spring. See example-beans.xml:

        <bean id="example" class="com.axibase.tsd.example.AtsdClientWriteExample"/>
        <bean id="dataService" class="com.axibase.tsd.client.DataService"/>
        <bean id="metaDataService" class="com.axibase.tsd.client.MetaDataService"/>
        <bean id="httpClientManager" class="com.axibase.tsd.client.HttpClientManager"/>
        <bean id="genericObjectPoolConfig"
            class="org.apache.commons.pool2.impl.GenericObjectPoolConfig">
            <property name="maxTotal" value="3"/>
        </bean>
        <bean id="clientConfiguration"
            class="com.axibase.tsd.model.system.ClientConfiguration">
            <constructor-arg name="url" value="http://atsd_server:8080/api/v1"/>
            <constructor-arg name="username" value="username"/>
            <constructor-arg name="password" value="pwd"/>
        </bean>

Usage:

            ApplicationContext context =
                new ClassPathXmlApplicationContext("example-beans.xml");
            AtsdClientWriteExample example =
                (AtsdClientWriteExample)context.getBean("example");
            example.writeData();
            example.printData();

Metadata Processing

        String metricExample = "jvm_memory_used_percent";
        Metric metric = metaDataService.retrieveMetric(metricExample);
        if (metric == null) {
            System.out.println("Unknown metric: " + metricExample);
            return;
        }
        List<EntityAndTags> entityAndTagsList = metaDataService
            .retrieveEntityAndTags(metric.getName(), null);
        System.out.println("===Metric MetaData===");
        System.out.println("Metric: " + metric);
        for (EntityAndTags entityAndTags : entityAndTagsList) {
            String entityName = entityAndTags.getEntityName();
            System.out.println("\n===Entity MetaData===");
            System.out.println("Entity: " + entityName);
            Map<String, String> tags = entityAndTags.getTags();
            System.out.println("===Tags===");
            for (Map.Entry<String, String> tagAndValue : tags.entrySet()) {
                System.out.println("\t" + tagAndValue.getKey() + " : " + tagAndValue.getValue());
            }
        }

Data Queries

        GetSeriesQuery command = new GetSeriesQuery(entityName, metric.getName(), tags,
            System.currentTimeMillis() - 3600, System.currentTimeMillis());
        command.setAggregateMatcher(
            new SimpleAggregateMatcher(new Interval(1, IntervalUnit.MINUTE),
            Interpolate.NONE,
            AggregateType.DETAIL));
        List<GetSeriesResult> getSeriesResults =
            dataService.retrieveSeries(command);
        for (GetSeriesResult getSeriesResult : getSeriesResults) {
            System.out.println("Time Series Key: "
                + getSeriesResult.getTimeSeriesKey());
            List<Series> data = getSeriesResult.getData();
            for (Series series : data) {
                long ts = series.getT();
                System.out.println(toISODate(ts) + "\t" + series.getV());
            }
        }