...
▽

Package otlptracegrpc

import "go.opentelemetry.io/otel/exporters/otlp/otlptrace/otlptracegrpc"
Overview
Index
Examples
Subdirectories

Overview ▾

Package otlptracegrpc provides an OTLP span exporter using gRPC. By default the telemetry is sent to https://localhost:4317.

Exporter should be created using New.

The environment variables described below can be used for configuration.

OTEL_EXPORTER_OTLP_ENDPOINT, OTEL_EXPORTER_OTLP_TRACES_ENDPOINT (default: "https://localhost:4317") - target to which the exporter sends telemetry. The target syntax is defined in https://github.com/grpc/grpc/blob/master/doc/naming.md. The value must contain a host. The value may additionally a port, a scheme, and a path. The value accepts "http" and "https" scheme. The value should not contain a query string or fragment. OTEL_EXPORTER_OTLP_TRACES_ENDPOINT takes precedence over OTEL_EXPORTER_OTLP_ENDPOINT. The configuration can be overridden by WithEndpoint, WithInsecure, WithGRPCConn options.

OTEL_EXPORTER_OTLP_INSECURE, OTEL_EXPORTER_OTLP_TRACES_INSECURE (default: "false") - setting "true" disables client transport security for the exporter's gRPC connection. You can use this only when an endpoint is provided without the http or https scheme. OTEL_EXPORTER_OTLP_ENDPOINT, OTEL_EXPORTER_OTLP_TRACES_ENDPOINT setting overrides the scheme defined via OTEL_EXPORTER_OTLP_ENDPOINT, OTEL_EXPORTER_OTLP_TRACES_ENDPOINT. OTEL_EXPORTER_OTLP_TRACES_INSECURE takes precedence over OTEL_EXPORTER_OTLP_INSECURE. The configuration can be overridden by WithInsecure, WithGRPCConn options.

OTEL_EXPORTER_OTLP_HEADERS, OTEL_EXPORTER_OTLP_TRACES_HEADERS (default: none) - key-value pairs used as gRPC metadata associated with gRPC requests. The value is expected to be represented in a format matching to 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_TRACES_HEADERS takes precedence over OTEL_EXPORTER_OTLP_HEADERS. The configuration can be overridden by WithHeaders option.

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

OTEL_EXPORTER_OTLP_COMPRESSION, OTEL_EXPORTER_OTLP_TRACES_COMPRESSION (default: none) - the gRPC compressor the exporter uses. Supported value: "gzip". OTEL_EXPORTER_OTLP_TRACES_COMPRESSION takes precedence over OTEL_EXPORTER_OTLP_COMPRESSION. The configuration can be overridden by WithCompressor, WithGRPCConn options.

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

OTEL_EXPORTER_OTLP_CLIENT_CERTIFICATE, OTEL_EXPORTER_OTLP_TRACES_CLIENT_CERTIFICATE (default: none) - the filepath to the client certificate/chain trust for clients private key to use in mTLS communication in PEM format. OTEL_EXPORTER_OTLP_TRACES_CLIENT_CERTIFICATE takes precedence over OTEL_EXPORTER_OTLP_CLIENT_CERTIFICATE. The configuration can be overridden by WithTLSCredentials, WithGRPCConn options.

OTEL_EXPORTER_OTLP_CLIENT_KEY, OTEL_EXPORTER_OTLP_TRACES_CLIENT_KEY (default: none) - the filepath to the clients private key to use in mTLS communication in PEM format. OTEL_EXPORTER_OTLP_TRACES_CLIENT_KEY takes precedence over OTEL_EXPORTER_OTLP_CLIENT_KEY. The configuration can be overridden by WithTLSCredentials, WithGRPCConn option.

▾ Example

Code:

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

tracerProvider := trace.NewTracerProvider(trace.WithBatcher(exp))
defer func() {
    if err := tracerProvider.Shutdown(ctx); err != nil {
        panic(err)
    }
}()
otel.SetTracerProvider(tracerProvider)

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

func New 

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

New constructs a new Exporter and starts it.

func NewClient 

func NewClient(opts ...Option) otlptrace.Client

NewClient creates a new gRPC trace client.

func NewUnstarted 

func NewUnstarted(opts ...Option) *otlptrace.Exporter

NewUnstarted constructs a new Exporter and does not start it.

type Option

Option applies an option to the gRPC driver. 

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

func WithCompressor 

func WithCompressor(compressor string) Option

WithCompressor sets the compressor for the gRPC client to use when sending requests. Supported compressor values: "gzip".

func WithDialOption 

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

WithDialOption sets explicit grpc.DialOptions to use when making a 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 unset, localhost:4317 will be used as a default.

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 client 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.

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. Note, by default, client security is required unless WithInsecure is 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 may be returned by the target endpoint when exporting a batch of spans.

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 allows the connection to use TLS credentials when talking to the server. It takes in grpc.TransportCredentials instead of say a Certificate file or a tls.Certificate, because the retrieving of these credentials can be done in many ways e.g. plain file, in code tls.Config or by certificate rotation, so it is up to the caller to decide what to use.

This option has no effect if WithGRPCConn is used.

func WithTimeout 

func WithTimeout(duration time.Duration) Option

WithTimeout sets the max amount of time a client will attempt to export a batch of spans. This takes precedence over any retry settings defined with WithRetry, once this time limit has been reached the export is abandoned and the batch of spans is dropped.

If unset, the default timeout will be set to 10 seconds.

type RetryConfig

RetryConfig defines configuration for retrying export of span batches that failed to be received by the target endpoint.

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

type RetryConfig retry.Config

Subdirectories

Name Synopsis
..