Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Extending with custom manual instrumentation #5789

Open
wants to merge 10 commits into
base: main
Choose a base branch
from
Open
Show file tree
Hide file tree
Changes from 3 commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
19 changes: 18 additions & 1 deletion content/en/docs/languages/java/api.md
Original file line number Diff line number Diff line change
Expand Up @@ -600,7 +600,7 @@ public class OpenTelemetryUsage {
```
<!-- prettier-ignore-end -->

### GlobalOpenTelemetry
#### GlobalOpenTelemetry
Comment on lines 602 to +603
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm not sure about the organization of the additions in this file

Maybe could just add two small notes right above here, something like "If you are using the Java agent, see X for information about how to obtain an OpenTelemetry instance" (and similar note for Spring Boot starter)

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I agree - I think an alert could be good. Something like

{{% alert title="Spring Boot Starter" %}} 
The Spring Boot starter is a special case where [...].
{{% /alert %}}


[GlobalOpenTelemetry](https://www.javadoc.io/doc/io.opentelemetry/opentelemetry-api/latest/io/opentelemetry/api/GlobalOpenTelemetry.html)
holds a global singleton [OpenTelemetry](#opentelemetry) instance.
Expand Down Expand Up @@ -655,6 +655,23 @@ public class GlobalOpenTelemetryUsage {
```
<!-- prettier-ignore-end -->

#### OpenTelemetry in 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/).

#### OpenTelemetry in 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/).

### TracerProvider

[TracerProvider](https://www.javadoc.io/doc/io.opentelemetry/opentelemetry-api/latest/io/opentelemetry/api/trace/TracerProvider.html)
Expand Down
3 changes: 1 addition & 2 deletions content/en/docs/zero-code/java/agent/annotations.md
Original file line number Diff line number Diff line change
Expand Up @@ -129,6 +129,5 @@ 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
tracer that can be used for [Manual Instrumentation](../api) and execute code
zeitlinger marked this conversation as resolved.
Show resolved Hide resolved
within the scope of that span.
81 changes: 81 additions & 0 deletions content/en/docs/zero-code/java/agent/api.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,81 @@
---
title: Manual instrumentation
zeitlinger marked this conversation as resolved.
Show resolved Hide resolved
description: Extending a Java agent with custom manual instrumentation.
weight: 21
---

## Introduction

In addition to the out-of-the-box instrumentation, you can extend the Java agent
with custom manual instrumentation. 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 [example repository].
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
A full example can be found [example repository].
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 [example repository].
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
A full example can be found [example repository].
A full example can be found in the [example repository].


[example repository]:
https://github.com/open-telemetry/opentelemetry-java-examples/tree/main/javaagent
Original file line number Diff line number Diff line change
Expand Up @@ -120,3 +120,9 @@ 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 for [Manual Instrumentation](../api) and execute code
zeitlinger marked this conversation as resolved.
Show resolved Hide resolved
within the scope of that span.
73 changes: 73 additions & 0 deletions content/en/docs/zero-code/java/spring-boot-starter/api.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,73 @@
---
title: Manual instrumentation
zeitlinger marked this conversation as resolved.
Show resolved Hide resolved
description:
Extending the Spring Boot starter with custom manual instrumentation.
weight: 21
---

## Introduction

In addition to the out-of-the-box instrumentation, you can extend the Spring
starter with custom manual instrumentation. 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 [example repository].
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
A full example can be found [example repository].
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 [example repository].
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
A full example can be found [example repository].
A full example can be found in the [example repository].


[example repository]:
https://github.com/open-telemetry/opentelemetry-java-examples/tree/main/spring-native
Loading