Documentation ¶
Overview ¶
Package otlploggrpc provides an OTLP log exporter using gRPC. The exporter uses gRPC to transport OTLP protobuf payloads.
All Exporters must be created with New.
The environment variables described below can be used for configuration.
OTEL_EXPORTER_OTLP_ENDPOINT, OTEL_EXPORTER_OTLP_LOGS_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 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. OTEL_EXPORTER_OTLP_LOGS_ENDPOINT takes precedence over OTEL_EXPORTER_OTLP_ENDPOINT. The configuration can be overridden by WithEndpoint, WithEndpointURL, WithInsecure, and WithGRPCConn options.
OTEL_EXPORTER_OTLP_INSECURE, OTEL_EXPORTER_OTLP_LOGS_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 scheme. OTEL_EXPORTER_OTLP_LOGS_INSECURE takes precedence over OTEL_EXPORTER_OTLP_INSECURE. The configuration can be overridden by WithInsecure, WithGRPCConn options.
OTEL_EXPORTER_OTLP_HEADERS, OTEL_EXPORTER_OTLP_LOGS_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 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_LOGS_HEADERS takes precedence over OTEL_EXPORTER_OTLP_HEADERS. The configuration can be overridden by WithHeaders option.
OTEL_EXPORTER_OTLP_TIMEOUT, OTEL_EXPORTER_OTLP_LOGS_TIMEOUT (default: "10000") - maximum time in milliseconds the OTLP exporter waits for each batch export. OTEL_EXPORTER_OTLP_LOGS_TIMEOUT takes precedence over OTEL_EXPORTER_OTLP_TIMEOUT. The configuration can be overridden by WithTimeout option.
OTEL_EXPORTER_OTLP_COMPRESSION, OTEL_EXPORTER_OTLP_LOGS_COMPRESSION (default: none) - the gRPC compressor the exporter uses. Supported value: "gzip". OTEL_EXPORTER_OTLP_LOGS_COMPRESSION takes precedence over OTEL_EXPORTER_OTLP_COMPRESSION. The configuration can be overridden by WithCompressor, WithGRPCConn options.
OTEL_EXPORTER_OTLP_CERTIFICATE, OTEL_EXPORTER_OTLP_LOGS_CERTIFICATE (default: none) - the filepath to the trusted certificate to use when verifying a server's TLS credentials. OTEL_EXPORTER_OTLP_LOGS_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_LOGS_CLIENT_CERTIFICATE (default: none) - the filepath to the client certificate/chain trust for client's private key to use in mTLS communication in PEM format. OTEL_EXPORTER_OTLP_LOGS_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_LOGS_CLIENT_KEY (default: none) - the filepath to the client's private key to use in mTLS communication in PEM format. OTEL_EXPORTER_OTLP_LOGS_CLIENT_KEY takes precedence over OTEL_EXPORTER_OTLP_CLIENT_KEY. The configuration can be overridden by WithTLSCredentials, WithGRPCConn option.
Example ¶
package main import ( "context" "go.opentelemetry.io/otel/exporters/otlp/otlplog/otlploggrpc" "go.opentelemetry.io/otel/log/global" "go.opentelemetry.io/otel/sdk/log" ) func main() { ctx := context.Background() exp, err := otlploggrpc.New(ctx) if err != nil { panic(err) } processor := log.NewBatchProcessor(exp) provider := log.NewLoggerProvider(log.WithProcessor(processor)) defer func() { if err := provider.Shutdown(ctx); err != nil { panic(err) } }() global.SetLoggerProvider(provider) // From here, the provider can be used by instrumentation to collect // telemetry. }
Output:
Index ¶
- func Version() string
- type Compression
- type Exporter
- type Option
- func WithCompressor(compressor string) Option
- func WithDialOption(opts ...grpc.DialOption) Option
- func WithEndpoint(endpoint string) Option
- func WithEndpointURL(rawURL 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(rc RetryConfig) Option
- func WithServiceConfig(serviceConfig string) Option
- func WithTLSCredentials(credential credentials.TransportCredentials) Option
- func WithTimeout(duration time.Duration) Option
- type RetryConfig
Examples ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
Types ¶
type Compression ¶
type Compression int
Compression describes the compression used for exported payloads.
const ( // NoCompression represents that no compression should be used. NoCompression Compression = iota // GzipCompression represents that gzip compression should be used. GzipCompression )
type Exporter ¶
type Exporter struct {
// contains filtered or unexported fields
}
Exporter is a OpenTelemetry log Exporter. It transports log data encoded as OTLP protobufs using gRPC. All Exporters must be created with New.
func New ¶
New returns a new Exporter.
It is recommended to use it with a [BatchProcessor] or other processor exporting records asynchronously.
func (*Exporter) Export ¶
Export transforms and transmits log records to an OTLP receiver.
This method returns nil and drops records if called after Shutdown. This method returns an error if the method is canceled by the passed context.
func (*Exporter) ForceFlush ¶
ForceFlush does nothing. The Exporter holds no state.
type Option ¶
type Option interface {
// contains filtered or unexported methods
}
Option applies an option to the Exporter.
func WithCompressor ¶
WithCompressor sets the compressor the gRPC client uses. Supported compressor values: "gzip".
If the OTEL_EXPORTER_OTLP_COMPRESSION or OTEL_EXPORTER_OTLP_LOGS_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_LOGS_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.
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. The grpc.WithBlock, grpc.WithTimeout, and grpc.WithReturnConnectionError grpc.DialOptions are ignored.
This option has no effect if WithGRPCConn is used.
func WithEndpoint ¶
WithEndpoint sets the target endpoint the Exporter will connect to.
If the OTEL_EXPORTER_OTLP_ENDPOINT or OTEL_EXPORTER_OTLP_LOGS_ENDPOINT environment variable is set, and this option is not passed, that variable value will be used. If both are set, OTEL_EXPORTER_OTLP_LOGS_ENDPOINT will take precedence.
If both this option and WithEndpointURL are used, the last used option 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 WithEndpointURL ¶
WithEndpointURL sets the target endpoint URL the Exporter will connect to.
If the OTEL_EXPORTER_OTLP_ENDPOINT or OTEL_EXPORTER_OTLP_LOGS_ENDPOINT environment variable is set, and this option is not passed, that variable value will be used. If both are set, OTEL_EXPORTER_OTLP_LOGS_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: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 ¶
WithHeaders will send the provided headers with each gRPC requests.
If the OTEL_EXPORTER_OTLP_HEADERS or OTEL_EXPORTER_OTLP_LOGS_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_LOGS_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_LOGS_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_LOGS_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 ¶
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(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.
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 ¶
WithServiceConfig defines the default gRPC service config used.
This option has no effect if WithGRPCConn is used.
func WithTLSCredentials ¶
func WithTLSCredentials(credential credentials.TransportCredentials) Option
WithTLSCredentials sets the gRPC connection to use creds.
If the OTEL_EXPORTER_OTLP_CERTIFICATE or OTEL_EXPORTER_OTLP_LOGS_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_LOGS_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 ¶
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 log data is dropped.
If the OTEL_EXPORTER_OTLP_TIMEOUT or OTEL_EXPORTER_OTLP_LOGS_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_LOGS_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 ¶
RetryConfig defines configuration for retrying the export of log data that failed.
This configuration does not define any network retry strategy. That is entirely handled by the gRPC ClientConn.
Directories ¶
Path | Synopsis |
---|---|
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/log data-types into OTLP data-types.
|
Package transform provides transformation functionality from the sdk/log data-types into OTLP data-types. |