otlpmetrichttp

package module
v1.26.0 Latest Latest
Warning

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

 Go to latest Published: Apr 24, 2024 License: Apache-2.0 Imports: 24 Imported by: 115

README

OTLP Metric HTTP Exporter

PkgGoDev

Documentation

Overview

Package otlpmetrichttp provides an OTLP metrics exporter using HTTP with protobuf payloads. By default the telemetry is sent to https://localhost:4318/v1/metrics.

Exporter should be created using New and used with a metric.PeriodicReader.

The environment variables described below can be used for configuration.

OTEL_EXPORTER_OTLP_ENDPOINT (default: "https://localhost:4318") - target base URL ("/v1/metrics" is appended) to which the exporter sends telemetry. The value must contain a scheme ("http" or "https") and host. The value may additionally contain a port and a path. The value should not contain a query string or fragment. The configuration can be overridden by OTEL_EXPORTER_OTLP_METRICS_ENDPOINT environment variable and by WithEndpoint, WithEndpointURL, and WithInsecure options.

OTEL_EXPORTER_OTLP_METRICS_ENDPOINT (default: "https://localhost:4318/v1/metrics") - target URL to which the exporter sends telemetry. The value must contain a scheme ("http" or "https") and host. The value may additionally contain a port and a path. The value should not contain a query string or fragment. The configuration can be overridden by WithEndpoint, WithEndpointURL, [WitnInsecure], and WithURLPath options.

OTEL_EXPORTER_OTLP_HEADERS, OTEL_EXPORTER_OTLP_METRICS_HEADERS (default: none) - key-value pairs used as headers associated with HTTP requests. The value is expected to be represented in a format matching the W3C Baggage HTTP Header Content Format, except that additional semi-colon delimited metadata is not supported. Example value: "key1=value1,key2=value2". OTEL_EXPORTER_OTLP_METRICS_HEADERS takes precedence over OTEL_EXPORTER_OTLP_HEADERS. The configuration can be overridden by WithHeaders option.

OTEL_EXPORTER_OTLP_TIMEOUT, OTEL_EXPORTER_OTLP_METRICS_TIMEOUT (default: "10000") - maximum time in milliseconds the OTLP exporter waits for each batch export. OTEL_EXPORTER_OTLP_METRICS_TIMEOUT takes precedence over OTEL_EXPORTER_OTLP_TIMEOUT. The configuration can be overridden by WithTimeout option.

OTEL_EXPORTER_OTLP_COMPRESSION, OTEL_EXPORTER_OTLP_METRICS_COMPRESSION (default: none) - compression strategy the exporter uses to compress the HTTP body. Supported values: "gzip". OTEL_EXPORTER_OTLP_METRICS_COMPRESSION takes precedence over OTEL_EXPORTER_OTLP_COMPRESSION. The configuration can be overridden by WithCompression option.

OTEL_EXPORTER_OTLP_CERTIFICATE, OTEL_EXPORTER_OTLP_METRICS_CERTIFICATE (default: none) - filepath to the trusted certificate to use when verifying a server's TLS credentials. OTEL_EXPORTER_OTLP_METRICS_CERTIFICATE takes precedence over OTEL_EXPORTER_OTLP_CERTIFICATE. The configuration can be overridden by WithTLSClientConfig option.

OTEL_EXPORTER_OTLP_CLIENT_CERTIFICATE, OTEL_EXPORTER_OTLP_METRICS_CLIENT_CERTIFICATE (default: none) - filepath to the client certificate/chain trust for client's private key to use in mTLS communication in PEM format. OTEL_EXPORTER_OTLP_METRICS_CLIENT_CERTIFICATE takes precedence over OTEL_EXPORTER_OTLP_CLIENT_CERTIFICATE. The configuration can be overridden by WithTLSClientConfig option.

OTEL_EXPORTER_OTLP_CLIENT_KEY, OTEL_EXPORTER_OTLP_METRICS_CLIENT_KEY (default: none) - filepath to the client's private key to use in mTLS communication in PEM format. OTEL_EXPORTER_OTLP_METRICS_CLIENT_KEY takes precedence over OTEL_EXPORTER_OTLP_CLIENT_KEY. The configuration can be overridden by WithTLSClientConfig option.

OTEL_EXPORTER_OTLP_METRICS_TEMPORALITY_PREFERENCE (default: "cumulative") - aggregation temporality to use on the basis of instrument kind. Supported values:

  • "cumulative" - Cumulative aggregation temporality for all instrument kinds,
  • "delta" - Delta aggregation temporality for Counter, Asynchronous Counter and Histogram instrument kinds; Cumulative aggregation for UpDownCounter and Asynchronous UpDownCounter instrument kinds,
  • "lowmemory" - Delta aggregation temporality for Synchronous Counter and Histogram instrument kinds; Cumulative aggregation temporality for Synchronous UpDownCounter, Asynchronous Counter, and Asynchronous UpDownCounter instrument kinds.

The configuration can be overridden by WithTemporalitySelector option.

OTEL_EXPORTER_OTLP_METRICS_DEFAULT_HISTOGRAM_AGGREGATION (default: "explicit_bucket_histogram") - default aggregation to use for histogram instruments. Supported values:

The configuration can be overridden by WithAggregationSelector option.

Example 
package main

import (
	"context"

	"go.opentelemetry.io/otel"
	"go.opentelemetry.io/otel/exporters/otlp/otlpmetric/otlpmetrichttp"
	"go.opentelemetry.io/otel/sdk/metric"
)

func main() {
	ctx := context.Background()
	exp, err := otlpmetrichttp.New(ctx)
	if err != nil {
		panic(err)
	}

	meterProvider := metric.NewMeterProvider(metric.WithReader(metric.NewPeriodicReader(exp)))
	defer func() {
		if err := meterProvider.Shutdown(ctx); err != nil {
			panic(err)
		}
	}()
	otel.SetMeterProvider(meterProvider)

	// From here, the meterProvider can be used by instrumentation to collect
	// telemetry.
}

Output:

Index

Examples

Constants

View Source 
const (
	// NoCompression tells the driver to send payloads without
	// compression.
	NoCompression = Compression(oconf.NoCompression)
	// GzipCompression tells the driver to send payloads after
	// compressing them with gzip.
	GzipCompression = Compression(oconf.GzipCompression)
)

Variables

This section is empty.

Functions

func Version added in v0.43.0 

func Version() string

Version is the current release version of the OpenTelemetry OTLP over HTTP/protobuf metrics exporter in use.

Types

type Compression 

type Compression oconf.Compression

Compression describes the compression used for payloads sent to the collector.

type Exporter added in v0.40.0 

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

Exporter is a OpenTelemetry metric Exporter using protobufs over HTTP.

func New 

func New(_ context.Context, opts ...Option) (*Exporter, error)

New returns an OpenTelemetry metric Exporter. The Exporter can be used with a PeriodicReader to export OpenTelemetry metric data to an OTLP receiving endpoint using protobufs over HTTP.

func (*Exporter) Aggregation added in v0.40.0 

func (e *Exporter) Aggregation(k metric.InstrumentKind) metric.Aggregation

Aggregation returns the Aggregation to use for an instrument kind.

func (*Exporter) Export added in v0.40.0 

func (e *Exporter) Export(ctx context.Context, rm *metricdata.ResourceMetrics) error

Export transforms and transmits metric data to an OTLP receiver.

This method returns an error if called after Shutdown. This method returns an error if the method is canceled by the passed context.

func (*Exporter) ForceFlush added in v0.40.0 

func (e *Exporter) ForceFlush(ctx context.Context) error

ForceFlush flushes any metric data held by an exporter.

This method returns an error if called after Shutdown. This method returns an error if the method is canceled by the passed context.

This method is safe to call concurrently.

func (*Exporter) MarshalLog added in v0.40.0 

func (e *Exporter) MarshalLog() interface{}

MarshalLog returns logging data about the Exporter.

func (*Exporter) Shutdown added in v0.40.0 

func (e *Exporter) Shutdown(ctx context.Context) error

Shutdown flushes all metric data held by an exporter and releases any held computational resources.

This method returns an error if called after Shutdown. This method returns an error if the method is canceled by the passed context.

This method is safe to call concurrently.

func (*Exporter) Temporality added in v0.40.0 

func (e *Exporter) Temporality(k metric.InstrumentKind) metricdata.Temporality

Temporality returns the Temporality to use for an instrument kind.

type HTTPTransportProxyFunc added in v1.25.0 

type HTTPTransportProxyFunc func(*http.Request) (*url.URL, error)

HTTPTransportProxyFunc is a function that resolves which URL to use as proxy for a given request. This type is compatible with http.Transport.Proxy and can be used to set a custom proxy function to the OTLP HTTP client.

type Option 

type Option interface {
	// contains filtered or unexported methods
}

Option applies an option to the Exporter.

func WithAggregationSelector added in v0.34.0 

func WithAggregationSelector(selector metric.AggregationSelector) Option

WithAggregationSelector sets the AggregationSelector the client will use to determine the aggregation to use for an instrument based on its kind. If this option is not used, the reader will use the DefaultAggregationSelector from the go.opentelemetry.io/otel/sdk/metric package, or the aggregation explicitly passed for a view matching an instrument.

func WithCompression 

func WithCompression(compression Compression) Option

WithCompression sets the compression strategy the Exporter will use to compress the HTTP body.

If the OTEL_EXPORTER_OTLP_COMPRESSION or OTEL_EXPORTER_OTLP_METRICS_COMPRESSION environment variable is set, and this option is not passed, that variable value will be used. That value can be either "none" or "gzip". If both are set, OTEL_EXPORTER_OTLP_METRICS_COMPRESSION will take precedence.

By default, if an environment variable is not set, and this option is not passed, no compression strategy will be used.

func WithEndpoint 

func WithEndpoint(endpoint string) Option

WithEndpoint sets the target endpoint the Exporter will connect to. This endpoint is specified as a host and optional port, no path or scheme should be included (see WithInsecure and WithURLPath).

If the OTEL_EXPORTER_OTLP_ENDPOINT or OTEL_EXPORTER_OTLP_METRICS_ENDPOINT environment variable is set, and this option is not passed, that variable value will be used. If both are set, OTEL_EXPORTER_OTLP_METRICS_ENDPOINT will take precedence.

By default, if an environment variable is not set, and this option is not passed, "localhost:4318" will be used.

func WithEndpointURL added in v1.23.0 

func WithEndpointURL(u string) Option

WithEndpointURL sets the target endpoint URL the Exporter will connect to.

If the OTEL_EXPORTER_OTLP_ENDPOINT or OTEL_EXPORTER_OTLP_METRICS_ENDPOINT environment variable is set, and this option is not passed, that variable value will be used. If both are set, OTEL_EXPORTER_OTLP_METRICS_ENDPOINT will take precedence.

If both this option and WithEndpoint are used, the last used option will take precedence.

If an invalid URL is provided, the default value will be kept.

By default, if an environment variable is not set, and this option is not passed, "localhost:4318" will be used.

This option has no effect if WithGRPCConn is used.

func WithHeaders 

func WithHeaders(headers map[string]string) Option

WithHeaders will send the provided headers with each HTTP requests.

If the OTEL_EXPORTER_OTLP_HEADERS or OTEL_EXPORTER_OTLP_METRICS_HEADERS environment variable is set, and this option is not passed, that variable value will be used. The value will be parsed as a list of key value pairs. These pairs are expected to be in the W3C Correlation-Context format without additional semi-colon delimited metadata (i.e. "k1=v1,k2=v2"). If both are set, OTEL_EXPORTER_OTLP_METRICS_HEADERS will take precedence.

By default, if an environment variable is not set, and this option is not passed, no user headers will be set.

func WithInsecure 

func WithInsecure() Option

WithInsecure disables client transport security for the Exporter's HTTP connection.

If the OTEL_EXPORTER_OTLP_ENDPOINT or OTEL_EXPORTER_OTLP_METRICS_ENDPOINT environment variable is set, and this option is not passed, that variable value will be used to determine client security. If the endpoint has a scheme of "http" or "unix" client security will be disabled. If both are set, OTEL_EXPORTER_OTLP_METRICS_ENDPOINT will take precedence.

By default, if an environment variable is not set, and this option is not passed, client security will be used.

func WithProxy added in v1.25.0 

func WithProxy(pf HTTPTransportProxyFunc) Option

WithProxy sets the Proxy function the client will use to determine the proxy to use for an HTTP request. If this option is not used, the client will use http.ProxyFromEnvironment.

func WithRetry added in v0.26.0 

func WithRetry(rc RetryConfig) Option

WithRetry sets the retry policy for transient retryable errors that are returned by the target endpoint.

If the target endpoint responds with not only a retryable error, but explicitly returns a backoff time in the response, that time will take precedence over these settings.

If unset, the default retry policy will be used. It will retry the export 5 seconds after receiving a retryable error and increase exponentially after each error for no more than a total time of 1 minute.

func WithTLSClientConfig 

func WithTLSClientConfig(tlsCfg *tls.Config) Option

WithTLSClientConfig sets the TLS configuration the Exporter will use for HTTP requests.

If the OTEL_EXPORTER_OTLP_CERTIFICATE or OTEL_EXPORTER_OTLP_METRICS_CERTIFICATE environment variable is set, and this option is not passed, that variable value will be used. The value will be parsed the filepath of the TLS certificate chain to use. If both are set, OTEL_EXPORTER_OTLP_METRICS_CERTIFICATE will take precedence.

By default, if an environment variable is not set, and this option is not passed, the system default configuration is used.

func WithTemporalitySelector added in v0.34.0 

func WithTemporalitySelector(selector metric.TemporalitySelector) Option

WithTemporalitySelector sets the TemporalitySelector the client will use to determine the Temporality of an instrument based on its kind. If this option is not used, the client will use the DefaultTemporalitySelector from the go.opentelemetry.io/otel/sdk/metric package.

func WithTimeout 

func WithTimeout(duration time.Duration) Option

WithTimeout sets the max amount of time an Exporter will attempt an export.

This takes precedence over any retry settings defined by WithRetry. Once this time limit has been reached the export is abandoned and the metric data is dropped.

If the OTEL_EXPORTER_OTLP_TIMEOUT or OTEL_EXPORTER_OTLP_METRICS_TIMEOUT environment variable is set, and this option is not passed, that variable value will be used. The value will be parsed as an integer representing the timeout in milliseconds. If both are set, OTEL_EXPORTER_OTLP_METRICS_TIMEOUT will take precedence.

By default, if an environment variable is not set, and this option is not passed, a timeout of 10 seconds will be used.

func WithURLPath 

func WithURLPath(urlPath string) Option

WithURLPath sets the URL path the Exporter will send requests to.

If the OTEL_EXPORTER_OTLP_ENDPOINT or OTEL_EXPORTER_OTLP_METRICS_ENDPOINT environment variable is set, and this option is not passed, the path contained in that variable value will be used. If both are set, OTEL_EXPORTER_OTLP_METRICS_ENDPOINT will take precedence.

By default, if an environment variable is not set, and this option is not passed, "/v1/metrics" will be used.

type RetryConfig added in v0.26.0 

type RetryConfig retry.Config

RetryConfig defines configuration for retrying the export of metric data that failed.

Source Files

View all Source files

Directories

Path Synopsis
envconfig
oconf
otest
retry
Package retry provides request retry functionality that can perform configurable exponential backoff for transient errors and honor any explicit throttle responses received.
 Package retry provides request retry functionality that can perform configurable exponential backoff for transient errors and honor any explicit throttle responses received.
transform
Package transform provides transformation functionality from the sdk/metric/metricdata data-types into OTLP data-types.
 Package transform provides transformation functionality from the sdk/metric/metricdata data-types into OTLP data-types.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.