/atsd-api-java

Axibase Time Series Database API Client for Java

Primary LanguageJavaApache License 2.0Apache-2.0

ATSD Java Client

Travis Codebeat codecov Maven central

Table of Contents

Overview

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

Get started by importing the Java Client with Maven:

<dependency>
  <groupId>com.axibase</groupId>
  <artifactId>atsd-api-java</artifactId>
  <version>1.0.8</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.

REST API

The REST API allows you to insert and retrieve data from the database using HTTP requests.

Series

  • Series: query
    Retrieves time series objects for the specified metric, entity, tags, and date range. Applies common time series transformations including aggregation, interpolation, downsampling etc.

  • Series: insert
    Inserts a timestamped array of numbers for a given series identified by metric, entity, and series tags.

  • Series: insert CSV
    Inserts series values for the specified entity and series tags in CSV format.

Properties

Alerts

Meta API

The Meta API allows you to query metadata for metrics, entities, and entity groups in the database.

Metrics

Entities

  • Entity: get
    Retrieves fields and tags describing the specified entity.

  • Entity: update
    Updates fields and tags of the specified entity.

  • Entity: create or replace
    Creates an entity with specified fields and tags or replaces the fields and tags of an existing entity.

  • Entity: delete
    Deletes the specified entity and removes the entity from any entity groups it belongs to.

  • Entity: metrics
    Retrieves a list of metrics collected by the entity.

Entity Groups

Installing Java Client

Prerequisites:

Installing ATSD Java Client via Maven is recommended. Build the ATSD Java Client with Maven after cloning the GitHub code.

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-1.0.8.jar:dependency/*" -Daxibase.tsd.api.client.properties=./client.properties com.axibase.tsd.example.AtsdClientWriteExample

Examples

Client Configuration

-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();

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
                false // enableGzipCompression
        );
        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();

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());
            }
        }