Extending with custom manual instrumentation (#5789)

Co-authored-by: Severin Neumann <[email protected]>
Co-authored-by: Trask Stalnaker <[email protected]>

content/en/docs/languages/java/api.md

@@ -560,6 +560,14 @@ public class AttributesUsage {
 
 ### OpenTelemetry
 
+{{% alert title="Spring Boot Starter" %}} The Spring Boot starter is a special
+case where `OpenTelemetry` is available as a Spring bean. Simply inject
+`OpenTelemetry` into your Spring components.
+
+Read more about
+[extending the Spring Boot starter with custom manual instrumentation](/docs/zero-code/java/spring-boot-starter/api/).
+{{% /alert %}}
+
 [OpenTelemetry](https://www.javadoc.io/doc/io.opentelemetry/opentelemetry-api/latest/io/opentelemetry/api/OpenTelemetry.html)
 is a holder for top-level API components which is convenient to pass to
 instrumentation.
@@ -602,6 +610,14 @@ public class OpenTelemetryUsage {
 
 ### GlobalOpenTelemetry
 
+{{% alert title="Java agent" %}} The Java agent is a special case where
+`GlobalOpenTelemetry` is set by the agent. Simply call
+`GlobalOpenTelemetry.get()` to access the `OpenTelemetry` instance.
+
+Read more about
+[extending the Java agent with custom manual instrumentation](/docs/zero-code/java/agent/api/).
+{{% /alert %}}
+
 [GlobalOpenTelemetry](https://www.javadoc.io/doc/io.opentelemetry/opentelemetry-api/latest/io/opentelemetry/api/GlobalOpenTelemetry.html)
 holds a global singleton [OpenTelemetry](#opentelemetry) instance.
 

content/en/docs/zero-code/java/agent/annotations.md

@@ -135,6 +135,4 @@ instrumented.
 ## Next steps
 
 Beyond the use of annotations, the OpenTelemetry API allows you to obtain a
-tracer that can be used for
-[Manual Instrumentation](/docs/languages/java/instrumentation/) and execute code
-within the scope of that span.
+tracer that can be used for [custom instrumentation](../api).

content/en/docs/zero-code/java/agent/api.md

@@ -0,0 +1,84 @@
+---
+title: Extending instrumentations with the API
+linkTitle: Extend with the API
+description:
+  Use the OpenTelemetry API in combination with the Java agent to extend the
+  automatically generated telemetry with custom spans and metrics
+weight: 21
+---
+
+## Introduction
+
+In addition to the out-of-the-box instrumentation, you can extend the Java agent
+with custom manual instrumentation using the OpenTelemetry API. This allows you
+to create [spans](/docs/concepts/signals/traces/#spans) and
+[metrics](/docs/concepts/signals/metrics) for your own code without doing too
+many code changes.
+
+## Dependencies
+
+Add a dependency on the `opentelemetry-api` library.
+
+### Maven
+
+```xml
+<dependencies>
+  <dependency>
+    <groupId>io.opentelemetry</groupId>
+    <artifactId>opentelemetry-api</artifactId>
+    <version>{{% param vers.otel %}}</version>
+  </dependency>
+</dependencies>
+```
+
+### Gradle
+
+```groovy
+dependencies {
+    implementation('io.opentelemetry:opentelemetry-api:{{% param vers.otel %}}')
+}
+```
+
+## OpenTelemetry
+
+The Java agent is a special case where `GlobalOpenTelemetry` is set by the
+agent. Simply call `GlobalOpenTelemetry.get()` to access the `OpenTelemetry`
+instance.
+
+## Span
+
+{{% alert title="Note" color="info" %}}
+
+For the most common use cases, use the `@WithSpan` annotation instead of manual
+instrumentation. See [Annotations](../annotations) for more information.
+
+{{% /alert %}}
+
+```java
+import io.opentelemetry.api.GlobalOpenTelemetry;
+import io.opentelemetry.api.trace.Tracer;
+
+Tracer tracer = GlobalOpenTelemetry.getTracer("application");
+```
+
+Use the `Tracer` to create a span as explained in the
+[Span](/docs/languages/java/api/#span) section.
+
+A full example can be found in the [example repository].
+
+## Meter
+
+```java
+import io.opentelemetry.api.GlobalOpenTelemetry;
+import io.opentelemetry.api.metrics.Meter;
+
+Meter meter = GlobalOpenTelemetry.getMeter("application");
+```
+
+Use the `Meter` to create a counter, gauge or histogram as explained in the
+[Meter](/docs/languages/java/api/#meter) section.
+
+A full example can be found in the [example repository].
+
+[example repository]:
+  https://github.com/open-telemetry/opentelemetry-java-examples/tree/main/javaagent

content/en/docs/zero-code/java/spring-boot-starter/annotations.md

@@ -120,3 +120,8 @@ annotation:
 | Name    | Type     | Description    | Default Value         |
 | ------- | -------- | -------------- | --------------------- |
 | `value` | `String` | Attribute name | Method parameter name |
+
+## Next steps
+
+Beyond the use of annotations, the OpenTelemetry API allows you to obtain a
+tracer that can be used [custom instrumentation](../api).

content/en/docs/zero-code/java/spring-boot-starter/api.md

@@ -0,0 +1,75 @@
+---
+title: Extending instrumentations with the API
+linkTitle: Extend with the API
+description:
+  Use the OpenTelemetry API in combination with the Spring Boot starter to
+  extend the automatically generated telemetry with custom spans and metrics
+weight: 21
+---
+
+## Introduction
+
+In addition to the out-of-the-box instrumentation, you can extend the Spring
+starter with custom manual instrumentation using the OpenTelemetry API. This
+allows you to create [spans](/docs/concepts/signals/traces/#spans) and
+[metrics](/docs/concepts/signals/metrics) for your own code without doing too
+many code changes.
+
+The required dependencies are already included in the Spring Boot starter.
+
+## OpenTelemetry
+
+The Spring Boot starter is a special case where `OpenTelemetry` is available as
+a Spring bean. Simply inject `OpenTelemetry` into your Spring components.
+
+## Span
+
+{{% alert title="Note" color="info" %}}
+
+For the most common use cases, use the `@WithSpan` annotation instead of manual
+instrumentation. See [Annotations](../annotations) for more information.
+
+{{% /alert %}}
+
+```java
+import io.opentelemetry.api.OpenTelemetry;
+import io.opentelemetry.api.trace.Tracer;
+
+@Controller
+public class MyController {
+  private final Tracer tracer;
+
+  public MyController(OpenTelemetry openTelemetry) {
+    this.tracer = openTelemetry.getTracer("application");
+  }
+}
+```
+
+Use the `Tracer` to create a span as explained in the
+[Span](/docs/languages/java/api/#span) section.
+
+A full example can be found in the [example repository].
+
+## Meter
+
+```java
+import io.opentelemetry.api.OpenTelemetry;
+import io.opentelemetry.api.metrics.Meter;
+
+@Controller
+public class MyController {
+  private final Meter meter;
+
+  public MyController(OpenTelemetry openTelemetry) {
+    this.meter = openTelemetry.getMeter("application");
+  }
+}
+```
+
+Use the `Meter` to create a counter, gauge or histogram as explained in the
+[Meter](/docs/languages/java/api/#meter) section.
+
+A full example can be found in the [example repository].
+
+[example repository]:
+  https://github.com/open-telemetry/opentelemetry-java-examples/tree/main/spring-native