This implements a basic Spectator library for instrumenting Go applications. It consists of a thin client designed to send metrics through spectatord.

This library currently targets the latest two stable versions of Go.

There is one language feature used in the project which requires at least 1.21 - the log/slog structured logging library.

package main

import (
	"github.com/Netflix/spectator-go/v2/spectator"
	"github.com/Netflix/spectator-go/v2/spectator/meter"
	"strconv"
	"time"
)

type Server struct {
	registry       spectator.Registry
	requestCountId *meter.Id
	requestLatency *meter.Timer
	responseSizes  *meter.DistributionSummary
}

type Request struct {
	country string
}

type Response struct {
	status int
	size   int64
}

func (s *Server) Handle(request *Request) (res *Response) {
	start := time.Now()

	// initialize response
	res = &Response{200, 64}

	// Update the counter with dimensions based on the request.
	tags := map[string]string{
		"country": request.country,
		"status":  strconv.Itoa(res.status),
	}
	requestCounterWithTags := s.requestCountId.WithTags(tags)
	counter := s.registry.CounterWithId(requestCounterWithTags)
	counter.Increment()

	// ...
	s.requestLatency.Record(time.Since(start))
	s.responseSizes.Record(res.size)
	return
}

func newServer(registry spectator.Registry) *Server {
	return &Server{
		registry,
		registry.NewId("server.requestCount", nil),
		registry.Timer("server.requestLatency", nil),
		registry.DistributionSummary("server.responseSizes", nil),
	}
}

func getNextRequest() *Request {
	// ...
	return &Request{"US"}
}

func main() {
	commonTags := map[string]string{"nf.platform": "my_platform", "process_name": "my_process"}
	// if desired, replace the logger with a custom one, using the third parameter here:
	config, _ := spectator.NewConfig("", commonTags, nil)

	registry, _ := spectator.NewRegistry(config)
	defer registry.Close()

	server := newServer(registry)

	for i := 1; i < 3; i++ {
		// get a request
		req := getNextRequest()
		server.Handle(req)
	}
}

Logging is implemented with the standard Golang slog package. The logger defines interfaces for Debugf, Infof, and Errorf. There are useful messages implemented at the Debug level which can help diagnose the metric publishing workflow.

Use spectator-go-runtime-metrics. Follow instructions in the README to enable collection.

Version 0.3 consists of a major rewrite that turns spectator-go into a thin client designed to send metrics through spectatord. As a result some functionality has been moved to other packages or removed.

spectator.Registry now supports different writers. The default writer is writer.UdpWriter which sends metrics to spectatord through UDP.

Writers can be configured through spectator.Config.Location. Possible values are:

• none: Configures a no-op writer that does nothing. Can be used to disable metrics collection.
• stdout: Writes metrics to stdout.
• stderr: Writes metrics to stderr.
• memory: Writes metrics to memory. Useful for testing.
• file:///path/to/file: Writes metrics to a file.
• unix:///path/to/socket: Writes metrics to a Unix domain socket.
• udp://host:port: Writes metrics to a UDP socket.

Location can also be set through the environment variable SPECTATOR_OUTPUT_LOCATION. If both are set, the environment variable takes precedence over the passed config.

The environment variable SPECTATOR_OUTPUT_LOCATION can be set to none to disable metrics collection.

The following new Meters have been added:

• meter.MaxGauge
• meter.Gauge with TTL

Common tags are now automatically added to all Meters. Their values are read from the environment variables.

Tags from environment variables take precedence over tags passed on code when creating the Config.

Note that common tags sourced by spectatord can't be overwritten.

• Config is now created through a constructor which throws error if the passed in parameters are not valid.
• Config members are now private.

• Runtime metrics collection has been moved to spectator-go-runtime-metrics. Follow instructions in the README to enable collection.
• Some types have been moved to different packages. For example, spectator.Counter is now in meter.Counter.

• spectator.HttpClient has been removed. Use the standard http.Client instead.
• spectator.Meters no longer has a Measure() []Measurement function. Meters are now stateless and do not store measurements.
• spectator.Clock has been removed. Use the standard time package instead.
• spectator.Config has been greatly simplified.
• spectator.Registry no longer has a Start() function. It is now automatically started when created.
• spectator.Registry no longer has a Stop() function. Instead, use Close() to close the registry. Once the registry is closed, it can't be started again.
• spectator.Config.IpcTimerRecord has been removed. Use a meter.Timer instead to record Ipc metrics.
• spectator.MeterFactoryFun has been removed. If you need to create a custom meter you can do so by wrapping one of the meters returned by spectator.Registry.
• spectator.Registry no longer reports spectator.measurements metrics. Instead, you can use spectatord metrics to troubleshoot.
• spectator.Registry no longer keep track of the Meters it creates. This means that you can't get a list of all Meters from the Registry. If you need to keep track of Meters, you can do so in your application code.
• Percentile* meters no longer support defining min/max values.
• spectator.Registry no longer allows setting a different logger after creation. A custom logger can be set in the spectator.Config before creating the Registry.
• File-based configuration is no longer supported.

1. Make sure you're not relying on any of the removed functionality.
2. Update imports to use meters package instead of spectator for Meters.
3. If you want to collect runtime metrics pull spectator-go-runtime-metrics and follow the instructions in the README
4. If you use PercentileDistributionSummary or PercentileTimer you need to update your code to use the respective functions provided by the Registry to initialize these meters.
5. Remove dependency on Spectator Go Internal configuration library. Such dependency is no longer required.
6. There is no longer an option to start or stop the registry at runtime. If you need to configure a registry that doesn't emit metrics, you can use the spectator.Config.Location option with none to configure a no-op writer.