Learn OpenTelemetry: New Getting Started & Best Practices

assets/js/navScroll.js

@@ -1,3 +1,7 @@
+const {
+  validateAdditionalItems,
+} = require('ajv/dist/vocabularies/applicator/additionalItems');
+
 // Check If an Element is Visible in the Viewport
 function isInViewport(element) {
   const rect = element.getBoundingClientRect();
@@ -15,3 +19,31 @@ let ele = document.querySelector('#td-section-nav .td-sidebar-nav-active-item');
 if (ele && !isInViewport(ele)) {
   ele.scrollIntoView({ behavior: 'smooth', block: 'end', inline: 'nearest' });
 }
+
+let _activeVar = '';
+
+document
+  .querySelectorAll('option[data-bs-toggle="tab"]')
+  .forEach(function (tab) {
+    tab.addEventListener('show.bs.tab', function (event) {
+      let _newVar = event.target.textContent.toLowerCase();
+      if (_activeVar != _newVar) {
+        console.log('activate');
+        _activeVar = _newVar;
+        document.querySelectorAll(`.code-vars`).forEach(function (v) {
+          v.style.display = 'none';
+        });
+        document
+          .querySelectorAll(`.code-vars-${_activeVar}`)
+          .forEach(function (v) {
+            v.style.display = 'inline';
+          });
+      }
+    });
+
+    tab.addEventListener('shown.bs.tab', function (event) {
+      if (event.target.classList.contains('active')) {
+        event.target.selected = true;
+      }
+    });
+  });

content/en/docs/learn/_index.md

@@ -0,0 +1,18 @@
+---
+title: Learn OpenTelemetry
+description:
+weight: 160
+---
+
+This section of the OpenTelemetry documentation contains tutorials, that will
+help you to cover the basics of Observability using OpenTelemetry and that will
+teach you best practices for common advanced topics.
+
+If you are new to OpenTelemetry, we recommend that you dive into the
+[Getting Started](./getting-started/) first. By doing them, you will learn
+hands-on about the main concepts, features and components of OpenTelemetry.
+
+After completing the [Getting Started](./getting-started/), you can either dive
+into the [Best Practices](./best-practices/), and learn more advanced topics
+using hands on tutorials, or you can explore other sections of the
+[OpenTelemetry Documentation](/docs) based on your needs and learning goals.

content/en/docs/learn/best-practices/_index.md

@@ -0,0 +1,6 @@
+---
+title: Best Practices
+description:
+weight: 90
+aliases: [/docs/getting-started]
+---

content/en/docs/learn/getting-started/_index.md

@@ -0,0 +1,6 @@
+---
+title: Getting Started
+description:
+weight: 10
+aliases: [/docs/getting-started]
+---

content/en/docs/learn/getting-started/add-context/index.md

@@ -0,0 +1,9 @@
+---
+title: Add Context
+description:
+weight: 90
+---
+
+In this section you will learn about Resources, Instrumentation Scope, Exemplars
+and other ways that allow you to add more context to different kinds of
+telemetry.

content/en/docs/learn/getting-started/add-telemetry/index.md

@@ -0,0 +1,42 @@
+---
+title: Add Telemetry
+description: Add traces, metrics and logs to your application
+weight: 30
+---
+
+In this section we will capture traces, metrics and logs from your application.
+You will learn how to extract telemetry from your dependencies, and how you can
+add telemetry to your custom code.
+
+## Instrumenting libraries
+
+As a first step, you will learn how to extract traces, metrics and logs from
+your dependencies. There are three different situations you will encounter, when
+looking into the observability of a library or framework:
+
+- The library is _natively instrumented_, and comes with OpenTelemetry support
+  by default. You can get traces, metrics and logs emitted from that library by
+  adding and setting up the OpenTelemetry SDK with your app.
+- If a library is not _natively instrumented_, there might be an
+  _instrumnetation library_ available, which is an additional dependency you can
+  add to your project. This instrumentation library will inject OpenTelemetry
+  API calls into the other library, such that it will emit telemetry.
+- In some cases, you will encounter libraries which are neither _natively
+  instrumented_ nor can be instrumented using an existing _instrumentation
+  library_. We will skip this situation in this beginners tutorial.
+
+### Using natively instrumented libraries
+
+### Using instrumentation libraries
+
+### Finding instrumentation for libraries
+
+## Instrumenting custom code
+
+Add logs, metrics, traces
+
+### Add traces
+
+### Add metrics
+
+### Add logs

content/en/docs/learn/getting-started/collector-setup/sdk-setup/index.md

@@ -0,0 +1,11 @@
+---
+title: Setup the Collector
+description:
+weight: 50
+---
+
+In this section you will learn how you can setup common receivers, processors,
+connectors and exporters of the OpenTelemetry collector. You will use the OTLP
+receiver to capture data from your application, then transform it using the
+`transform processor` and finally export the telemetry to the console or to an
+OTLP compatible backend that can visualize your telemetry.

content/en/docs/learn/getting-started/correlate-across-services/index.md

@@ -0,0 +1,10 @@
+---
+title: Correlate across Services
+description:
+weight: 70
+---
+
+In this section we will add the coordinator service and a second player service
+to your application. You will learn how OpenTelemetry propagates information
+across service boundaries, such that you can see telemetry being stitched
+together across services in your visualization backend.

content/en/docs/learn/getting-started/export-telemetry/index.md

@@ -0,0 +1,16 @@
+---
+title: Export Telemetry
+description: Export telemetry to the OpenTelemetry Collector or a backend
+weight: 40
+---
+
+In this section you will learn how to export the telemetry your app is
+generating. You will output your telemetry to the console, then use the OTLP
+exporter to send telemetry to the OpenTelemetry collector or a compatible
+backend.
+
+## Export to the console
+
+## Export via OTLP
+
+## Other exporters

content/en/docs/learn/getting-started/overview.md

@@ -0,0 +1,45 @@
+---
+title: >-
+  Overview
+description: What you'll be building
+weight: -1
+---
+
+For this tutorial, you will be starting with an _uninstrumented_ distributed
+[sample app](./sample-application/). _Uninstrumented_ means, that this app will
+initially not have any code, that will emit telemetry, such as
+[traces](/docs/concepts/signals/traces),
+[metrics](/docs/concepts/signals/metrics) and
+[logs](/docs/concepts/signals/logs).
+
+You will [add the OpenTelemetry SDK](./sdk-setup/code/) to that application, and
+afterwards [_instrument_](./add-telemetry/) the application by adding traces,
+metrics and logs. You will do that, for your dependencies and for your custom
+code.
+
+When you have successfully instrumented the app, you will learn how to
+[export your telemetry](./export-telemetry/) to the console and then using OTLP
+to the OpenTelemetry collector. You will see how you can
+[receive telemetry with the collector](./collector-setup/), process that
+telemetry and eventually export it to a backend, that can
+[visualize your data](./visualization/).
+
+Finally, you will learn how OpenTelemetry can
+[correlate telemetry across service boundaries](./correlate-across-services/),
+and how you can [add more context](./add-context/), like service, container or
+host information to your telemetry.
+
+By the end of the tutorial, you will have learned how to instrument your own app
+using OpenTelemetry.
+
+Start by setting up the [sample application](./sample-application/) that will be
+used throughout the tutorial.
+
+{{% alert title="Note" color="info" %}}
+
+You can follow the tutorial using your own application as well, but we recommend
+that you use the provided [sample application](./sample-application.md) when you
+go through it for the first time, such that you have an easier time when you
+need to troubleshoot or go back some steps.
+
+{{% /alert %}}

content/en/docs/learn/getting-started/sample-application/code/go.md

@@ -0,0 +1,67 @@
+---
+headless: true
+title: Go
+params:
+  app-file: main.go
+  lib-file: rolldice.go
+---
+
+{{% code-block "init" %}}
+
+```bash
+go mod init dice
+```
+
+{{% /code-block %}} {{% code-block "app-file" %}}
+
+```go
+/* main.go */
+package main
+
+import (
+	"log"
+	"net/http"
+)
+
+func main() {
+	http.HandleFunc("/rolldice", rolldice)
+
+	log.Fatal(http.ListenAndServe(":8080", nil))
+}
+```
+
+{{% /code-block %}}
+
+{{% code-block "lib-file" %}}
+
+```go
+package main
+
+import (
+	"io"
+	"log"
+	"math/rand"
+	"net/http"
+	"strconv"
+)
+
+func rolldice(w http.ResponseWriter, r *http.Request) {
+	roll := 1 + rand.Intn(6)
+
+	resp := strconv.Itoa(roll) + "\n"
+	if _, err := io.WriteString(w, resp); err != nil {
+		log.Printf("Write failed: %v\n", err)
+	}
+}
+```
+
+{{% /code-block %}}
+
+{{% code-block "run-app" %}}
+
+```console
+$ node app.js
+Listening for requests on http://localhost:8080
+```
+
+{{% /code-block %}}