otlpmetricgrpc

Documentation

Overview

Package otlpmetricgrpc provides an otlpmetric.Exporter that communicates with an OTLP receiving endpoint using gRPC.

Example

package main

import (
	"context"

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

func main() {
	ctx := context.Background()
	exp, err := otlpmetricgrpc.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)
		}
	}()
	global.SetMeterProvider(meterProvider)

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

Index

• func New(ctx context.Context, options ...Option) (metric.Exporter, error)
• type Option
  • func WithCompressor(compressor string) Option
  • func WithDialOption(opts ...grpc.DialOption) Option
  • func WithEndpoint(endpoint string) Option
  • func WithGRPCConn(conn *grpc.ClientConn) Option
  • func WithHeaders(headers map[string]string) Option
  • func WithInsecure() Option
  • func WithReconnectionPeriod(rp time.Duration) Option
  • func WithRetry(settings RetryConfig) Option
  • func WithServiceConfig(serviceConfig string) Option
  • func WithTLSCredentials(creds credentials.TransportCredentials) Option
  • func WithTimeout(duration time.Duration) Option
• type RetryConfig

Examples

• Package

Functions

func New

func New(ctx context.Context, options ...Option) (metric.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 gRPC.

If an already established gRPC ClientConn is not passed in options using WithGRPCConn, a connection to the OTLP endpoint will be established based on options. If a connection cannot be establishes in the lifetime of ctx, an error will be returned.

Types

type Option

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

Option applies a configuration option to the Exporter.

func WithCompressor

func WithCompressor(compressor string) Option

WithCompressor sets the compressor the gRPC client uses.

It is the responsibility of the caller to ensure that the compressor set has been registered with google.golang.org/grpc/encoding (see encoding.RegisterCompressor for more information). For example, to register the gzip compressor import the package:

import _ "google.golang.org/grpc/encoding/gzip"

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 compressor will be used.

This option has no effect if WithGRPCConn is used.

func WithDialOption

func WithDialOption(opts ...grpc.DialOption) Option

WithDialOption sets explicit grpc.DialOptions to use when establishing a gRPC connection. The options here are appended to the internal grpc.DialOptions used so they will take precedence over any other internal grpc.DialOptions they might conflict with.

This option has no effect if WithGRPCConn is used.

func WithEndpoint

func WithEndpoint(endpoint string) Option

WithEndpoint sets the target endpoint 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.

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

This option has no effect if WithGRPCConn is used.

func WithGRPCConn

func WithGRPCConn(conn *grpc.ClientConn) Option

WithGRPCConn sets conn as the gRPC ClientConn used for all communication.

This option takes precedence over any other option that relates to establishing or persisting a gRPC connection to a target endpoint. Any other option of those types passed will be ignored.

It is the callers responsibility to close the passed conn. The Exporter Shutdown method will not close this connection.

func WithHeaders

func WithHeaders(headers map[string]string) Option

WithHeaders will send the provided headers with each gRPC 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 gRPC connection, just like grpc.WithInsecure() (https://pkg.go.dev/google.golang.org/grpc#WithInsecure) does.

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.

This option has no effect if WithGRPCConn is used.

func WithReconnectionPeriod

func WithReconnectionPeriod(rp time.Duration) Option

WithReconnectionPeriod set the minimum amount of time between connection attempts to the target endpoint.

This option has no effect if WithGRPCConn is used.

func WithRetry

func WithRetry(settings 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.

These settings do not define any network retry strategy. That is entirely handled by the gRPC ClientConn.

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 WithServiceConfig

func WithServiceConfig(serviceConfig string) Option

WithServiceConfig defines the default gRPC service config used.

This option has no effect if WithGRPCConn is used.

func WithTLSCredentials

func WithTLSCredentials(creds credentials.TransportCredentials) Option

WithTLSCredentials sets the gRPC connection to use creds.

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, no TLS credentials will be used.

This option has no effect if WithGRPCConn is used.

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.

type RetryConfig

type RetryConfig retry.Config

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

This configuration does not define any network retry strategy. That is entirely handled by the gRPC ClientConn.