diff --git a/content/en/blog/2022/apisix/index.md b/content/en/blog/2022/apisix/index.md index a89582f9245b..4d66fd24047a 100644 --- a/content/en/blog/2022/apisix/index.md +++ b/content/en/blog/2022/apisix/index.md @@ -192,7 +192,7 @@ resulting in a call chain consisting of two spans. ### Step 1: Deploy OpenTelemetry The following uses `docker compose` as an example. For other deployments, see -[Getting Started](/docs/collector/getting-started/). +[Quick start](/docs/collector/quick-start/). You can see the following command to deploy[^1]: diff --git a/content/en/blog/2022/k8s-otel-expose/index.md b/content/en/blog/2022/k8s-otel-expose/index.md index a71ec71fdbcc..e04bf6e6c0b5 100644 --- a/content/en/blog/2022/k8s-otel-expose/index.md +++ b/content/en/blog/2022/k8s-otel-expose/index.md @@ -106,8 +106,8 @@ in this setup are mentioned in brackets. [v1.2.1] installed. - A Kubernetes [v1.23.3] edge cluster to create a test cluster. Using [Kind](https://kind.sigs.k8s.io/) is recommended. -- Installed [OpenTelemetry Operator](/docs/collector/getting-started) [v0.58.0] - on both ends. +- Installed [OpenTelemetry Operator](/docs/kubernetes/operator/) [v0.58.0] on + both ends. - Installed [Jaeger Operator](https://www.jaegertracing.io/docs/1.37/operator/) [v1.37.0] on your public cluster. - Installed [cert-manager](https://cert-manager.io/) [v1.9.1] on your public diff --git a/content/en/blog/2023/k8s-runtime-observability/index.md b/content/en/blog/2023/k8s-runtime-observability/index.md index f945b406ba81..2a520b4c82bf 100644 --- a/content/en/blog/2023/k8s-runtime-observability/index.md +++ b/content/en/blog/2023/k8s-runtime-observability/index.md @@ -472,5 +472,5 @@ are available from the Tracetest repository. - [Traces For Kubernetes System Components](https://kubernetes.io/docs/concepts/cluster-administration/system-traces/) - [Tracing on ContainerD](https://github.com/containerd/containerd/blob/main/docs/tracing.md) - [Kubernetes: Tools for Monitoring Resources](https://kubernetes.io/docs/tasks/debug/debug-cluster/resource-usage-monitoring/) -- [Getting Started with OTel Collector](/docs/collector/getting-started/) +- [OTel Collector quick start](/docs/collector/quick-start/) - [Boosting Kubernetes container runtime observability with OpenTelemetry](https://kubernetes.io/blog/2022/12/01/runtime-observability-opentelemetry/) diff --git a/content/en/docs/collector/_index.md b/content/en/docs/collector/_index.md index 9978cb243616..dc514f972379 100644 --- a/content/en/docs/collector/_index.md +++ b/content/en/docs/collector/_index.md @@ -48,10 +48,9 @@ it allows your service to offload data quickly and the collector can take care of additional handling like retries, batching, encryption or even sensitive data filtering. -It is also easier to [setup a collector](./getting-started) than you might -think: the default OTLP exporters in each language assume a local collector -endpoint, so if you launch a collector it will automatically start receiving -telemetry. +It is also easier to [setup a collector](quick-start) than you might think: the +default OTLP exporters in each language assume a local collector endpoint, so if +you launch a collector it will automatically start receiving telemetry. ## Status and releases 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/management.md b/content/en/docs/collector/management.md index 3477fd777eb0..d41987eea02b 100644 --- a/content/en/docs/collector/management.md +++ b/content/en/docs/collector/management.md @@ -11,8 +11,8 @@ deployment at scale. To get the most out of this page you should know how to install and configure the collector. These topics are covered elsewhere: -- [Getting Started][otel-collector-getting-started] to understand how to install - the OpenTelemetry Collector. +- [Quick Start](/docs/collector/quick-start/) to understand how to install the + OpenTelemetry Collector. - [Configuration][otel-collector-configuration] for how to configure the OpenTelemetry Collector, setting up telemetry pipelines. @@ -217,8 +217,7 @@ otelcol_receiver_refused_metric_points{receiver="prometheus/own_metrics",service - [What is OpAMP & What is BindPlane][opamp-bindplane] [otel-collector]: /docs/collector/ -[otel-collector-getting-started]: /docs/collector/getting-started -[otel-collector-configuration]: /docs/collector/configuration +[otel-collector-configuration]: /docs/collector/configuration/ [opamp-spec]: https://github.com/open-telemetry/opamp-spec/blob/main/specification.md [opamp-in-otel-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..f6620c1c3624 --- /dev/null +++ b/content/en/docs/collector/quick-start.md @@ -0,0 +1,144 @@ +--- +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). + +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. + +- [Go](https://go.dev/) 1.20 or higher +- [`GOBIN` environment variable][gobin] is set; if unset, initialize it + appropriately, for example[^1]: + ```sh + export GOBIN=${GOBIN:-$(go env GOPATH)/bin} + ``` + +[^1]: + For more information, see + [Your first program](https://go.dev/doc/code#Command). + +## Set up the environment + +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 + 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: + + ```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 in the following example: + + ```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. 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](../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/). + +[gobin]: https://pkg.go.dev/cmd/go#hdr-Environment_variables +[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/ diff --git a/content/en/docs/languages/python/getting-started.md b/content/en/docs/languages/python/getting-started.md index 99042100fb1e..b9e291389f93 100644 --- a/content/en/docs/languages/python/getting-started.md +++ b/content/en/docs/languages/python/getting-started.md @@ -640,9 +640,9 @@ emitted to the console, with separate counts for each roll value: ## Send telemetry to an OpenTelemetry Collector -The [OpenTelemetry Collector](/docs/collector/getting-started/) is a critical -component of most production deployments. Some examples of when it's beneficial -to use a collector: +The [OpenTelemetry Collector](/docs/collector/) is a critical component of most +production deployments. Some examples of when it's beneficial to use a +collector: - A single telemetry sink shared by multiple services, to reduce overhead of switching exporters diff --git a/static/refcache.json b/static/refcache.json index c94dcca13e18..3af1b4a3a3ac 100644 --- a/static/refcache.json +++ b/static/refcache.json @@ -3987,6 +3987,10 @@ "StatusCode": 200, "LastSeen": "2023-09-25T10:17:08.450210292Z" }, + "https://go.dev/doc/code#Command": { + "StatusCode": 200, + "LastSeen": "2024-01-16T09:38:29.715064-05:00" + }, "https://go.dev/doc/install/gccgo": { "StatusCode": 200, "LastSeen": "2024-01-18T19:01:53.277862-05:00" @@ -5363,6 +5367,10 @@ "StatusCode": 200, "LastSeen": "2024-01-18T19:07:28.767134-05:00" }, + "https://pkg.go.dev/cmd/go#hdr-Environment_variables": { + "StatusCode": 200, + "LastSeen": "2024-01-16T09:38:27.962889-05:00" + }, "https://pkg.go.dev/github.com/XSAM/otelsql": { "StatusCode": 200, "LastSeen": "2024-01-08T12:17:16.696764+01:00"