Skip to content

Commit 292967a

Browse files
zeitlingersvrnmtrask
authored
Extending with custom manual instrumentation (#5789)
Co-authored-by: Severin Neumann <[email protected]> Co-authored-by: Trask Stalnaker <[email protected]>
1 parent 672498e commit 292967a

File tree

5 files changed

+181
-3
lines changed

5 files changed

+181
-3
lines changed

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

+16
Original file line numberDiff line numberDiff line change
@@ -560,6 +560,14 @@ public class AttributesUsage {
560560

561561
### OpenTelemetry
562562

563+
{{% alert title="Spring Boot Starter" %}} The Spring Boot starter is a special
564+
case where `OpenTelemetry` is available as a Spring bean. Simply inject
565+
`OpenTelemetry` into your Spring components.
566+
567+
Read more about
568+
[extending the Spring Boot starter with custom manual instrumentation](/docs/zero-code/java/spring-boot-starter/api/).
569+
{{% /alert %}}
570+
563571
[OpenTelemetry](https://www.javadoc.io/doc/io.opentelemetry/opentelemetry-api/latest/io/opentelemetry/api/OpenTelemetry.html)
564572
is a holder for top-level API components which is convenient to pass to
565573
instrumentation.
@@ -602,6 +610,14 @@ public class OpenTelemetryUsage {
602610

603611
### GlobalOpenTelemetry
604612

613+
{{% alert title="Java agent" %}} The Java agent is a special case where
614+
`GlobalOpenTelemetry` is set by the agent. Simply call
615+
`GlobalOpenTelemetry.get()` to access the `OpenTelemetry` instance.
616+
617+
Read more about
618+
[extending the Java agent with custom manual instrumentation](/docs/zero-code/java/agent/api/).
619+
{{% /alert %}}
620+
605621
[GlobalOpenTelemetry](https://www.javadoc.io/doc/io.opentelemetry/opentelemetry-api/latest/io/opentelemetry/api/GlobalOpenTelemetry.html)
606622
holds a global singleton [OpenTelemetry](#opentelemetry) instance.
607623

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

+1-3
Original file line numberDiff line numberDiff line change
@@ -135,6 +135,4 @@ instrumented.
135135
## Next steps
136136

137137
Beyond the use of annotations, the OpenTelemetry API allows you to obtain a
138-
tracer that can be used for
139-
[Manual Instrumentation](/docs/languages/java/instrumentation/) and execute code
140-
within the scope of that span.
138+
tracer that can be used for [custom instrumentation](../api).

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

+84
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,84 @@
1+
---
2+
title: Extending instrumentations with the API
3+
linkTitle: Extend with the API
4+
description:
5+
Use the OpenTelemetry API in combination with the Java agent to extend the
6+
automatically generated telemetry with custom spans and metrics
7+
weight: 21
8+
---
9+
10+
## Introduction
11+
12+
In addition to the out-of-the-box instrumentation, you can extend the Java agent
13+
with custom manual instrumentation using the OpenTelemetry API. This allows you
14+
to create [spans](/docs/concepts/signals/traces/#spans) and
15+
[metrics](/docs/concepts/signals/metrics) for your own code without doing too
16+
many code changes.
17+
18+
## Dependencies
19+
20+
Add a dependency on the `opentelemetry-api` library.
21+
22+
### Maven
23+
24+
```xml
25+
<dependencies>
26+
<dependency>
27+
<groupId>io.opentelemetry</groupId>
28+
<artifactId>opentelemetry-api</artifactId>
29+
<version>{{% param vers.otel %}}</version>
30+
</dependency>
31+
</dependencies>
32+
```
33+
34+
### Gradle
35+
36+
```groovy
37+
dependencies {
38+
implementation('io.opentelemetry:opentelemetry-api:{{% param vers.otel %}}')
39+
}
40+
```
41+
42+
## OpenTelemetry
43+
44+
The Java agent is a special case where `GlobalOpenTelemetry` is set by the
45+
agent. Simply call `GlobalOpenTelemetry.get()` to access the `OpenTelemetry`
46+
instance.
47+
48+
## Span
49+
50+
{{% alert title="Note" color="info" %}}
51+
52+
For the most common use cases, use the `@WithSpan` annotation instead of manual
53+
instrumentation. See [Annotations](../annotations) for more information.
54+
55+
{{% /alert %}}
56+
57+
```java
58+
import io.opentelemetry.api.GlobalOpenTelemetry;
59+
import io.opentelemetry.api.trace.Tracer;
60+
61+
Tracer tracer = GlobalOpenTelemetry.getTracer("application");
62+
```
63+
64+
Use the `Tracer` to create a span as explained in the
65+
[Span](/docs/languages/java/api/#span) section.
66+
67+
A full example can be found in the [example repository].
68+
69+
## Meter
70+
71+
```java
72+
import io.opentelemetry.api.GlobalOpenTelemetry;
73+
import io.opentelemetry.api.metrics.Meter;
74+
75+
Meter meter = GlobalOpenTelemetry.getMeter("application");
76+
```
77+
78+
Use the `Meter` to create a counter, gauge or histogram as explained in the
79+
[Meter](/docs/languages/java/api/#meter) section.
80+
81+
A full example can be found in the [example repository].
82+
83+
[example repository]:
84+
https://github.com/open-telemetry/opentelemetry-java-examples/tree/main/javaagent

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

+5
Original file line numberDiff line numberDiff line change
@@ -120,3 +120,8 @@ annotation:
120120
| Name | Type | Description | Default Value |
121121
| ------- | -------- | -------------- | --------------------- |
122122
| `value` | `String` | Attribute name | Method parameter name |
123+
124+
## Next steps
125+
126+
Beyond the use of annotations, the OpenTelemetry API allows you to obtain a
127+
tracer that can be used [custom instrumentation](../api).

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

+75
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,75 @@
1+
---
2+
title: Extending instrumentations with the API
3+
linkTitle: Extend with the API
4+
description:
5+
Use the OpenTelemetry API in combination with the Spring Boot starter to
6+
extend the automatically generated telemetry with custom spans and metrics
7+
weight: 21
8+
---
9+
10+
## Introduction
11+
12+
In addition to the out-of-the-box instrumentation, you can extend the Spring
13+
starter with custom manual instrumentation using the OpenTelemetry API. This
14+
allows you to create [spans](/docs/concepts/signals/traces/#spans) and
15+
[metrics](/docs/concepts/signals/metrics) for your own code without doing too
16+
many code changes.
17+
18+
The required dependencies are already included in the Spring Boot starter.
19+
20+
## OpenTelemetry
21+
22+
The Spring Boot starter is a special case where `OpenTelemetry` is available as
23+
a Spring bean. Simply inject `OpenTelemetry` into your Spring components.
24+
25+
## Span
26+
27+
{{% alert title="Note" color="info" %}}
28+
29+
For the most common use cases, use the `@WithSpan` annotation instead of manual
30+
instrumentation. See [Annotations](../annotations) for more information.
31+
32+
{{% /alert %}}
33+
34+
```java
35+
import io.opentelemetry.api.OpenTelemetry;
36+
import io.opentelemetry.api.trace.Tracer;
37+
38+
@Controller
39+
public class MyController {
40+
private final Tracer tracer;
41+
42+
public MyController(OpenTelemetry openTelemetry) {
43+
this.tracer = openTelemetry.getTracer("application");
44+
}
45+
}
46+
```
47+
48+
Use the `Tracer` to create a span as explained in the
49+
[Span](/docs/languages/java/api/#span) section.
50+
51+
A full example can be found in the [example repository].
52+
53+
## Meter
54+
55+
```java
56+
import io.opentelemetry.api.OpenTelemetry;
57+
import io.opentelemetry.api.metrics.Meter;
58+
59+
@Controller
60+
public class MyController {
61+
private final Meter meter;
62+
63+
public MyController(OpenTelemetry openTelemetry) {
64+
this.meter = openTelemetry.getMeter("application");
65+
}
66+
}
67+
```
68+
69+
Use the `Meter` to create a counter, gauge or histogram as explained in the
70+
[Meter](/docs/languages/java/api/#meter) section.
71+
72+
A full example can be found in the [example repository].
73+
74+
[example repository]:
75+
https://github.com/open-telemetry/opentelemetry-java-examples/tree/main/spring-native

0 commit comments

Comments
 (0)