receiver

README

General Information

A receiver is how data gets into the OpenTelemetry Collector. Generally, a receiver accepts data in a specified format, translates it into the internal format and passes it to processors and exporters defined in the applicable pipelines. The format of the traces and metrics supported are receiver specific.

Supported trace receivers (sorted alphabetically):

• Jaeger Receiver
• OpenCensus Receiver
• Zipkin Receiver

Supported metric receivers (sorted alphabetically):

• OpenCensus Receiver
• Prometheus Receiver
• VM Metrics Receiver

The contributors repository has more receivers that can be added to custom builds of the collector.

Configuring Receiver(s)

Receivers are configured via YAML under the top-level receivers tag. There must be at least one enabled receiver for a configuration to be considered valid.

The following is a sample configuration for the examplereceiver.

receivers:
  # Receiver 1.
  # <receiver type>:
  examplereceiver:
    # <setting one>: <value one>
    endpoint: 1.2.3.4:8080
    # ...
  # Receiver 2.
  # <receiver type>/<name>:
  examplereceiver/settings:
    # <setting one>: <value one>
    disabled: false
    # <setting two>: <value two>
    endpoint: localhost:9211

A receiver instance is referenced by its full name in other parts of the config, such as in pipelines. A full name consists of the receiver type, '/' and the name appended to the receiver type in the configuration. All receiver full names must be unique. For the example above:

• Receiver 1 has full name examplereceiver.
• Receiver 2 has full name examplereceiver/settings.

All receivers expose a setting to disable it, by default receivers are enabled. At least one receiver must be enabled per pipeline to be a valid configuration.

Trace Receivers

Jaeger Receiver

This receiver supports Jaeger formatted traces.

It supports the Jaeger Collector and Agent protocols:

• gRPC
• Thrift HTTP
• Thrift TChannel
• Thrift Compact
• Thrift Binary

By default, the Jaeger receiver will not serve any protocol. A protocol must be named for the jaeger receiver to start. The following demonstrates how to start the Jaeger receiver with only gRPC enabled on the default port.

receivers:
  jaeger:
    protocols:
      grpc:

It is possible to configure the protocols on different ports, refer to config.yaml for detailed config examples. The full list of settings exposed for this receiver are documented here.

Communicating over TLS

The Jaeger receiver supports communication using Transport Layer Security (TLS), but only using the gRPC protocol. It can be configured by specifying a tls_credentials object in the gRPC receiver configuration.

receivers:
  jaeger:
    protocols:
      grpc:
        tls_credentials:
          key_file: /key.pem # path to private key
          cert_file: /cert.pem # path to certificate
        endpoint: "localhost:9876"

Remote Sampling

The Jaeger receiver also supports fetching sampling configuration from a remote collector. It works by proxying client requests for remote sampling configuration to the configured collector.

+---------------+ +--------------+ +-----------------+ | | get | | proxy | | | client +--- sampling ---->+ agent +------------->+ collector | | | strategy | | | | +---------------+ +--------------+ +-----------------+

Remote sample proxying can be enabled by specifying the following lines in the jaeger receiver config:

receivers:
  jaeger:
    protocols:
      grpc:
      .
      .
    remote_sampling:
      fetch_endpoint: "jaeger-collector:1234"

Remote sampling can also be directly served by the collector by providing a sampling json file:

receivers:
  jaeger:
    protocols:
      grpc:
    remote_sampling:
      strategy_file: "/etc/strategy.json"

Note: gRPC must be enabled for this to work as Jaeger serves its remote sampling strategies over gRPC.

OpenCensus Receiver

This receiver receives trace and metrics from OpenCensus instrumented applications.

To get started, all that is required to enable the OpenCensus receiver is to include it in the receiver definitions. This will enable the default values as specified here. The following is an example:

receivers:
  opencensus:

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_credentials object in the receiver configuration for receivers that support it.

receivers:
  opencensus:
    tls_credentials:
      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:
    endpoint: "localhost:55678"
    cors_allowed_origins:
    - http://test.com
    # Origins can have wildcards with *, use * by itself to match any origin.
    - https://*.example.com

Zipkin Receiver

This receiver receives spans from Zipkin (V1 and V2).

To get started, all that is required to enable the Zipkin receiver is to include it in the receiver definitions. This will enable the default values as specified here. The following is an example:

receivers:
  zipkin:

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

Metric Receivers

OpenCensus Receiver

The OpenCensus receiver supports both traces and metrics. Configuration information can be found under the trace section here.

Prometheus Receiver

This receiver is a drop-in replacement for getting Prometheus to scrape your services. Just like you would write in a YAML configuration file before starting Prometheus, such as with:

prometheus --config.file=prom.yaml

You can copy and paste that same configuration under section

receivers:
  prometheus:
    config:

For example:

receivers:
    prometheus:
      config:
        scrape_configs:
          - job_name: 'opencensus_service'
            scrape_interval: 5s
            static_configs:
              - targets: ['localhost:8889']

          - job_name: 'jdbc_apps'
            scrape_interval: 3s
            static_configs:
              - targets: ['localhost:9777']

Include Filter

Include Filter provides ability to filter scraping metrics per target. If a filter is specified for a target then only those metrics which exactly matches one of the metrics specified in the Include Filter list will be scraped. Rest of the metrics from the targets will be dropped.

Syntax

• Endpoint should be double quoted.
• Metrics should be specified in form of a list.

Example

receivers:
    prometheus:
      include_filter: {
        "localhost:9777" : [http/server/server_latency, custom_metric1],
        "localhost:9778" : [http/client/roundtrip_latency],
      }
      config:
        scrape_configs:
          ...

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

VM Metrics Receiver

Collects metrics from the host operating system. This is applicable when the OpenTelemetry Collector is running as an agent.

receivers:
  vmmetrics:
    scrape_interval: 10s
    metric_prefix: "testmetric"
    mount_point: "/proc"
    #process_mount_point: "/data/proc" # Only using when running as an agent / daemonset

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

Documentation

Overview

Example (EndToEnd)

package main

import (
	"context"
	"log"
	"time"

	"contrib.go.opencensus.io/exporter/ocagent"
	"go.opencensus.io/trace"
	"go.uber.org/zap"

	"github.com/open-telemetry/opentelemetry-collector/component"
	"github.com/open-telemetry/opentelemetry-collector/config/configmodels"
	"github.com/open-telemetry/opentelemetry-collector/exporter/loggingexporter"
	"github.com/open-telemetry/opentelemetry-collector/receiver/opencensusreceiver"
)

func main() {
	// This is what the cmd/ocagent code would look like this.
	// A trace receiver as per the trace receiver
	// configs that have been parsed.
	lte, err := loggingexporter.NewTraceExporter(&configmodels.ExporterSettings{}, "debug", zap.NewNop())
	if err != nil {
		log.Fatalf("Failed to create logging exporter: %v", err)
	}

	tr, err := opencensusreceiver.New("opencensus", "tcp", "localhost:55678", lte, nil)
	if err != nil {
		log.Fatalf("Failed to create trace receiver: %v", err)
	}

	// The agent will combine all trace receivers like this.
	trl := []component.TraceReceiver{tr}

	// Once we have the span receiver which will connect to the
	// various exporter pipeline i.e. *tracepb.Span->OpenCensus.SpanData
	for _, tr := range trl {
		if err := tr.Start(nil); err != nil {
			log.Fatalf("Failed to start trace receiver: %v", err)
		}
	}

	// Before exiting, stop all the trace receivers
	defer func() {
		for _, tr := range trl {
			_ = tr.Shutdown()
		}
	}()
	log.Println("Done starting the trace receiver")
	// We are done with the agent-core

	// Now this code would exist in the client application e.g. client code.
	// Create the agent exporter
	oce, err := ocagent.NewExporter(ocagent.WithInsecure())
	if err != nil {
		log.Fatalf("Failed to create ocagent exporter: %v", err)
	}
	defer oce.Stop()

	// Register it as a trace exporter
	trace.RegisterExporter(oce)
	// For demo purposes we are always sampling
	trace.ApplyConfig(trace.Config{DefaultSampler: trace.AlwaysSample()})

	log.Println("Starting loop")
	ctx, span := trace.StartSpan(context.Background(), "ClientLibrarySpan")
	for i := 0; i < 10; i++ {
		_, span := trace.StartSpan(ctx, "ChildSpan")
		span.Annotatef([]trace.Attribute{
			trace.StringAttribute("type", "Child"),
			trace.Int64Attribute("i", int64(i)),
		}, "This is an annotation")
		<-time.After(100 * time.Millisecond)
		span.End()
		oce.Flush()
	}
	span.End()

	<-time.After(400 * time.Millisecond)
	oce.Flush()
	<-time.After(5 * time.Second)
}

Index

• type SecureReceiverSettings
• type TLSCredentials
  • func (tlsCreds *TLSCredentials) ToGrpcServerOption() (opt grpc.ServerOption, err error)

Examples

• Package (EndToEnd)

Types

type SecureReceiverSettings

type SecureReceiverSettings struct {
	configmodels.ReceiverSettings `mapstructure:",squash"` // squash ensures fields are correctly decoded in embedded struct
	// Configures the receiver to use TLS.
	// The default value is nil, which will cause the receiver to not use TLS.
	TLSCredentials *TLSCredentials `mapstructure:"tls_credentials, omitempty"`
}

SecureReceiverSettings defines common settings for receivers that use Transport Layer Security (TLS)

type TLSCredentials

type TLSCredentials struct {
	// CertFile is the file path containing the TLS certificate.
	CertFile string `mapstructure:"cert_file"`

	// KeyFile is the file path containing the TLS key.
	KeyFile string `mapstructure:"key_file"`
}

TLSCredentials contains path information for a certificate and key to be used for TLS

func (*TLSCredentials) ToGrpcServerOption

func (tlsCreds *TLSCredentials) ToGrpcServerOption() (opt grpc.ServerOption, err error)

ToGrpcServerOption creates a gRPC ServerOption from TLSCredentials. If TLSCredentials is nil, returns empty option.