Using the TrueSight Intelligence SDK for Java

This SDK supports local methods which can be invoked for sending data for Metrics, Measurements and Events to your TrueSight Intelligence account. The  TrueSight Intelligence SDK for Java on GitHub  contains java library, samples and documentation for using the SDK.

POST methods are currently supported for the following REST endpoints. The GET, PUT, and DELETE methods are not currently supported.

• /v1/batch/metrics
• /v1/measurements
• /v1/events

Prerequisites

You need JDK 1.8 for building the project.

To install and use the SDK (Maven)

1. Clone the repository to your local directory and create the jar file in the target folder in the same directory. The folder will also contain the javadoc for the library generated. You can now use the SDK.

   $ git clone <repository URL> 
   $ cd tsi-sdk-java
   $ mvn clean install

2. Install the local jar to the maven repository

   1. Create a folder inside the root directory of the client project (local-repo)

   2. Run the following maven command to install the jar to the directory.

      $ mvn deploy:deploy-file -DgroupId=com.bmc.truesight.saas.apiclient -DartifactId=truesight-saas-api-client -Dversion=1.0 -Durl=file:./local-repo/ -DrepositoryId=local-repo -DupdateReleaseInfo=true -Dfile=<path-to-the-jar-file>

3. Add the required dependency to client application POM.

   1. Add the maven repository details to the client pom.

      <repositories>
         <repository>
            <id>local-repo</id>
            <url>file:///${project.basedir}/local-repo</url>
         </repository>
      </repositories>

   2. Add the dependency to the POM file.

      <dependency>
         <groupId>com.bmc.truesight.saas.apiclient</groupId>
         <artifactId>truesight-saas-api-client</artifactId>
         <version>1.0</version>            
      </dependency>

Basic authentication

The SDK needs to be authenticated using HTTP Basic Authentication. You need to provide a TrueSightCredentials object while creating the TruesightAPIClient object, which will be used for all the API calls that are made using this particular client. The SDK does not restrict the number of client objects that can be created.

Use your email-ID used for registering with Intelligence and the API-token for your account for creating the TrueSightCredentials object.

public TrueSightCredentials(String email, String token)

Sample logger configuration

This SDK uses logging facade sfl4j. You can configure any of the concrete logger implementations to get the SDK logs. If none of them is specified, the logs will be ignored. Use the below logging configuration sample while using logback.

<?xml version="1.0" encoding="UTF-8"?>
<configuration>
   <appender name="fileAppender" class="ch.qos.logback.core.FileAppender">
      <file>logfile-path</file>
      <append>true</append>
      <encoder>
         <pattern>%d [%thread] %-5level %logger{35} - %msg%n</pattern>
      </encoder>
   </appender>
      <root level="TRACE">
         <appender-ref ref="fileAppender" />
      </root>
</configuration>

Change the 'logfile-path' as required.

Logging dependencies required for logback

<dependency>
   <groupId>ch.qos.logback</groupId>
   <artifactId>logback-classic</artifactId>
   <version>${logback.version}</version>
</dependency>
       
<dependency>
   <groupId>ch.qos.logback</groupId>
   <artifactId>logback-core</artifactId>
   <version>${logback.version}</version>
</dependency>

Retry configuration

This SDK supports retry of the API call when an IOException is exception, and the retry count is set to 3. You can configure the retry delay by setting the retryDelay parameter during the creation of the TrueSightAPIClient object. If the value is not provided, the default value of 30 seconds is use. If a value below 30 seconds is provided the default value of 30 seconds will be used.

public TrueSightAPIClient(TrueSightCredentials creds, int retryDelay)

public TrueSightAPIClient(TrueSightCredentials creds)

Sample code

Sample code snippets are provided in the repository/samples. Samples is a separate project with its own POM file. Use the following procedure to build the project and refer to the javadoc created during build for additional reference on using the SDK.

Sample Programs

This GitHub project contains SDK samples which can be built separately. For more information, see the sample program on GitHub .

Steps to run samples

1. Build and install the parent SDK from the root directory.
      $mvn clean install 
2. Once build is successful, traverse to the samples folder and build the same.
      $mvn clean install

Provide your <email-ID> and <api-token> before building the samples for successfully authenticating the API when invoking the available SDK methods.

After you build the main SDK project, the SDK jar is created and placed in the maven local repository. Hence, when you refer to the same SDK jar in the sample pom, maven picks up the jar from the local repository. You must make changes to the pom.xml in the samples folder for any changes in the master jar.

Samples for the following operations which are supported by the SDK have been provided:

• Creating Metrics (bulk)
• Adding Measurements(bulk)
• Creating Events (bulk)

The values used are dummy values, you can change them if required. While creating metrics, the call can fail if the metric already exists.