Quick start

The OpenTelemetry Collector receives traces, metrics, and logs, processes the telemetry, and exports it to a wide variety of observability backends using its components. For a conceptual overview of the Collector, see Collector.

You are going to learn to do the following in less than five minutes:

• Set up and run the OpenTelemetry Collector.
• Send telemetry and see it processed by the Collector.

Prerequisites

Make sure that your developer environment has the following. This page assumes that you’re using bash. Adapt configuration and commands as necessary for your preferred shell.

• Docker or any compatible containers’ runtime.
• Go 1.20 or higher
• GOBIN environment variable is set; if unset, initialize it appropriately, for example¹:

  export GOBIN=${GOBIN:-$(go env GOPATH)/bin}
  

Set up the environment

1. Pull in the OpenTelemetry Collector Contrib Docker image:

   docker pull otel/opentelemetry-collector-contrib:0.116.1
   

2. Install the telemetrygen utility:

   go install github.com/open-telemetry/opentelemetry-collector-contrib/cmd/telemetrygen@latest
   

   This utility can simulate a client generating traces, metrics, and logs.

Generate and collect telemetry

3. Launch the Collector, listening on ports 4317 (for OTLP gRPC), 4318 (for OTLP HTTP) and 55679 (for ZPages):

   docker run \
     -p 127.0.0.1:4317:4317 \
     -p 127.0.0.1:4318:4318 \
     -p 127.0.0.1:55679:55679 \
     otel/opentelemetry-collector-contrib:0.116.1 \
     2>&1 | tee collector-output.txt # Optionally tee output for easier search later
   

4. In a separate terminal window, generate a few sample traces:

   $GOBIN/telemetrygen traces --otlp-insecure --traces 3
   

   Among the output generated by the utility, you should see a confirmation that traces were generated:

   2024-01-16T14:33:15.692-0500  INFO  traces/worker.go:99  traces generated  {"worker": 0, "traces": 3}
   2024-01-16T14:33:15.692-0500  INFO  traces/traces.go:58  stop the batch span processor
   

   For an easier time seeing relevant output you can filter it:

   $GOBIN/telemetrygen traces --otlp-insecure \
     --traces 3 2>&1 | grep -E 'start|traces|stop'
   

5. In the terminal window running the Collector container, you should see trace ingest activity similar to what is shown in the following example:

   $ grep -E '^Span|(ID|Name|Kind|time|Status \w+)\s+:' ./collector-output.txt
   Span #0
       Trace ID       : f30faffbde5fcf71432f89da1bf7bc14
       Parent ID      : 6f1ff7f9cf4ec1c7
       ID             : 8d1e820c1ac57337
       Name           : okey-dokey
       Kind           : Server
       Start time     : 2024-01-16 14:13:54.585877 +0000 UTC
       End time       : 2024-01-16 14:13:54.586 +0000 UTC
       Status code    : Unset
       Status message :
   Span #1
       Trace ID       : f30faffbde5fcf71432f89da1bf7bc14
       Parent ID      :
       ID             : 6f1ff7f9cf4ec1c7
       Name           : lets-go
       Kind           : Client
       Start time     : 2024-01-16 14:13:54.585877 +0000 UTC
       End time       : 2024-01-16 14:13:54.586 +0000 UTC
       Status code    : Unset
       Status message :
   ...
   

6. Open http://localhost:55679/debug/tracez and select one of the samples in the table to see the traces you’ve just generated.

7. After you are done, shutdown the Collector container, for example, using Control-C.

Next steps

In this tutorial you’ve started the OpenTelemetry Collector and sent telemetry to it. As next steps, consider doing the following:

• Explore different ways to install the Collector.
• Learn about the different modes of the Collector in Deployment Methods.
• Familiarize yourself with the Collector configuration files and structure.
• Explore available components in the registry.
• Learn how to build a custom Collector with the OpenTelemetry Collector Builder (OCB).