mackerel

package module
v1.5.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Jun 17, 2020 License: BSD-3-Clause Imports: 23 Imported by: 0

README

mackerelexporter-go

This is OpenTelemetry Meter Exporter for Mackerel.

GoDev Actions Status

Installation

If you use Go Modules, then you just import OpenTelemetry API and the exporter. Otherwise you can install manually.

$ go get -u go.opentelemetry.io/otel
$ go get -u github.com/lufia/mackerelexporter-go

After installation, you can start to write a program. There is the example at the Example section of this document.

Description

Hosts

Mackerel manages hosts database in the organization. Official mackerel-agent installed to the host, such as compute instance, bare metal or local machine collects host informations from resources provided by operating system. The exporter won't access external resources. Instead host informations will be generated from labels attached to the metrics.

For example, the host identifier that is unique in the organization refers the label host.id. Similarly the host name refers the label host.name. The exporter handles metrics attached these labels as host metric in Mackerel.

Services

Like as hosts, both Service and Role are made from labels. Label service.namespace is mapped to Service, and the label service.name is mapped Role.

Where post are metrics?

The metrics with a label below will post as Host Metric.

  • host.id

Also the metrics with these all labels below will post as Host Metric.

  • service.namespace
  • service.name
  • service.instance.id

The metric with a labels below will post as Service Metric.

  • service.namespace
Graph Definitions

The exporter will create the Graph Definition on Mackerel if needed. Most cases it creates automatically based from recorded metric name. However you might think to want to customize the graph by wildcards in the graph name. In this case you can configure the exporter to use pre-defined graph name with WithHints() option.

The hint is the name composed by deleted only the end of the metric name, and it can be replaced each elements by wildcard, # or *. For example the hint http.handlers.# is valid for the metric http.handlers.index.count.

Special case. The exporter will append .min, .max and .percentile_xx implicitly to the end of the name for measure metric in OpenTelemetry. Thus count of elements of the hint will be same as the recorded metric name.

The push/pull mode

If you give InstallNewPipeline a valid API key with WithAPIKey option, the exporter runs as the push mode. In this mode, the exporter sends host- and service-metrics to Mackerl automatically. Otherwise the exporter runs as the pull mode. The pull mode dont' send any metrics. Instead, InstallNewPipeline returns a handler function for net/http. In pull mode, the handler function responds host metrics to the HTTP client, and it don't include any service metrics.

Example

import (
	"context"
	"log"
	"net/http"
	"os"
	"runtime"
	"time"

	"go.opentelemetry.io/otel/api/global"
	"go.opentelemetry.io/otel/api/kv"
	"go.opentelemetry.io/otel/api/metric"
	"go.opentelemetry.io/otel/api/unit"

	"github.com/lufia/mackerelexporter-go"
)

var (
	hints = []string{
		"storage.#",
	}
)

func main() {
	apiKey := os.Getenv("MACKEREL_APIKEY")
	pusher, handler, err := mackerel.InstallNewPipeline(
		mackerel.WithAPIKey(apiKey),
		mackerel.WithHints(hints),
		mackerel.WithResource([]kv.KeyValue{
			mackerel.KeyHostID.String("10-1-2-241"),
			mackerel.KeyHostName.String("localhost"),
			mackerel.KeyServiceNS.String("example"), // service name
			mackerel.KeyServiceName.String("app"),   // role name
		}),
	)
	if err != nil {
		log.Fatal(err)
	}
	defer pusher.Stop()
	if handler != nil {
		http.HandlerFunc("/metrics", handler)
		go http.ListenAndServe(":8080", nil)
	}

	meter := global.MeterProvider().Meter("example")
	meterMust := metric.Must(meter)
	firestoreRead := meterMust.NewInt64Counter("storage.firestore.read")
	var (
		memAllocs      metric.Int64ValueObserver
		memTotalAllocs metric.Int64ValueObserver
	)
	memStats := meterMust.NewBatchObserver(func(ctx context.Context, result metric.BatchObserverResult) {
		var m runtime.MemStats
		runtime.ReadMemStats(&m)
		result.Observe(nil,
			memAllocs.Observation(int64(m.Alloc)),
			memTotalAllocs.Observation(int64(m.TotalAlloc)),
		)
	})
	memAllocs = memStats.NewInt64ValueObserver("runtime.memory.alloc", metric.WithUnit(unit.Bytes))
	memTotalAllocs = memStats.NewInt64ValueObserver("runtime.memory.total_alloc", metric.WithUnit(unit.Bytes))

	ctx := context.Background()
	additionalLabels := []kv.KeyValue{
		mackerel.KeyServiceVersion("v1.0"),
	}
	firestoreRead.Add(ctx, 100, additionalLabels)

	v := firestoreRead.Bind(additionalLabels)
	v.Add(ctx, 20)

	m := firestoreRead.Measurement(1)
	meter.RecordBatch(ctx, additionalLabels, m)
	time.Sleep(2 * time.Minute)
}

Documentation

Index

Examples

Constants

This section is empty.

Variables

These keys are handled for creating hosts, graph-defs, or metrics.

Functions

func InstallNewPipeline

func InstallNewPipeline(opts ...Option) (*push.Controller, http.HandlerFunc, error)

InstallNewPipeline instantiates a NewExportPipeline and registers it globally.

Example (PullMode)
pusher, handler, err := mackerel.InstallNewPipeline(
	mackerel.WithQuantiles([]float64{0.99, 0.90, 0.85}),
	mackerel.WithResource(
		mackerel.KeyHostID.String("1-2-3-4"),
		mackerel.KeyHostName.String("localhost"),
		mackerel.KeyServiceNS.String("service"),
		mackerel.KeyServiceName.String("role"),
	),
)
if err != nil {
	log.Fatal(err)
}
defer pusher.Stop()

http.HandleFunc("/metrics", handler)
Output:

Example (PushMode)
apiKey := os.Getenv("MACKEREL_APIKEY")
pusher, _, err := mackerel.InstallNewPipeline(
	mackerel.WithAPIKey(apiKey),
	mackerel.WithQuantiles([]float64{0.99, 0.90, 0.85}),
	mackerel.WithResource(
		mackerel.KeyHostID.String("1-2-3-4"),
		mackerel.KeyHostName.String("localhost"),
		mackerel.KeyServiceNS.String("service"),
		mackerel.KeyServiceName.String("role"),
	),
)
if err != nil {
	log.Fatal(err)
}
defer pusher.Stop()
Output:

func NewExportPipeline

func NewExportPipeline(opts ...Option) (*push.Controller, http.HandlerFunc, error)

NewExportPipeline sets up a complete export pipeline.

Types

type Exporter

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

Exporter is a stats exporter that uploads data to Mackerel.

func NewExporter

func NewExporter(opts ...Option) (*Exporter, error)

NewExporter creates a new Exporter.

func (*Exporter) Export

func (e *Exporter) Export(ctx context.Context, a export.CheckpointSet) error

Export exports the provide metric record to Mackerel.

func (*Exporter) Handler added in v1.3.0

func (e *Exporter) Handler() http.Handler

type Option

type Option func(*options)

Option is function type that is passed to NewExporter function.

func WithAPIKey

func WithAPIKey(apiKey string) Option

WithAPIKey sets the Mackerel API Key.

func WithBaseURL

func WithBaseURL(baseURL *url.URL) Option

WithBaseURL sets base URL for Mackerel API.

func WithDebug added in v1.2.0

func WithDebug() Option

WithDebug enables logs for debugging.

func WithHints

func WithHints(hints []string) Option

WithHints sets hints for decision the name of the Graph Definition.

func WithQuantiles

func WithQuantiles(quantiles []float64) Option

WithQuantiles sets quantiles for recording measure metrics. Each quantiles must be unique and its precision must be greater or equal than 0.01.

func WithResource added in v1.2.0

func WithResource(tags ...kv.KeyValue) Option

WithResource sets resource tags.

Notes

Bugs

  • currently, FindHosts supports seraching by CustomIdentifier only.

  • The pull mode don't support to post the service metrics.

Directories

Path Synopsis
cmd
internal
tag

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL