diff --git a/content/en/docs/collector/getting-started.md b/content/en/docs/collector/getting-started.md deleted file mode 100644 index b809bba59736..000000000000 --- a/content/en/docs/collector/getting-started.md +++ /dev/null @@ -1,93 +0,0 @@ ---- -title: Getting Started -cSpell:ignore: docker dokey dpkg okey telemetrygen -description: Test the OpenTelemetry Collector in five minutes -weight: 1 ---- - -The OpenTelemetry Collector receives [traces](/docs/concepts/signals/traces/), -[metrics](/docs/concepts/signals/metrics/) and -[logs](/docs/concepts/signals/logs/), processes the telemetry, and exports it to -a wide variety of observability backends using its components. For a conceptual -overview of the Collector, read the [introduction](/docs/collector). - -The following tutorial shows how to deploy the OpenTelemetry Collector and send -telemetry to it using the default configuration and the -[telemetrygen](https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/main/cmd/telemetrygen) -utility. - -## Prerequisites - -To follow this tutorial you need the following - -- [Go](https://go.dev/) 1.20 or higher - -## Test the OpenTelemetry Collector in five minutes - -1. Pull the OpenTelemetry Collector Docker image and run the collector in a - container: - - ```sh - docker pull otel/opentelemetry-collector:{{% param vers %}} - docker run -p 127.0.0.1:4317:4317 -p 127.0.0.1:55679:55679 otel/opentelemetry-collector:{{% param vers %}} - ``` - -2. Download and install the `telemetrygen` utility from the - [opentelemetry-collector-contrib](https://github.com/open-telemetry/opentelemetry-collector-contrib/) - repository: - - ```sh - go install github.com/open-telemetry/opentelemetry-collector-contrib/cmd/telemetrygen@latest - ``` - - The command should install `telemetrygen` inside the local `go/bin` - directory. - -3. The `telemetrygen` command generates dummy telemetry for testing. In a new - terminal window, send some traces to the collector: - - ```sh - telemetrygen traces --otlp-insecure --duration 5s - ``` - - After five seconds, `telemetrygen` stops and shows the sent messages in the - console: - - ```text - 2023-10-23T12:58:19.835+0200 INFO traces/worker.go:88 traces generated {"worker": 0, "traces": 994418} - 2023-10-23T12:58:19.835+0200 INFO traces/traces.go:79 stop the batch span processor - ``` - - In the terminal window, running the Collector container, logs should show - activity related to the trace ingest similar to this: - - ```text - Span #434 - Trace ID : ba7ef95fce7499811ca72158350c907c - Parent ID : 1d3c9f49b3f2cf47 - ID : 7609079dc6253034 - Name : okey-dokey - Kind : Server - Start time : 2023-10-23 11:01:29.53251 +0000 UTC - End time : 2023-10-23 11:01:29.532634 +0000 UTC - Status code : Unset - Status message : - ``` - -4. Open `http://localhost:55679/debug/tracez` in your browser and select one of - the samples in the table to see the traces you've just generated. - -## 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](../installation/). -- Learn about the different modes of the Collector in - [Deployment Methods](../deployment/). -- Familiarize yourself with the Collector - [configuration](/docs/collector/configuration) files and structure. -- Explore available components in the - [registry](/ecosystem/registry/?language=collector) -- Learn how to - [build a custom Collector with the OpenTelemetry Collector Builder (OCB)](/docs/collector/custom-collector/) diff --git a/content/en/docs/collector/quick-start.md b/content/en/docs/collector/quick-start.md new file mode 100644 index 000000000000..3a3d4e725dba --- /dev/null +++ b/content/en/docs/collector/quick-start.md @@ -0,0 +1,141 @@ +--- +title: Quick start +cSpell:ignore: docker dokey dpkg okey telemetrygen +description: Setup and collect telemetry in minutes! +aliases: [getting-started] +weight: 1 +cSpell:ignore: gobin +--- + +The OpenTelemetry Collector receives [traces](/docs/concepts/signals/traces/), +[metrics](/docs/concepts/signals/metrics/), and +[logs](/docs/concepts/signals/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](/docs/collector). + +In this page you'll learn how 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 + +Ensure 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. + +- [Go](https://go.dev/) 1.20 or higher +- [`GOBIN` environment variable][gobin] is set; if not initialize it + appropriately, for example[^1]: + ```sh + export GOBIN=${GOBIN:-$(go env GOPATH)/bin} + ``` + [gobin]: https://pkg.go.dev/cmd/go#hdr-Environment_variables + [^1]: + For more information, see + [Your first program](https://go.dev/doc/code#Command). + +## Set up + +1. Pull in the OpenTelemetry Collector Docker image: + + ```sh + docker pull otel/opentelemetry-collector:{{% param vers %}} + ``` + +2. Install the [telemetrygen] utility: + + ```sh + 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: + + ```sh + docker run \ + -p 127.0.0.1:4317:4317 \ + -p 127.0.0.1:55679:55679 \ + otel/opentelemetry-collector:{{% param vers %}} \ + 2>&1 | tee collector-output.txt # Optionally tee output for easier search later + ``` + +4. In a separate terminal window, generate a few sample traces: + + ```sh + $GOBIN/telemetrygen traces --otlp-insecure --traces 3 + ``` + + Among the output generated by the utility, you should see a confirmation that + traces were generated: + + ```text + 2023-10-23T12:58:19.835+0200 INFO traces/worker.go:88 traces generated {"worker": 0, "traces": 994418} + 2023-10-23T12:58:19.835+0200 INFO traces/traces.go:79 stop the batch span processor + ``` + + For an easier time seeing relevant output you can filter it: + + ```sh + $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 below: + + ```console + $ 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 and select one of the samples in + the table to see the traces you've just generated. + +7. Once 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](../installation/). +- Learn about the different modes of the Collector in + [Deployment Methods](../deployment/). +- Familiarize yourself with the Collector + [configuration](/docs/collector/configuration) files and structure. +- Explore available components in the + [registry](/ecosystem/registry/?language=collector). +- Learn how to + [build a custom Collector with the OpenTelemetry Collector Builder (OCB)](/docs/collector/custom-collector/). + +[logs]: /docs/concepts/signals/logs/ +[metrics]: /docs/concepts/signals/metrics/ +[telemetrygen]: + https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/main/cmd/telemetrygen +[traces]: /docs/concepts/signals/traces/