remote

package
v0.0.0-...-84a4734 Latest Latest
Warning

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

Go to latest
Published: Aug 26, 2025 License: Apache-2.0 Imports: 17 Imported by: 1

Documentation

Overview

Package remote implements bindings for Prometheus Remote APIs.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func NewWriteHandler

func NewWriteHandler(store writeStorage, acceptedMessageTypes MessageTypes, opts ...WriteHandlerOption) http.Handler

NewWriteHandler returns HTTP handler that receives Remote Write 2.0 protocol https://prometheus.io/docs/specs/remote_write_spec_2_0/.

func SnappyDecodeMiddleware

func SnappyDecodeMiddleware(logger *slog.Logger) func(http.Handler) http.Handler

SnappyDecodeMiddleware returns a middleware that checks if the request body is snappy-encoded and decompresses it. If the request body is not snappy-encoded, it returns an error. Used by default in NewHandler.

Types

type API

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

API is a client for Prometheus Remote Protocols. NOTE(bwplotka): Only https://prometheus.io/docs/specs/remote_write_spec_2_0/ is currently implemented, read protocols to be implemented if there will be a demand.

func NewAPI

func NewAPI(baseURL string, opts ...APIOption) (*API, error)

NewAPI returns a new API for the clients of Remote Write Protocol.

func (*API) Write

func (r *API) Write(ctx context.Context, msgType WriteMessageType, msg any) (_ WriteResponseStats, err error)

Write writes given, non-empty, protobuf message to a remote storage.

Depending on serialization methods,

  • https://github.com/planetscale/vtprotobuf methods will be used if your msg supports those (e.g. SizeVT() and MarshalToSizedBufferVT(...)), for efficiency
  • Otherwise https://github.com/gogo/protobuf methods (e.g. Size() and MarshalToSizedBuffer(...)) will be used
  • If neither is supported, it will marshaled using generic google.golang.org/protobuf methods and error out on unknown scheme.

type APIOption

type APIOption func(o *apiOpts) error

APIOption represents a remote API option.

func WithAPIBackoff

func WithAPIBackoff(backoff backoff.Config) APIOption

WithAPIBackoff returns APIOption that allows overriding backoff configuration.

func WithAPIHTTPClient

func WithAPIHTTPClient(client *http.Client) APIOption

WithAPIHTTPClient returns APIOption that allows providing http client.

func WithAPILogger

func WithAPILogger(logger *slog.Logger) APIOption

WithAPILogger returns APIOption that allows providing slog logger. By default, nothing is logged.

func WithAPINoRetryOnRateLimit

func WithAPINoRetryOnRateLimit() APIOption

WithAPINoRetryOnRateLimit returns APIOption that disables retrying on rate limit status code.

func WithAPIPath

func WithAPIPath(path string) APIOption

WithAPIPath returns APIOption that allows providing path to send remote write requests to.

type Compression

type Compression string

Compression represents the encoding. Currently remote storage supports only one, but we experiment with more, thus leaving the compression scaffolding for now.

const (
	// SnappyBlockCompression represents https://github.com/google/snappy/blob/2c94e11145f0b7b184b831577c93e5a41c4c0346/format_description.txt
	SnappyBlockCompression Compression = "snappy"
)

type MessageTypes

type MessageTypes []WriteMessageType

func (MessageTypes) Contains

func (m MessageTypes) Contains(mType WriteMessageType) bool

func (MessageTypes) String

func (m MessageTypes) String() string

func (MessageTypes) Strings

func (m MessageTypes) Strings() []string

type WriteHandlerOption

type WriteHandlerOption func(o *writeHandlerOpts)

WriteHandlerOption represents an option for the write handler.

func WithWriteHandlerLogger

func WithWriteHandlerLogger(logger *slog.Logger) WriteHandlerOption

WithWriteHandlerLogger returns WriteHandlerOption that allows providing slog logger. By default, nothing is logged.

func WithWriteHandlerMiddlewares

func WithWriteHandlerMiddlewares(middlewares ...func(http.Handler) http.Handler) WriteHandlerOption

WithWriteHandlerMiddlewares returns WriteHandlerOption that allows providing middlewares. Multiple middlewares can be provided and will be applied in the order they are passed. This option replaces the default middlewares (SnappyDecompressorMiddleware), so if you want to have handler that works with the default Remote Write 2.0 protocol, SnappyDecompressorMiddleware (or any other decompression middleware) needs to be added explicitly.

type WriteMessageType

type WriteMessageType string

WriteMessageType represents the fully qualified name of the protobuf message to use in Remote write 1.0 and 2.0 protocols. See https://prometheus.io/docs/specs/remote_write_spec_2_0/#protocol.

const (
	// WriteV1MessageType represents the `prometheus.WriteRequest` protobuf
	// message introduced in the https://prometheus.io/docs/specs/remote_write_spec/.
	// DEPRECATED: Use WriteV2MessageType instead.
	WriteV1MessageType WriteMessageType = "prometheus.WriteRequest"
	// WriteV2MessageType represents the `io.prometheus.write.v2.Request` protobuf
	// message introduced in https://prometheus.io/docs/specs/remote_write_spec_2_0/
	WriteV2MessageType WriteMessageType = "io.prometheus.write.v2.Request"
)

func ParseProtoMsg

func ParseProtoMsg(contentType string) (WriteMessageType, error)

ParseProtoMsg parses the content-type header and returns the proto message type.

The expected content-type will be of the form,

  • `application/x-protobuf;proto=io.prometheus.write.v2.Request` which will be treated as RW2.0 request,
  • `application/x-protobuf;proto=prometheus.WriteRequest` which will be treated as RW1.0 request,
  • `application/x-protobuf` which will be treated as RW1.0 request.

If the content-type is not of the above forms, it will return an error.

func (WriteMessageType) Validate

func (n WriteMessageType) Validate() error

Validate returns error if the given reference for the protobuf message is not supported.

type WriteResponse

type WriteResponse struct {
	WriteResponseStats
	// contains filtered or unexported fields
}

WriteResponse represents the response from the remote storage upon receiving a remote write request.

func NewWriteResponse

func NewWriteResponse() *WriteResponse

NewWriteResponse creates a new WriteResponse with empty stats and status code http.StatusNoContent.

func (*WriteResponse) SetExtraHeader

func (w *WriteResponse) SetExtraHeader(key, value string)

SetExtraHeader adds additional headers to be set in the response (apart from stats headers)

func (*WriteResponse) SetStatusCode

func (w *WriteResponse) SetStatusCode(code int)

SetStatusCode sets the HTTP status code for the response. http.StatusNoContent is the default unless 5xx is set.

func (*WriteResponse) Stats

func (w *WriteResponse) Stats() WriteResponseStats

Stats returns the current statistics.

type WriteResponseStats

type WriteResponseStats struct {
	// Samples represents X-Prometheus-Remote-Write-Written-Samples
	Samples int
	// Histograms represents X-Prometheus-Remote-Write-Written-Histograms
	Histograms int
	// Exemplars represents X-Prometheus-Remote-Write-Written-Exemplars
	Exemplars int
	// contains filtered or unexported fields
}

WriteResponseStats represents the response, remote write statistics.

func (*WriteResponseStats) Add

Add adds the given WriteResponseStats to this WriteResponseStats. If this WriteResponseStats is empty, it will be replaced by the given WriteResponseStats.

func (WriteResponseStats) AllSamples

func (s WriteResponseStats) AllSamples() int

AllSamples returns both float and histogram sample numbers.

func (WriteResponseStats) NoDataWritten

func (s WriteResponseStats) NoDataWritten() bool

NoDataWritten returns true if statistics indicate no data was written.

Directories

Path Synopsis
genproto
v2

Jump to

Keyboard shortcuts

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