Update instrumentation concept page (open-telemetry#3996)

Signed-off-by: svrnm <neumanns@cisco.com>
Co-authored-by: Fabrizio Ferri-Benedetti <fferribenedetti@splunk.com>
Co-authored-by: Phillip Carter <pcarter@fastmail.com>

Author: 3 people

content/en/blog/2023/end-user-discussions-03.md

@@ -186,7 +186,7 @@ agent to the host metrics receiver for infrastructure monitoring.
 
 **A:** It depends on the use cases:
 
-- [Auto instrumentation](/docs/concepts/instrumentation/automatic/) options are
+- [Auto instrumentation](/docs/concepts/instrumentation/zero-code/) options are
   maturing in OTel; for example, the Java JAR agent takes care of instrumenting
   [most libraries](https://github.com/open-telemetry/opentelemetry-java-instrumentation/blob/main/docs/supported-libraries.md#libraries--frameworks)
   that are used by applications. Auto-instrumentation is also available for

content/en/blog/2023/logs-collection/index.md

@@ -425,7 +425,7 @@ extend Yoda's code to do the following:
 1. Once you have traces and logs ingested in a backend, try to correlate these
    two telemetry signal types in the backend along with a frontend such as
    Grafana.
-1. Use [Automatic Instrumentation](/docs/concepts/instrumentation/automatic/) to
+1. Use [Automatic Instrumentation](/docs/concepts/instrumentation/zero-code/) to
    further enrich telemetry.
 
 The community is currently working on the [Events API

content/en/docs/concepts/components.md

@@ -12,7 +12,7 @@ OpenTelemetry is currently made up of several main components:
 - [Language-specific API \& SDK implementations](#language-specific-api--sdk-implementations)
   - [Instrumentation Libraries](#instrumentation-libraries)
   - [Exporters](#exporters)
-  - [Automatic Instrumentation](#automatic-instrumentation)
+  - [Zero-Code Instrumentation](#zero-code-instrumentation)
   - [Resource Detectors](#resource-detectors)
   - [Cross Service Propagators](#cross-service-propagators)
   - [Sampler](#sampler)
@@ -75,7 +75,7 @@ For more information, see
 
 {{% docs/languages/exporters/intro %}}
 
-### Automatic Instrumentation
+### Zero-Code Instrumentation
 
 If applicable a language specific implementation of OpenTelemetry will provide a
 way to instrument your application without touching your source code. While the
@@ -84,7 +84,7 @@ OpenTelemetry API and SDK capabilities to your application. Additionally they
 may add a set of Instrumentation Libraries and exporter dependencies.
 
 For more information, see
-[Instrumenting](/docs/concepts/instrumentation/automatic/).
+[Zero-Code Instrumentation](/docs/concepts/instrumentation/zero-code/).
 
 ### Resource Detectors
 

content/en/docs/concepts/instrumentation/_index.md

@@ -1,8 +1,7 @@
 ---
 title: Instrumentation
 description: >-
-  How OpenTelemetry facilitates automatic and manual instrumentation of
-  applications.
+  How OpenTelemetry instrumentations libraries and applications.
 aliases: [instrumenting]
 weight: 15
 ---
@@ -12,32 +11,48 @@ from the system's components must emit [traces](/docs/concepts/signals/traces/),
 [metrics](/docs/concepts/signals/metrics/), and
 [logs](/docs/concepts/signals/logs/).
 
-Without being required to modify the source code you can collect telemetry from
-an application using [automatic instrumentation](automatic/). If you previously
-used an APM agent to extract telemetry from your application, Automatic
-Instrumentation will give you a similar out of the box experience.
-
-To facilitate the instrumentation of applications even more, you can
-[manually instrument](manual/) your applications by coding against the
-OpenTelemetry APIs.
-
-For that you don't need to instrument all the dependencies used in your
-application:
-
-- some of your libraries will be observable out of the box by calling the
-  OpenTelemetry API themselves directly. Those libraries are sometimes called
-  **natively instrumented**.
-- for libraries without such an integration the OpenTelemetry projects provide
-  language specific [Instrumentation Libraries][]
-
-Note, that for most languages it is possible to use both manual and automatic
-instrumentation at the same time: Automatic Instrumentation will allow you to
-gain insights into your application quickly and manual instrumentation will
-enable you to embed granular observability into your code.
-
-The exact installation mechanism for [manual](manual/) and
-[automatic](automatic/) instrumentation varies based on the language you’re
-developing in, but there are some similarities covered in the sections below.
-
-[instrumentation libraries]:
-  /docs/specs/otel/overview/#instrumentation-libraries
+OpenTelemetry has two primary ways to instrument.
+
+1. [Code-based solutions](/docs/concepts/instrumentation/code-based) via
+   official APIs and SDKs for eleven languages.
+2. [Zero-code solutions](/docs/concepts/instrumentation/zero-code/) that, when
+   installed, instrument libraries you use.
+
+Code-based solutions allow you to get rich telemetry from your application
+itself. They let you use the OpenTelemetry API to generate telemetry from your
+application, which acts as an essential complement to the telemetry generated by
+zero-code solutions.
+
+The Zero-code solutions are great for getting started, or when you can't modify
+the application you need to get telemetry out of. They provide rich telemetry
+from libraries you use and/or the environment your application runs in. Another
+way to think of it is that they provide information about what's happening _at
+the edges_ of your application.
+
+It's generally recommended that you use both solutions when you can.
+
+## Additional OpenTelemetry Benefits
+
+OpenTelemetry provides more than just zero-code and code-based telemetry
+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
+  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/),
+  [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.

content/en/docs/concepts/instrumentation/automatic.md

@@ -1,8 +1,9 @@
 ---
-title: Manual
+title: Code-based
 description: >-
-  Learn about the essential steps to manually instrument your application.
+  Learn about the essential steps to instrument your code base.
 weight: 20
+aliases: [manual]
 cSpell:ignore: legitimatebusiness proxying
 ---
 

content/en/docs/concepts/instrumentation/manual.md content/en/docs/concepts/instrumentation/code-based.md

@@ -0,0 +1,51 @@
+---
+title: Zero-code
+description: >-
+  Learn how to add observability to an application without the need to write
+  more code
+weight: 10
+aliases: [automatic]
+---
+
+As [ops](/docs/getting-started/ops/) you might want to add observability to one
+or more applications without having to edit the source. OpenTelemetry lets you
+quickly gain some observability for a service without having to use the
+OpenTelemetry API & SDK for
+[code-based instrumentation](/docs/concepts/instrumentation/code-based).
+
+Zero-code instrumentation adds the OpenTelemetry API and SDK capabilities to
+your application typically as an agent or agent-like installation. The specific
+mechanisms involved may differ by language, ranging from bytecode manipulation,
+monkey patching, or eBPF to inject calls to the OpenTelemetry API and SDK into
+your application.
+
+Typically, zero-code instrumentation adds instrumentation for the libraries
+you're using. This means that requests and responses, database calls, message
+queue calls, and so forth are what are instrumented. Your application's code,
+however, is not typically instrumented. To instrument your code, you'll need to
+use [code-based instrumentation](/docs/concepts/instrumentation/code-based).
+
+Additionally, zero-code instrumentation lets you configure the
+[Instrumentation Libraries](/docs/concepts/instrumentation/libraries) and
+[exporters](/docs/concepts/components/#exporters) loaded.
+
+You can configure zero-code instrumentation through environment variables and
+other language-specific mechanisms, such as system properties or arguments
+passed to initialization methods. To get started, you only need a service name
+configured so that you can identify the service in the observability backend of
+your choice.
+
+Other configuration options are available, including:
+
+- Data source specific configuration
+- Exporter configuration
+- Propagator configuration
+- Resource configuration
+
+Automatic instrumentation is available for the following languages:
+
+- [.NET](/docs/languages/net/automatic/)
+- [Java](/docs/languages/java/automatic/)
+- [JavaScript](/docs/languages/js/automatic/)
+- [PHP](/docs/languages/php/automatic/)
+- [Python](/docs/languages/python/automatic/)

content/en/docs/concepts/instrumentation/zero-code.md

@@ -14,8 +14,7 @@ instrumented automatically and instrumenting your own code with our API
 manually, we recommend that you learn the following concepts first:
 
 - [What is OpenTelemetry?](/docs/what-is-opentelemetry/)
-- [How can I instrument dependencies without touching their code?](/docs/concepts/instrumentation/automatic/)
-- [How can I instrument my application manually?](/docs/concepts/instrumentation/manual/)
+- [How can I add instrumentation to my code base?](/docs/concepts/instrumentation/code-based/)
 
 If you develop libraries, frameworks or middleware that is used as a dependency
 within other software, we recommend that you learn how you can provide telemetry

content/en/docs/getting-started/dev.md

@@ -15,7 +15,7 @@ applications without touching their code, we recommend that you learn the
 following:
 
 - [What is OpenTelemetry?](/docs/what-is-opentelemetry/)
-- [How can I instrument applications without touching their code?](/docs/concepts/instrumentation/automatic/)
+- [How can I instrument applications without touching their code?](/docs/concepts/instrumentation/zero-code/)
 - [How can I set up a collector?](/docs/collector/)
 - [How can I get automation for Kubernetes with the OpenTelemetry Operator?](/docs/kubernetes/operator/)