diff --git a/tutorial/content/intro/overview_of_otel/index.md b/tutorial/content/intro/overview_of_otel/index.md index 716a786..16d5bc8 100644 --- a/tutorial/content/intro/overview_of_otel/index.md +++ b/tutorial/content/intro/overview_of_otel/index.md @@ -67,20 +67,13 @@ The implementation of a signal consists of two parts: Generally speaking, we use the OpenTelemetry API to add instrumentation to our source code. -In practice, instrumentation can be achieved in various ways, such as: -- manual instrumentation - - requires modification of the source code - - allows fine-grained control over what and how telemetry gets generated -- auto-instrumentation (if available) and library instrumentation to avoid code changes - - can be used to get started quickly with observability - - collects predefined metrics, traces and logs within a library or framework - - added after the fact by injecting an agent (or already included inside the library or framework) - - requires close to zero code changes -- and native instrumentation (already instrumented with OpenTelemetry) - -We'll look at them later in more detail. +In practice, this can be achieved in various ways, such as: +- manual instrumentation (for fine-grained control) +- auto-instrumentation and instrumentation libraries (if available and to avoid code changes) +- by using code that has already been instrumented with OpenTelemetry + -For now, let's focus on why OpenTelemetry decided to separate the API from the SDK. +For now, let's skip futher details an focus on why OpenTelemetry decided to separate the API from the SDK. On startup, the application registers a provider for every type of signal. After that, calls to the API are forwarded to the respective provider. If we don't explicitly register one, OpenTelemetry will use a fallback provider that translates API calls into no-ops. diff --git a/tutorial/content/labs/instrumentation/automatic/_index.md b/tutorial/content/labs/instrumentation/automatic/_index.md index c19c5be..e9ca387 100644 --- a/tutorial/content/labs/instrumentation/automatic/_index.md +++ b/tutorial/content/labs/instrumentation/automatic/_index.md @@ -22,3 +22,8 @@ Recognizing these burdens, OpenTelemetry tries to simplify the user experience For example, it is designed to integrate well with pre-existing solutions and allows for incremental migration strategies. This section explores the mechanisms OpenTelemetry provides for producing telemetry with zero code changes. This is where instrumentation libraries and auto-instrumentation come in. + + - can be used to get started quickly with observability + - collects predefined metrics, traces and logs within a library or framework + - added after the fact by injecting an agent (or already included inside the library or framework) + - requires close to zero code changes \ No newline at end of file diff --git a/tutorial/content/labs/instrumentation/manual/_index.md b/tutorial/content/labs/instrumentation/manual/_index.md index af9a542..cdc738e 100644 --- a/tutorial/content/labs/instrumentation/manual/_index.md +++ b/tutorial/content/labs/instrumentation/manual/_index.md @@ -5,10 +5,26 @@ draft = false weight = 1 +++ - +Welcome to the lab on manual instrumentation! +Let's look at how to instrument an application by directly using API and SDK packages provided by OpenTelemetry. +In other words, manual instrumentation requires you to make modifications to the source code. +This comes with its fair share of benefits and disadvantages. +The biggest disadvantage is that if you are just starting out, writing manual instrumentation can be daunting because you: +- need to get familiar with OpenTelemetry packages +- must be willing to explore how telemetry signals work under the hood + +It's totally reasonable to think that this is asking too much of the developers in your organization. +Another downside could be that you don't want to add observability instrumentation to your code base. +If that's the case, don't worry; there are other options to generate and emit telemetry. +We'll look at them in later chapters. + +However, there are also reasons for using manual instrumentation: +- some languages do not support auto-instrumentation +- provides fine-grained control over what and how telemetry gets generated +- you want to make observability part of the development process +- you are a library author or maintainer who wants to offer native instrumentation to your users + +So let's get started. \ No newline at end of file +--> + diff --git a/tutorial/content/labs/instrumentation/manual/metrics/index.md b/tutorial/content/labs/instrumentation/manual/metrics/index.md index b35ed33..d0a31fe 100644 --- a/tutorial/content/labs/instrumentation/manual/metrics/index.md +++ b/tutorial/content/labs/instrumentation/manual/metrics/index.md @@ -11,8 +11,6 @@ A `MetricReader` in OpenTelemetry is an interface that defines how to read metri The metric data model in OpenTelemetry defines the structure of the data that is collected and exported by the SDK. It includes information about the resource, instrumentation library, and the actual metrics data. Here's an example of what the metric data model might look like in JSON format: -The lab environment is deliberately designed to be as minimal as possible. It aims to teach fundamental concepts of OpenTelemetry over providing a highly a realistic deployment scenario. - ### How to perform the exercise * You need to either start the [repository](https://github.com/JenSeReal/otel-getting-started/) with Codespaces, Gitpod or clone the repository with git and run it locally with dev containers or docker compose * Initial directory: `labs/manual-instrumentation-metrics/initial` diff --git a/tutorial/content/labs/instrumentation/manual/traces/index.md b/tutorial/content/labs/instrumentation/manual/traces/index.md index 22bb6d4..374740b 100644 --- a/tutorial/content/labs/instrumentation/manual/traces/index.md +++ b/tutorial/content/labs/instrumentation/manual/traces/index.md @@ -5,19 +5,6 @@ draft: false weight: 2 --- - - - -The lab environment is deliberately designed to be as minimal as possible. It aims to teach fundamental concepts of OpenTelemetry over providing a highly a realistic deployment scenario. - ### How to perform the exercise * You need to either start the [repository](https://github.com/JenSeReal/otel-getting-started/) with Codespaces, Gitpod or clone the repository with git and run it locally with dev containers or docker compose * Initial directory: `labs/manual-instrumentation-traces/initial`