graphite

README

OpenCensus Go Graphite Exporter

The OpenCensus Graphite Stats Exporter for Go is a package that exports data to Graphite, a real-time graphing system that stores and renders graphs of received numeric time-series data on demand.

Quickstart

Import

import "contrib.go.opencensus.io/exporter/graphite"

The API of this project is still evolving. The use of vendoring or a dependency management tool is recommended.

Register the exporter

func main() {
    // Namespace is an optional part of the Options struct.
    // Stats will be reported every second by default.
    exporter, err := graphite.NewExporter(graphite.Options{Namespace: "opencensus"})
    ...
}

It is possible to set different reporting intervals by using SetReportingPeriod(), for example:

func main() {
    graphite.NewExporter(graphite.Options{Namespace: "opencensus"})
    view.RegisterExporter(exporter)
    ....
    view.SetReportingPeriod(5 * time.Second)
}

Options for the Graphite exporter

There are some options that can be defined when registering and creating the exporter. Those options are shown below:

Field	Description	Default Value
Host	Type string. The Host contains the host address for the graphite server	"127.0.0.1"
Port	Type int. The Port in which the carbon/graphite endpoint is available	2003
Namespace	Type string. The Namespace is a string value to build the metric path. It will be the first value on the path	None
ReportingPeriod	Type time.Duration. The ReportingPeriod is a value to determine the buffer timeframe in which the stats data will be sent.	1 second

Implementation Details

To feed data into Graphite in Plaintext, the following format must be used: <metric path> <metric value> <metric timestamp>.

• metric_path is the metric namespace.
• value is the value of the metric at a given time.
• timestamp is the number of seconds since unix epoch time and the time in which the data is received on Graphite.

Frequently Asked Questions

How the stats data is handled?

The stats data is aggregated into Views (which are essentially a collection of metrics, each with a different set of labels). To know more about the definition of views, check the Opencensus docs

How the path is built?

One of the main concepts of Graphite is the metric path. This path is used to aggregate and organize the measurements and generate the graphs.

In this exporter, the path is built as follows:

Options.Namespace.View.Name.Tags

• Options.Namespace: Defined in the Options object.
• View.Name: The name given to the view.
• Tags: The view tag key and values in the format key=value

For example, in a configuration where:

• Options.Namespace: 'opencensus'
• View.Name: 'video_size'
• Tags: { "name": "video1", "author": "john"}

The generated path will look like:

opencensus.video_size;name=video1;author=john

Graph visualization on Graphite

Heatmap visualization on Grafana

On Grafana it's possible to generate heatmaps based on time series bucket. To do so, it's necessary to configure the Axes, setting the Data format to Time series bucket as shown in the image below:

It's also necessary to sort the values so that Grafana displays the buckets in the correct order. For that, it's necessary to insert a SortByName(true) function on the metrics query as shown in the image below:

With this configuration, Grafana automatically identifies the bucket boundaries in the data that's being sent and generate the correct heatmap without the need of further configuration.

In the next image, it's possible to see the heatmap created from a gRPC client latency view, that can be found in the ocgrpc package as ClientRoundtripLatencyView.

The code for generating this example is not much different from the grpc example contained in the example folder. The main change is on line 45 of the client:

...
// Register the view to collect gRPC client stats.
if err := view.Register(ocgrpc.ClientRoundtripLatencyView); err != nil {
	log.Fatal(err)
}
...

Documentation

Overview

Package graphite contains a Graphite exporter that supports exporting OpenCensus views as Graphite metrics.

Example

package main

import (
	"log"
	"net/http"

	"contrib.go.opencensus.io/exporter/graphite"

	"go.opencensus.io/stats/view"
)

func main() {
	exporter, err := graphite.NewExporter(graphite.Options{})
	if err != nil {
		log.Fatal(err)
	}
	view.RegisterExporter(exporter)

	// Serve the scrape endpoint on port 9999.
	log.Fatal(http.ListenAndServe(":9999", nil))
}

Index

• type Exporter
  • func NewExporter(o Options) (*Exporter, error)
  • func (e *Exporter) ExportView(vd *view.Data)
  • func (e *Exporter) Flush()
• type Graphite
  • func NewGraphite(host string, port int) (*Graphite, error)
  • func (g *Graphite) Disconnect() (err error)
  • func (g *Graphite) SendMetric(metric Metric) error
• type Metric
  • func (m Metric) String() string
• type Options

Examples

• Package

Types

type Exporter

type Exporter struct {
	// contains filtered or unexported fields
}

Exporter exports stats to Graphite

func NewExporter

func NewExporter(o Options) (*Exporter, error)

NewExporter returns an exporter that exports stats to Graphite.

func (*Exporter) ExportView

func (e *Exporter) ExportView(vd *view.Data)

ExportView exports to the Graphite if view data has one or more rows. Each OpenCensus stats records will be converted to corresponding Graphite Metric

func (*Exporter) Flush

func (e *Exporter) Flush()

type Graphite

type Graphite struct {
	Host    string
	Port    int
	Timeout time.Duration
	Conn    io.Writer
}

Graphite is a struct that defines the relevant properties of a graphite connection

func NewGraphite

func NewGraphite(host string, port int) (*Graphite, error)

NewGraphite is a method that's used to create a new Graphite

func (*Graphite) Disconnect

func (g *Graphite) Disconnect() (err error)

Disconnect closes the Graphite.conn field

func (*Graphite) SendMetric

func (g *Graphite) SendMetric(metric Metric) error

SendMetric method can be used to just pass a metric name and value and have it be sent to the Graphite host

type Metric

type Metric struct {
	Name      string
	Value     float64
	Timestamp time.Time
}

Metric contains the metric fields expected by Graphite.

func (Metric) String

func (m Metric) String() string

String formats a Metric to the format expected bt Graphite.

type Options

type Options struct {
	// Host contains de host address for the graphite server.
	// The default value is "127.0.0.1".
	Host string

	// Port is the port in which the carbon endpoint is available.
	// The default value is 2003.
	Port int

	// Namespace is optional and will be the first element in the path.
	Namespace string

	// Tags specifies a set of default tags to attach to each metric.
	// Tags is optional and will work only for Graphite above 1.1.x.
	Tags []tag.Tag

	// OnError is the hook to be called when there is
	// an error uploading the stats or tracing data.
	// If no custom hook is set, errors are logged.
	// Optional.
	OnError func(err error)

	// MetricPathBuilder return a custom metric path
	// namespace is Options.Namespace, rowTags are the metric tags and
	// defaultTags are tags from Options.Tags
	MetricPathBuilder func(nameSpace, viewName string, rowTags, defaultTags []tag.Tag) string

	// Do not apply sanitization to periods in sanitizeRune
	//
	// According to Graphite documentation on naming hierarchy. Periods
	// should be allowed in a metric name for creating path components.
	//
	// https://graphite.readthedocs.io/en/latest/feeding-carbon.html#step-1-plan-a-naming-hierarchy
	AllowDotsDashesInNames bool
}

Options contains options for configuring the exporter.