opencensusreceiver

README

OpenCensus Receiver

Receives traces and/or metrics via gRPC using OpenCensus format.

To get started, all that is required to enable the OpenCensus receiver is to include it in the receiver definitions.

The following settings are required:

• endpoint (default = 0.0.0.0:55678): host:port to which the exporter is going to receive traces or metrics, using the gRPC protocol. The valid syntax is described at https://github.com/grpc/grpc/blob/master/doc/naming.md.
• transport (default = tcp): which transport to use between tcp and unix.

The following settings are optional:

• cors_allowed_origins (default = unset): allowed CORS origins for HTTP/JSON requests. See the HTTP/JSON section below.
• keepalive: see https://godoc.org/google.golang.org/grpc/keepalive#ServerParameters for more information
  • MaxConnectionIdle (default = infinity)
  • MaxConnectionAge (default = infinity)
  • MaxConnectionAgeGrace (default = infinity)
  • Time (default = 2h)
  • Timeout (default = 20s)
• max_recv_msg_size_mib (default = infinity): sets the maximum size of messages accepted
• max_concurrent_streams: sets the limit on the number of concurrent streams
• tls_credentials (default = unset): configures the receiver to use TLS. See TLS section below.

Examples:

receivers:
  opencensus:
  opencensus/withendpoint:
    endpoint: 127.0.0.1:55678

The full list of settings exposed for this receiver are documented here with detailed sample configurations here.

Communicating over TLS

This receiver supports communication using Transport Layer Security (TLS). TLS can be configured by specifying a tls_settings object in the receiver configuration for receivers that support it.

receivers:
  opencensus:
    tls_settings:
      key_file: /key.pem # path to private key
      cert_file: /cert.pem # path to certificate

Writing with HTTP/JSON

The OpenCensus receiver can receive trace export calls via HTTP/JSON in addition to gRPC. The HTTP/JSON address is the same as gRPC as the protocol is recognized and processed accordingly.

To write traces with HTTP/JSON, POST to [address]/v1/trace. The JSON message format parallels the gRPC protobuf format, see this OpenApi spec for it.

The HTTP/JSON endpoint can also optionally configure CORS, which is enabled by specifying a list of allowed CORS origins in the cors_allowed_origins field:

receivers:
  opencensus:
    cors_allowed_origins:
    - http://test.com
    # Origins can have wildcards with *, use * by itself to match any origin.
    - https://*.example.com

Documentation

Index

• type Config
• type Factory
  • func (f *Factory) CreateDefaultConfig() configmodels.Receiver
  • func (f *Factory) CreateMetricsReceiver(ctx context.Context, logger *zap.Logger, cfg configmodels.Receiver, ...) (component.MetricsReceiver, error)
  • func (f *Factory) CreateTraceReceiver(ctx context.Context, logger *zap.Logger, cfg configmodels.Receiver, ...) (component.TraceReceiver, error)
  • func (f *Factory) CustomUnmarshaler() component.CustomUnmarshaler
  • func (f *Factory) Type() configmodels.Type
• type Option
  • func WithCorsOrigins(origins []string) Option
  • func WithGRPCServerOptions(gsOpts ...grpc.ServerOption) Option
• type Receiver
  • func New(instanceName string, transport string, addr string, ...) (*Receiver, error)
  • func (ocr *Receiver) Shutdown(context.Context) error
  • func (ocr *Receiver) Start(ctx context.Context, host component.Host) error

Types

type Config

type Config struct {
	configmodels.ReceiverSettings `mapstructure:",squash"` // squash ensures fields are correctly decoded in embedded struct

	// Configures the receiver server protocol.
	configgrpc.GRPCServerSettings `mapstructure:",squash"` // squash ensures fields are correctly decoded in embedded struct

	// CorsOrigins are the allowed CORS origins for HTTP/JSON requests to grpc-gateway adapter
	// for the OpenCensus receiver. See github.com/rs/cors
	// An empty list means that CORS is not enabled at all. A wildcard (*) can be
	// used to match any origin or one or more characters of an origin.
	CorsOrigins []string `mapstructure:"cors_allowed_origins"`
}

Config defines configuration for OpenCensus receiver.

type Factory

type Factory struct {
}

Factory is the Factory for receiver.

func (*Factory) CreateDefaultConfig

func (f *Factory) CreateDefaultConfig() configmodels.Receiver

CreateDefaultConfig creates the default configuration for receiver.

func (*Factory) CreateMetricsReceiver

func (f *Factory) CreateMetricsReceiver(ctx context.Context, logger *zap.Logger, cfg configmodels.Receiver, nextConsumer consumer.MetricsConsumerOld) (component.MetricsReceiver, error)

CreateMetricsReceiver creates a metrics receiver based on provided config.

func (*Factory) CreateTraceReceiver

func (f *Factory) CreateTraceReceiver(
	ctx context.Context,
	logger *zap.Logger,
	cfg configmodels.Receiver,
	nextConsumer consumer.TraceConsumerOld,
) (component.TraceReceiver, error)

CreateTraceReceiver creates a trace receiver based on provided config.

func (*Factory) CustomUnmarshaler

func (f *Factory) CustomUnmarshaler() component.CustomUnmarshaler

CustomUnmarshaler returns nil because we don't need custom unmarshaling for this config.

func (*Factory) Type

func (f *Factory) Type() configmodels.Type

Type gets the type of the Receiver config created by this Factory.

type Option

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

Option interface defines for configuration settings to be applied to receivers.

withReceiver applies the configuration to the given receiver.

func WithCorsOrigins

func WithCorsOrigins(origins []string) Option

WithCorsOrigins is an option to specify the allowed origins to enable writing HTTP/JSON requests to the grpc-gateway adapter using CORS.

func WithGRPCServerOptions

func WithGRPCServerOptions(gsOpts ...grpc.ServerOption) Option

WithGRPCServerOptions allows one to specify the options for starting a gRPC server.

type Receiver

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

Receiver is the type that exposes Trace and Metrics reception.

func New

func New(
	instanceName string,
	transport string,
	addr string,
	tc consumer.TraceConsumerOld,
	mc consumer.MetricsConsumerOld,
	opts ...Option,
) (*Receiver, error)

New just creates the OpenCensus receiver services. It is the caller's responsibility to invoke the respective Start*Reception methods as well as the various Stop*Reception methods to end it.

func (*Receiver) Shutdown

func (ocr *Receiver) Shutdown(context.Context) error

Shutdown is a method to turn off receiving.

func (*Receiver) Start

func (ocr *Receiver) Start(ctx context.Context, host component.Host) error

Start runs the trace receiver on the gRPC server. Currently it also enables the metrics receiver too.