Hawkular-Client for Go

• Introduction
  • License and copyright
• Usage
  • Installation
  • Basic usage
  • Advanced usage

Introduction

This client provides abstractions to use the Hawkular REST-endpoints. At this point, only the metrics interface is supported (standalone or part of the distribution). Real world usage can be found for example from the Kubernetes' monitoring project, Heapster and this client is bundled with the Openshift to provide metrics functionality from Hawkular-Metrics.

For further information on available functionality, see the documentation of Hawkular-Metrics.

License and copyright

   Copyright 2015-2016 Red Hat, Inc. and/or its affiliates
   and other contributors.

   Licensed under the Apache License, Version 2.0 (the "License");
   you may not use this file except in compliance with the License.
   You may obtain a copy of the License at

       http://www.apache.org/licenses/LICENSE-2.0

   Unless required by applicable law or agreed to in writing, software
   distributed under the License is distributed on an "AS IS" BASIS,
   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
   See the License for the specific language governing permissions and
   limitations under the License.

Usage

Installation

To install the package, one can use the go command of go get github.com/hawkular/hawkular-client-go.

Basic usage

For examples of usage, see the client_test.go.

Initialization

To create new instance of Hawkular, use the function NewHawkularClient and provide it with the struct Parameters

p := Parameters{Tenant: "default", Url: "http://localhost:8080"}
h := NewHawkularClient(p)

Creating and modifying metric definitions

To create new metric definitions, we need the MetricDefinition struct. The required information is Id and Type, but you can also add tags at the same time. In this example we create a metric called doc.gauge.1 and set some tags to it. You can later alter the tags by using the methods UpdateTags and DeleteTags. The Create function returns two values, first a boolean that indicates if the creation succeeded (it will return false if there’s duplicate id already) and also any potential connection or other errors.

tags := make(map[string]string)
tags["env"] = "documentation-project"

md_tags := MetricDefinition{Id: "doc.gauge.1", Tags: tags, Type: Gauge}
ok, err = c.Create(md_tags)

Fetching the definitions and tags introduces us to the principal concept around the client, which is compositional functions. We can alter the behavior of all the commands in the go-client by giving as input some modifier functions. Fetching the definitions happens with the function Definitions and as parameters we can give it some filters by including them inside the Filters function. For example to get all the Gauge definitions with given tags filter, we would do the following:

mdq, err := c.Definitions(Filters(TypeFilter(Gauge), TagsFilter(tags)))

Writing datapoints

Datapoints are written to the server inside the MetricHeader. You need to create Datapoint struct and set the time and value and embed that datapoint inside a MetricHeader struct. You can write multiple datapoints to a multiple metric ids in a single call to Write().

If the Write() happens to fail with some temporary reason (such as network issue), you can always resend the same request - old values are simply overwritten.

dp := Datapoint{Value: 1.45, Timestamp: time.Now()}

header := MetricHeader{
      ID:   "doc.gauge.1",
      Data: []Datapoint{dp},
      Type: Gauge,
}
err := c.Write([]MetricHeader{header})

For performance reasons, it is recommended to write multiple metrics in one call.

Reading datapoints

Reading datapoints has two approaches, you can either request raw metrics and datapoints that you’ve stored on the server or you can request aggregates / downsampled values. ReadRaw() returns the same datatypes as what was used when writing to the server:

metric, err := c.ReadRaw(Gauge, "doc.gauge.1")

metric should now be equal to what we sent in the previous chapter. We can change the order of returned metrics by giving OrderFilter function inside the Filters function as parameter to the ReadRaw. Default is ascending.

To request aggregated view of the stored metrics, we can use the ReadBuckets() method. The returned struct is Bucketpoint. In the following example we’ll request a single bucket of all the data, data was searched from all the metrics that have env tag with value unittest and we’re interested in calculated percentiles of values 90% and 99%.

tags := make(map[string]string)
tags["env"] = "unittest"

bp, err := c.ReadBuckets(Gauge, Filters(TagsFilter(tags), BucketsFilter(1), PercentilesFilter([]float64{90.0, 99.0})))

Advanced usage

GoDoc

Extending feature set

Client usage is based on the compositional nirvana, overloading the functions with more functions. All the functions are built on top of the Send(), which is accepting functions that are based on the Modifier type.

Base function used to build features

type Modifier func(*http.Request) error

INFO: Don’t forget to check Filter type and Endpoint type as well, which may be better startpoint for URL modifiers.