From 8721894913de01c71563e0ca721cfcd4065b0668 Mon Sep 17 00:00:00 2001 From: Patrice Chalin Date: Thu, 6 Mar 2025 16:55:29 -0500 Subject: [PATCH 1/4] Rework of What-is-OTel and Instrumentation pages --- .../docs/concepts/instrumentation/_index.md | 37 +++---- content/en/docs/what-is-opentelemetry.md | 98 ++++++++++--------- 2 files changed, 72 insertions(+), 63 deletions(-) diff --git a/content/en/docs/concepts/instrumentation/_index.md b/content/en/docs/concepts/instrumentation/_index.md index 39ae1d73d907..7b4daa7c440c 100644 --- a/content/en/docs/concepts/instrumentation/_index.md +++ b/content/en/docs/concepts/instrumentation/_index.md @@ -5,16 +5,15 @@ aliases: [instrumenting] weight: 15 --- -In order to make a system observable, it must be **instrumented**: That is, code -from the system's components must emit [traces](/docs/concepts/signals/traces/), -[metrics](/docs/concepts/signals/metrics/), and -[logs](/docs/concepts/signals/logs/). +For a system [observable], it must be **instrumented**: that is, code from the +system's components must emit [signals], such as [traces], [metrics], and +[logs]. Using OpenTelemetry, you can instrument your code in two primary ways: -1. [Code-based solutions](/docs/concepts/instrumentation/code-based) via - official [APIs and SDKs for most languages](/docs/languages/) -2. [Zero-code solutions](/docs/concepts/instrumentation/zero-code/) +1. [Code-based solutions](code-based/) via official + [APIs and SDKs for most languages](/docs/languages/) +2. [Zero-code solutions](zero-code/) **Code-based** solutions allow you to get deeper insight and rich telemetry from your application itself. They let you use the OpenTelemetry API to generate @@ -37,20 +36,24 @@ solutions. The following things are also a part of OpenTelemetry: - Libraries can leverage the OpenTelemetry API as a dependency, which will have no impact on applications using that library, unless the OpenTelemetry SDK is imported. -- For each [signal](/docs/concepts/signals) (traces, metrics, logs) you have - several methods at your disposals to create, process, and export them. -- With [context propagation](/docs/concepts/context-propagation) built into the +- For each of the [signals] you have several methods at your disposals to + create, process, and export them. +- With [context propagation](../context-propagation/) built into the implementations, you can correlate signals regardless of where they are generated. -- [Resources](/docs/concepts/resources) and - [Instrumentation Scopes](/docs/concepts/instrumentation-scope) allow grouping - of signals, by different entities, like, the - [host](/docs/specs/semconv/resource/host/), +- [Resources](../resources/) and + [Instrumentation Scopes](../instrumentation-scope/) allow grouping of signals, + by different entities, like, the [host](/docs/specs/semconv/resource/host/), [operating system](/docs/specs/semconv/resource/os/) or [K8s cluster](/docs/specs/semconv/resource/k8s/#cluster) - Each language-specific implementation of the API and SDK follows the requirements and expectations of the [OpenTelemetry specification](/docs/specs/otel/). -- [Semantic Conventions](/docs/concepts/semantic-conventions) provide a common - naming schema that can be used for standardization across code bases and - platforms. +- [Semantic Conventions](../semantic-conventions/) provide a common naming + schema that can be used for standardization across code bases and platforms. + +[logs]: ../signals/traces/ +[metrics]: ../signals/traces/ +[observable]: ../observability-primer/#what-is-observability +[signals]: ../signals/ +[traces]: ../signals/traces/ diff --git a/content/en/docs/what-is-opentelemetry.md b/content/en/docs/what-is-opentelemetry.md index 8db26af2c6f0..c99913c3d455 100644 --- a/content/en/docs/what-is-opentelemetry.md +++ b/content/en/docs/what-is-opentelemetry.md @@ -1,50 +1,49 @@ --- title: What is OpenTelemetry? -description: A short explanation of what OpenTelemetry is and isn't. +description: A brief explanation of what OpenTelemetry is and isn't. aliases: [/about, /docs/concepts/what-is-opentelemetry, /otel] weight: 150 --- OpenTelemetry is: -- An [Observability](/docs/concepts/observability-primer/#what-is-observability) - framework and toolkit designed to create and manage telemetry data such as - [traces](/docs/concepts/signals/traces/), - [metrics](/docs/concepts/signals/metrics/), and - [logs](/docs/concepts/signals/logs/). -- Vendor- and tool-agnostic, meaning that it can be used with a broad variety of - Observability backends, including open source tools like - [Jaeger](https://www.jaegertracing.io/) and - [Prometheus](https://prometheus.io/), as well as commercial offerings. -- Not an observability backend like Jaeger, Prometheus, or other commercial - vendors. -- Focused on the generation, collection, management, and export of telemetry. A - major goal of OpenTelemetry is that you can easily instrument your - applications or systems, no matter their language, infrastructure, or runtime - environment. The storage and visualization of telemetry is intentionally left - to other tools. +- An **[observability] framework and toolkit** designed to facilitate the + + - Generation + - Export + - Collection + + of [telemetry data][] such as [traces], [metrics], and [logs]. + +- **Open source** and **vendor- and tool-agnostic**, meaning that it can be used + with a broad variety of observability backends, including open source tools + like [Jaeger] and [Prometheus], as well as commercial offerings. OpenTelemetry + is **not** an observability backend itself. + +A major goal of OpenTelemetry is to enable easy instrumentation of your +applications and systems, regardless of the programming language, +infrastructure, and runtime environments used. + +The (backend) **storage** and (frontend) **visualization** of telemetry data are +intentionally left to other tools. ## What is observability? -[Observability](/docs/concepts/observability-primer/#what-is-observability) is -the ability to understand the internal state of a system by examining its -outputs. In the context of software, this means being able to understand the -internal state of a system by examining its telemetry data, which includes -traces, metrics, and logs. +[Observability] is the ability to understand the internal state of a system by +examining its outputs. In the context of software, this means being able to +understand the internal state of a system by examining its telemetry data, which +includes traces, metrics, and logs. To make a system observable, it must be -[instrumented](/docs/concepts/instrumentation). That is, the code must emit -[traces](/docs/concepts/signals/traces/), -[metrics](/docs/concepts/signals/metrics/), or -[logs](/docs/concepts/signals/logs/). The instrumented data must then be sent to -an observability backend. +[instrumented](../concepts/instrumentation). That is, the code must emit +[traces], [metrics], or [logs]. The instrumented data must then be sent to an +observability backend. ## Why OpenTelemetry? With the rise of cloud computing, microservices architectures, and increasingly complex business requirements, the need for software and infrastructure -[observability](/docs/concepts/observability-primer/#what-is-observability) is -greater than ever. +[observability] is greater than ever. OpenTelemetry satisfies the need for observability while following two key principles: @@ -62,24 +61,23 @@ If you want to learn more, take a look at OpenTelemetry's OpenTelemetry consists of the following major components: -- A [specification](/docs/specs/otel) for all components -- A standard [protocol](/docs/specs/otlp/) that defines the shape of telemetry - data -- [Semantic conventions](/docs/specs/semconv/) that define a standard naming - scheme for common telemetry data types +- A [specification](../specs/otel) for all components +- A standard [protocol](../specs/otlp/) that defines the shape of telemetry data +- [Semantic conventions](../specs/semconv/) that define a standard naming scheme + for common telemetry data types - APIs that define how to generate telemetry data -- [Language SDKs](/docs/languages) that implement the specification, APIs, and +- [Language SDKs](../languages) that implement the specification, APIs, and export of telemetry data - A [library ecosystem](/ecosystem/registry) that implements instrumentation for common libraries and frameworks - Automatic instrumentation components that generate telemetry data without requiring code changes -- The [OpenTelemetry Collector](/docs/collector), a proxy that receives, - processes, and exports telemetry data +- The [OpenTelemetry Collector](../collector), a proxy that receives, processes, + and exports telemetry data - Various other tools, such as the - [OpenTelemetry Operator for Kubernetes](/docs/platforms/kubernetes/operator/), - [OpenTelemetry Helm Charts](/docs/platforms/kubernetes/helm/), and - [community assets for FaaS](/docs/platforms/faas/) + [OpenTelemetry Operator for Kubernetes](../platforms/kubernetes/operator/), + [OpenTelemetry Helm Charts](../platforms/kubernetes/helm/), and + [community assets for FaaS](../platforms/faas/) OpenTelemetry is used by a wide variety of [libraries, services and apps](/ecosystem/integrations/) that have OpenTelemetry @@ -97,7 +95,7 @@ extended include: - Adding a receiver to the OpenTelemetry Collector to support telemetry data from a custom source - Loading custom instrumentation libraries into an SDK -- Creating a [distribution](/docs/concepts/distributions/) of an SDK or the +- Creating a [distribution](../concepts/distributions/) of an SDK or the Collector tailored to a specific use case - Creating a new exporter for a custom backend that doesn't yet support the OpenTelemetry protocol (OTLP) @@ -108,8 +106,7 @@ designed to make it possible at nearly every level. ## History -OpenTelemetry is a -[Cloud Native Computing Foundation (CNCF)](https://www.cncf.io) project that is +OpenTelemetry is a [Cloud Native Computing Foundation][] (CNCF) project that is the result of a [merger] between two prior projects, [OpenTracing](https://opentracing.io) and [OpenCensus](https://opencensus.io). Both of these projects were created to solve the same problem: the lack of a @@ -119,12 +116,21 @@ they merged to form OpenTelemetry and combine their strengths while offering a single solution. If you are currently using OpenTracing or OpenCensus, you can learn how to -migrate to OpenTelemetry in the [Migration guide](/docs/migration/). +migrate to OpenTelemetry in the [Migration guide](../migration/). [merger]: https://www.cncf.io/blog/2019/05/21/a-brief-history-of-opentelemetry-so-far/ ## What next? -- [Getting started](/docs/getting-started/) — jump right in! -- Learn about [OpenTelemetry concepts](/docs/concepts/). +- [Getting started](../getting-started/) — jump right in! +- Learn about [OpenTelemetry concepts](../concepts/). + +[logs]: ../concepts/signals/logs/ +[metrics]: ../concepts/signals/metrics/ +[observability]: ../concepts/observability-primer/#what-is-observability +[telemetry data]: ../concepts/signals/ +[traces]: ../concepts/signals/traces/ +[Jaeger]: https://www.jaegertracing.io/ +[Prometheus]: https://prometheus.io/ +[Cloud Native Computing Foundation]: https://www.cncf.io From 3218e4259a22a8b006756a3ca5b6b790062a6a87 Mon Sep 17 00:00:00 2001 From: Patrice Chalin Date: Thu, 6 Mar 2025 17:13:04 -0500 Subject: [PATCH 2/4] Add links for generation and collection --- content/en/docs/what-is-opentelemetry.md | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/content/en/docs/what-is-opentelemetry.md b/content/en/docs/what-is-opentelemetry.md index c99913c3d455..064385e8d8a9 100644 --- a/content/en/docs/what-is-opentelemetry.md +++ b/content/en/docs/what-is-opentelemetry.md @@ -9,9 +9,9 @@ OpenTelemetry is: - An **[observability] framework and toolkit** designed to facilitate the - - Generation + - [Generation][instr] - Export - - Collection + - [Collection](../concepts/components/#collector) of [telemetry data][] such as [traces], [metrics], and [logs]. @@ -34,10 +34,9 @@ examining its outputs. In the context of software, this means being able to understand the internal state of a system by examining its telemetry data, which includes traces, metrics, and logs. -To make a system observable, it must be -[instrumented](../concepts/instrumentation). That is, the code must emit -[traces], [metrics], or [logs]. The instrumented data must then be sent to an -observability backend. +To make a system observable, it must be [instrumented][instr]. That is, the code +must emit [traces], [metrics], or [logs]. The instrumented data must then be +sent to an observability backend. ## Why OpenTelemetry? @@ -126,11 +125,12 @@ migrate to OpenTelemetry in the [Migration guide](../migration/). - [Getting started](../getting-started/) — jump right in! - Learn about [OpenTelemetry concepts](../concepts/). +[Cloud Native Computing Foundation]: https://www.cncf.io +[instr]: ../concepts/instrumentation +[Jaeger]: https://www.jaegertracing.io/ [logs]: ../concepts/signals/logs/ [metrics]: ../concepts/signals/metrics/ [observability]: ../concepts/observability-primer/#what-is-observability +[Prometheus]: https://prometheus.io/ [telemetry data]: ../concepts/signals/ [traces]: ../concepts/signals/traces/ -[Jaeger]: https://www.jaegertracing.io/ -[Prometheus]: https://prometheus.io/ -[Cloud Native Computing Foundation]: https://www.cncf.io From e9507f28e191387cf6090c7ddb80141522737202 Mon Sep 17 00:00:00 2001 From: Patrice Chalin Date: Fri, 7 Mar 2025 10:05:18 -0500 Subject: [PATCH 3/4] Fabri's feedback Co-authored-by: Fabrizio Ferri-Benedetti --- content/en/docs/concepts/instrumentation/_index.md | 4 ++-- content/en/docs/what-is-opentelemetry.md | 4 ++-- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/content/en/docs/concepts/instrumentation/_index.md b/content/en/docs/concepts/instrumentation/_index.md index 7b4daa7c440c..b9b18be081c3 100644 --- a/content/en/docs/concepts/instrumentation/_index.md +++ b/content/en/docs/concepts/instrumentation/_index.md @@ -5,7 +5,7 @@ aliases: [instrumenting] weight: 15 --- -For a system [observable], it must be **instrumented**: that is, code from the +For a system to be [observable], it must be **instrumented**: that is, code from the system's components must emit [signals], such as [traces], [metrics], and [logs]. @@ -36,7 +36,7 @@ solutions. The following things are also a part of OpenTelemetry: - Libraries can leverage the OpenTelemetry API as a dependency, which will have no impact on applications using that library, unless the OpenTelemetry SDK is imported. -- For each of the [signals] you have several methods at your disposals to +- For each of the [signals] you have several methods at your disposal to create, process, and export them. - With [context propagation](../context-propagation/) built into the implementations, you can correlate signals regardless of where they are diff --git a/content/en/docs/what-is-opentelemetry.md b/content/en/docs/what-is-opentelemetry.md index 064385e8d8a9..e14ed96017a6 100644 --- a/content/en/docs/what-is-opentelemetry.md +++ b/content/en/docs/what-is-opentelemetry.md @@ -15,7 +15,7 @@ OpenTelemetry is: of [telemetry data][] such as [traces], [metrics], and [logs]. -- **Open source** and **vendor- and tool-agnostic**, meaning that it can be used +- **Open source**, as well as **vendor- and tool-agnostic**, meaning that it can be used with a broad variety of observability backends, including open source tools like [Jaeger] and [Prometheus], as well as commercial offerings. OpenTelemetry is **not** an observability backend itself. @@ -24,7 +24,7 @@ A major goal of OpenTelemetry is to enable easy instrumentation of your applications and systems, regardless of the programming language, infrastructure, and runtime environments used. -The (backend) **storage** and (frontend) **visualization** of telemetry data are +The backend (storage) and the frontend (visualization) of telemetry data are intentionally left to other tools. ## What is observability? From 68f91e70a2572186089031ced8e71efd09a5b78e Mon Sep 17 00:00:00 2001 From: opentelemetrybot <107717825+opentelemetrybot@users.noreply.github.com> Date: Fri, 7 Mar 2025 15:07:28 +0000 Subject: [PATCH 4/4] Results from /fix:format --- content/en/docs/concepts/instrumentation/_index.md | 8 ++++---- content/en/docs/what-is-opentelemetry.md | 8 ++++---- 2 files changed, 8 insertions(+), 8 deletions(-) diff --git a/content/en/docs/concepts/instrumentation/_index.md b/content/en/docs/concepts/instrumentation/_index.md index b9b18be081c3..a9bdb5763dc5 100644 --- a/content/en/docs/concepts/instrumentation/_index.md +++ b/content/en/docs/concepts/instrumentation/_index.md @@ -5,8 +5,8 @@ aliases: [instrumenting] weight: 15 --- -For a system to be [observable], it must be **instrumented**: that is, code from the -system's components must emit [signals], such as [traces], [metrics], and +For a system to be [observable], it must be **instrumented**: that is, code from +the system's components must emit [signals], such as [traces], [metrics], and [logs]. Using OpenTelemetry, you can instrument your code in two primary ways: @@ -36,8 +36,8 @@ solutions. The following things are also a part of OpenTelemetry: - Libraries can leverage the OpenTelemetry API as a dependency, which will have no impact on applications using that library, unless the OpenTelemetry SDK is imported. -- For each of the [signals] you have several methods at your disposal to - create, process, and export them. +- For each of the [signals] you have several methods at your disposal to create, + process, and export them. - With [context propagation](../context-propagation/) built into the implementations, you can correlate signals regardless of where they are generated. diff --git a/content/en/docs/what-is-opentelemetry.md b/content/en/docs/what-is-opentelemetry.md index e14ed96017a6..985e0203cc77 100644 --- a/content/en/docs/what-is-opentelemetry.md +++ b/content/en/docs/what-is-opentelemetry.md @@ -15,10 +15,10 @@ OpenTelemetry is: of [telemetry data][] such as [traces], [metrics], and [logs]. -- **Open source**, as well as **vendor- and tool-agnostic**, meaning that it can be used - with a broad variety of observability backends, including open source tools - like [Jaeger] and [Prometheus], as well as commercial offerings. OpenTelemetry - is **not** an observability backend itself. +- **Open source**, as well as **vendor- and tool-agnostic**, meaning that it can + be used with a broad variety of observability backends, including open source + tools like [Jaeger] and [Prometheus], as well as commercial offerings. + OpenTelemetry is **not** an observability backend itself. A major goal of OpenTelemetry is to enable easy instrumentation of your applications and systems, regardless of the programming language,