Build a receiver

OpenTelemetry defines distributed tracing as:

Traces that track the progression of a single request, known as a trace, as it is handled by services that make up an application. The request may be initiated by a user or an application. Distributed tracing is a form of tracing that traverses process, network, and security boundaries.

Although distributed traces are defined in an application-centric way, you can think of them as a timeline for any request that moves through your system. Each distributed trace shows how long a request took from start to finish and breaks down the steps taken to complete it.

If your system generates tracing telemetry, you can configure your OpenTelemetry Collector with a trace receiver designed to receive and convert that telemetry. The receiver converts your data from its original format into the OpenTelemetry trace model so the Collector can process it.

To implement a trace receiver, you need the following:

• A Config implementation so the trace receiver can gather and validate its configurations in the Collector config.yaml.

• A receiver.Factory implementation so the Collector can properly instantiate the trace receiver component.

• A receiver.Traces implementation that collects the telemetry, converts it to the internal trace representation, and passes the telemetry to the next consumer in the pipeline.

This tutorial shows you how to create a trace receiver called tailtracer that simulates a pull operation and generates traces as an outcome of that operation.

Setting up receiver development and testing environment

First, use the Building a Custom Collector tutorial to create a Collector instance named otelcol-dev; all you need is to copy the builder-config.yaml described in Configure the OpenTelemetry Collector Builder and run the builder. As an outcome, you should now have a folder structure like this:

.
├── builder-config.yaml
├── ocb
└── otelcol-dev
    ├── components.go
    ├── components_test.go
    ├── go.mod
    ├── go.sum
    ├── main.go
    ├── main_others.go
    ├── main_windows.go
    └── otelcol-dev

To properly test your trace receiver, you may need a distributed tracing backend so the Collector can send the telemetry to it. We will be using Jaeger. If you don’t have a Jaeger instance running, you can easily start one using Docker with the following command:

docker run -d --name jaeger \
  -p 16686:16686 \
  -p 14317:4317 \
  -p 14318:4318 \
  jaegertracing/jaeger:latest

Once the container is up and running, you can access Jaeger UI via this URL: http://localhost:16686/