Collector quick start

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 <http://localhost:55679/debug/tracez> 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
+   <kbd>Control-C</kbd>.
+
+## 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/