Skip to content

Commit

Permalink
Link up language-agnostic concepts in java docs + format (#1547)
Browse files Browse the repository at this point in the history
  • Loading branch information
@cartermp
cartermp authored Jul 22, 2022
1 parent ccfa0ec commit 05e3289
Show file tree
Hide file tree
Showing 2 changed files with 119 additions and 83 deletions.
46 changes: 25 additions & 21 deletions content/en/docs/instrumentation/java/automatic/annotations.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -6,8 +6,9 @@ weight: 4
---

For most users, the out-of-the-box instrumentation is completely sufficient and
nothing more has to be done. Sometimes, however, users wish to create spans
for their own custom code without doing too much code change.
nothing more has to be done. Sometimes, however, users wish to create
[spans](/docs/concepts/signals/traces/#spans-in-opentelemetry) for their own
custom code without doing too much code change.

## Dependencies

Expand Down Expand Up @@ -36,8 +37,8 @@ dependencies {

## Creating spans around methods with `@WithSpan`

To create a span corresponding to one of your method, annotate the method
with `@WithSpan`.
To create a [span](/docs/concepts/signals/traces/#spans-in-opentelemetry)
corresponding to one of your method, annotate the method with `@WithSpan`.

```java
import io.opentelemetry.extension.annotations.WithSpan;
Expand All @@ -55,9 +56,9 @@ denotes its duration and provides any thrown exceptions. By default, the span
name will be `<className>.<methodName>`, unless a name is provided as an
argument to the annotation.

If the return type of the method annotated by `@WithSpan` is one of the
[future- or promise-like](https://en.wikipedia.org/wiki/Futures_and_promises)
types listed below, then the span will not be ended until the future completes.
If the return type of the method annotated by `@WithSpan` is one of the [future-
or promise-like](https://en.wikipedia.org/wiki/Futures_and_promises) types
listed below, then the span will not be ended until the future completes.

* [java.util.concurrent.CompletableFuture](https://docs.oracle.com/javase/8/docs/api/java/util/concurrent/CompletableFuture.html)
* [java.util.concurrent.CompletionStage](https://docs.oracle.com/javase/8/docs/api/java/util/concurrent/CompletionStage.html)
Expand All @@ -74,9 +75,11 @@ types listed below, then the span will not be ended until the future completes.

## Adding attributes to the span with `@SpanAttribute`

When a span is created for an annotated method the values of the arguments to
the method invocation can be automatically added as attributes to the created
span by annotating the method parameters with the `@SpanAttribute` annotation.
When a [span](/docs/concepts/signals/traces/#spans-in-opentelemetry) is created
for an annotated method the values of the arguments to the method invocation can
be automatically added as
[attributes](/docs/concepts/signals/traces/#attributes) to the created span by
annotating the method parameters with the `@SpanAttribute` annotation.

```java
import io.opentelemetry.extension.annotations.SpanAttribute;
Expand All @@ -102,23 +105,24 @@ Suppressing `@WithSpan` is useful if you have code that is over-instrumented
using `@WithSpan` and you want to suppress some of them without modifying the
code.

{{% config_option name="otel.instrumentation.opentelemetry-annotations.exclude-methods" %}}
Suppress `@WithSpan` instrumentation for specific methods.
Format is `my.package.MyClass1[method1,method2];my.package.MyClass2[method3]`.
{{% /config_option %}}
{{% config_option
name="otel.instrumentation.opentelemetry-annotations.exclude-methods" %}}
Suppress `@WithSpan` instrumentation for specific methods. Format is
`my.package.MyClass1[method1,method2];my.package.MyClass2[method3]`. {{%
/config_option %}}

## Creating spans around methods with `otel.instrumentation.methods.include`

In cases where you are unable to modify the code, you can still configure the
javaagent to capture spans around specific methods.

{{% config_option name="otel.instrumentation.methods.include" %}}
Add instrumentation for specific methods in lieu of `@WithSpan`.
Format is `my.package.MyClass1[method1,method2];my.package.MyClass2[method3]`.
{{% /config_option %}}
{{% config_option name="otel.instrumentation.methods.include" %}} Add
instrumentation for specific methods in lieu of `@WithSpan`. Format is
`my.package.MyClass1[method1,method2];my.package.MyClass2[method3]`. {{%
/config_option %}}

## Next steps

Beyond the use of annotations, the OpenTelemetry API allows you to obtain
a tracer that can be used for [Manual Instrumentation](../../manual)
and execute code within the scope of that span.
Beyond the use of annotations, the OpenTelemetry API allows you to obtain a
tracer that can be used for [Manual Instrumentation](../../manual) and execute
code within the scope of that span.
156 changes: 94 additions & 62 deletions content/en/docs/instrumentation/java/manual.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -50,9 +50,10 @@ reason, you can fall back to using an instance from the `GlobalOpenTelemetry`
class. Note that you can't force end-users to configure the global, so this is
the most brittle option for library instrumentation.

## Tracing
## Acquiring a Tracer

In the following, we present how to trace code using the OpenTelemetry API.
To do [Tracing](/docs/concepts/signals/traces/#tracing-in-opentelemetry) you'll
need to aquire a [`Tracer`](/docs/concepts/signals/traces/#tracer).

**Note:** Methods of the OpenTelemetry SDK should never be called.

Expand All @@ -64,6 +65,10 @@ application to be monitored. More information is available in the specification
chapter [Obtaining a Tracer].

```java
import io.opentelemetry.api;

//...

Tracer tracer =
openTelemetry.getTracer("instrumentation-library-name", "1.0.0");
```
Expand All @@ -72,27 +77,32 @@ Important: the "name" and optional version of the tracer are purely
informational. All `Tracer`s that are created by a single `OpenTelemetry`
instance will interoperate, regardless of name.

### Create a basic Span
### Create Spans

To create a basic span, you only need to specify the name of the span. The start
and end time of the span is automatically set by the OpenTelemetry SDK.
To create [Spans](/docs/concepts/signals/traces/#spans-in-opentelemetry), you
only need to specify the name of the span. The start and end time of the span is
automatically set by the OpenTelemetry SDK.

```java
Span span = tracer.spanBuilder("my span").startSpan();
// put the span into the current Context
try {
// do something...

// Make the span the current span
try (Scope ss = span.makeCurrent()) {
// In this scope, the span is the current/active span
} finally {
span.end();
}
```

It's required to call `end()` to end the span when you want it to end.

### Create nested Spans

Most of the time, we want to correlate spans for nested operations.
OpenTelemetry supports tracing within processes and across remote processes. For
more details how to share context between remote processes, see [Context
Propagation](#context-propagation).
Most of the time, we want to correlate
[spans](/docs/concepts/signals/traces/#spans-in-opentelemetry) for nested
operations. OpenTelemetry supports tracing within processes and across remote
processes. For more details how to share context between remote processes, see
[Context Propagation](#context-propagation).

For a method `a` calling a method `b`, the spans could be manually linked in the
following way:
Expand Down Expand Up @@ -153,8 +163,9 @@ Span childRemoteParent = tracer.spanBuilder("Child").setParent(remoteContext).st

### Get the current span

Sometimes it's helpful to do something with the current/active span at a
particular point in program execution.
Sometimes it's helpful to do something with the current/active
[span](/docs/concepts/signals/traces/#spans-in-opentelemetry) at a particular
point in program execution.

```java
Span span = Span.current()
Expand All @@ -168,10 +179,12 @@ Span span = Span.fromContext(context)

### Span Attributes

In OpenTelemetry spans can be created freely and it's up to the implementor to
annotate them with attributes specific to the represented operation. Attributes
provide additional context on a span about the specific operation it tracks,
such as results or operation properties.
In OpenTelemetry [spans](/docs/concepts/signals/traces/#spans-in-opentelemetry)
can be created freely and it's up to the implementor to annotate them with
attributes specific to the represented operation.
[Attributes](/docs/concepts/signals/traces/#attributes) provide additional
context on a span about the specific operation it tracks, such as results or
operation properties.

```java
Span span = tracer.spanBuilder("/resource/path").setSpanKind(SpanKind.CLIENT).startSpan();
Expand All @@ -187,9 +200,11 @@ cross-language specification.

### Create Spans with events

Spans can be annotated with named events that can carry zero or more [Span
Attributes](#span-attributes), each of which is itself a key:value map paired
automatically with a timestamp.
[Spans](/docs/concepts/signals/traces/#spans-in-opentelemetry) can be annotated
with named events (called [Span
Events](/docs/concepts/signals/traces/#span-events)) that can carry zero or more
[Span Attributes](#span-attributes), each of which is itself a key:value map
paired automatically with a timestamp.

```java
span.addEvent("Init");
Expand All @@ -207,10 +222,11 @@ span.addEvent("End Computation", eventAttributes);

### Create Spans with links

A Span may be linked to zero or more other Spans that are causally related.
Links can be used to represent batched operations where a Span was initiated by
multiple initiating Spans, each representing a single incoming item being
processed in the batch.
A [Span](/docs/concepts/signals/traces/#spans-in-opentelemetry) may be linked to
zero or more other Spans that are causally related via a [Span
Link](/docs/concepts/signals/traces/#span-links). Links can be used to represent
batched operations where a Span was initiated by multiple initiating Spans, each
representing a single incoming item being processed in the batch.

```java
Span child = tracer.spanBuilder("childWithLink")
Expand All @@ -226,10 +242,11 @@ Propagation](#context-propagation).

### Set span status

A status can be set on a span, typically used to specify that a span
has not completed successfully - `SpanStatus.Error`.
In rare scenarios, you could override the `Error` status with `OK`,
but don't set `OK` on successfully-completed spans.
A [status](/docs/concepts/signals/traces/#span-status) can be set on a
[span](/docs/concepts/signals/traces/#spans-in-opentelemetry), typically used to
specify that a span has not completed successfully - `SpanStatus.Error`. In rare
scenarios, you could override the `Error` status with `OK`, but don't set `OK`
on successfully-completed spans.

The status can be set at any time before the span is finished:

Expand All @@ -248,9 +265,8 @@ try (Scope scope = span.makeCurrent()) {

### Record exceptions in spans

It can be a good idea to record exceptions when they happen.
It's recommended to do this in conjunction with setting
[span status](#set-span-status).
It can be a good idea to record exceptions when they happen. It's recommended to
do this in conjunction with setting [span status](#set-span-status).

```java
Span span = tracer.spanBuilder("my span").startSpan();
Expand Down Expand Up @@ -348,7 +364,11 @@ public void handle(HttpExchange httpExchange) {
}
}
```
The following code presents an example to read the W3C Trace Context from incoming request, add spans, and further propagate the context. The example utilizes [HttpHeaders](https://docs.oracle.com/en/java/javase/11/docs/api/java.net.http/java/net/http/HttpHeaders.html) to fetch the traceparent header for context propagation.
The following code presents an example to read the W3C Trace Context from
incoming request, add spans, and further propagate the context. The example
utilizes
[HttpHeaders](https://docs.oracle.com/en/java/javase/11/docs/api/java.net.http/java/net/http/HttpHeaders.html)
to fetch the traceparent header for context propagation.
```java
TextMapGetter<HttpHeaders> getter =
new TextMapGetter<HttpHeaders>() {
Expand Down Expand Up @@ -407,12 +427,13 @@ public void handle(<Library Specific Annotation> HttpHeaders headers){

## Metrics

Spans provide detailed information about your application, but produce data that
is proportional to the load on the system. In contrast, metrics combine
individual measurements into aggregations, and produce data which is constant as
a function of system load. The aggregations lack details required to diagnose
low level issues, but complement spans by helping to identify trends and
providing application runtime telemetry.
[Spans](/docs/concepts/signals/traces/#spans-in-opentelemetry) provide detailed
information about your application, but produce data that is proportional to the
load on the system. In contrast, [metrics](/docs/concepts/signals/metrics)
combine individual measurements into aggregations, and produce data which is
constant as a function of system load. The aggregations lack details required to
diagnose low level issues, but complement spans by helping to identify trends
and providing application runtime telemetry.

The metrics API defines a variety of instruments. Instruments record
measurements, which are aggregated by the metrics SDK and eventually exported
Expand Down Expand Up @@ -514,9 +535,12 @@ traces can be sampled.

The OpenTelemetry SDK offers four samplers out of the box:

- [AlwaysOnSampler] which samples every trace regardless of upstream sampling decisions.
- [AlwaysOffSampler] which doesn't sample any trace, regardless of upstream sampling decisions.
- [ParentBased] which uses the parent span to make sampling decisions, if present.
- [AlwaysOnSampler] which samples every trace regardless of upstream sampling
decisions.
- [AlwaysOffSampler] which doesn't sample any trace, regardless of upstream
sampling decisions.
- [ParentBased] which uses the parent span to make sampling decisions, if
present.
- [TraceIdRatioBased] which samples a configurable percentage of traces, and
additionally samples any trace that was sampled upstream.

Expand Down Expand Up @@ -557,15 +581,15 @@ exporters out of the box:
- `InMemorySpanExporter`: keeps the data in memory, useful for testing and
debugging.
- Jaeger Exporter: prepares and sends the collected telemetry data to a Jaeger
backend via gRPC. Varieties include `JaegerGrpcSpanExporter`
and `JaegerThriftSpanExporter`.
backend via gRPC. Varieties include `JaegerGrpcSpanExporter` and
`JaegerThriftSpanExporter`.
- `ZipkinSpanExporter`: prepares and sends the collected telemetry data to a
Zipkin backend via the Zipkin APIs.
- Logging Exporter: saves the telemetry data into log streams. Varieties
include `LoggingSpanExporter` and `OtlpJsonLoggingSpanExporter`.
- OpenTelemetry Protocol Exporter: sends the data in OTLP to
the [OpenTelemetry Collector] or other OTLP receivers. Varieties
include `OtlpGrpcSpanExporter` and `OtlpHttpSpanExporter`.
- Logging Exporter: saves the telemetry data into log streams. Varieties include
`LoggingSpanExporter` and `OtlpJsonLoggingSpanExporter`.
- OpenTelemetry Protocol Exporter: sends the data in OTLP to the [OpenTelemetry
Collector] or other OTLP receivers. Varieties include `OtlpGrpcSpanExporter`
and `OtlpHttpSpanExporter`.

Other exporters can be found in the [OpenTelemetry Registry].

Expand Down Expand Up @@ -627,11 +651,11 @@ OpenTelemetry provides the following exporters out of the box:

- `InMemoryMetricExporter`: keeps the data in memory, useful for testing and
debugging.
- Logging Exporter: saves the telemetry data into log streams. Varieties
include `LoggingMetricExporter` and `OtlpJsonLoggingMetricExporter`.
- OpenTelemetry Protocol Exporter: sends the data in OTLP to
the [OpenTelemetry Collector] or other OTLP receivers. Varieties
include `OtlpGrpcMetricExporter` and `OtlpHttpMetricExporter`.
- Logging Exporter: saves the telemetry data into log streams. Varieties include
`LoggingMetricExporter` and `OtlpJsonLoggingMetricExporter`.
- OpenTelemetry Protocol Exporter: sends the data in OTLP to the [OpenTelemetry
Collector] or other OTLP receivers. Varieties include `OtlpGrpcMetricExporter`
and `OtlpHttpMetricExporter`.

Other exporters can be found in the [OpenTelemetry Registry].

Expand Down Expand Up @@ -735,15 +759,23 @@ public class IgnoreExportErrorsFilter implements Filter {
io.opentelemetry.sdk.trace.export.BatchSpanProcessor = io.opentelemetry.extension.logging.IgnoreExportErrorsFilter
```

[AlwaysOffSampler]: https://github.com/open-telemetry/opentelemetry-java/blob/main/sdk/trace/src/main/java/io/opentelemetry/sdk/trace/samplers/AlwaysOffSampler.java
[AlwaysOnSampler]: https://github.com/open-telemetry/opentelemetry-java/blob/main/sdk/trace/src/main/java/io/opentelemetry/sdk/trace/samplers/AlwaysOnSampler.java
[HttpExchange]: https://docs.oracle.com/javase/8/docs/jre/api/net/httpserver/spec/com/sun/net/httpserver/HttpExchange.html
[Instrumentation Library]: /docs/reference/specification/glossary/#instrumentation-library
[instrumented library]: /docs/reference/specification/glossary/#instrumented-library
[AlwaysOffSampler]:
https://github.com/open-telemetry/opentelemetry-java/blob/main/sdk/trace/src/main/java/io/opentelemetry/sdk/trace/samplers/AlwaysOffSampler.java
[AlwaysOnSampler]:
https://github.com/open-telemetry/opentelemetry-java/blob/main/sdk/trace/src/main/java/io/opentelemetry/sdk/trace/samplers/AlwaysOnSampler.java
[HttpExchange]:
https://docs.oracle.com/javase/8/docs/jre/api/net/httpserver/spec/com/sun/net/httpserver/HttpExchange.html
[Instrumentation Library]:
/docs/reference/specification/glossary/#instrumentation-library
[instrumented library]:
/docs/reference/specification/glossary/#instrumented-library
[Library Guidelines]: /docs/reference/specification/library-guidelines
[Obtaining a Tracer]: /docs/reference/specification/trace/api/#get-a-tracer
[OpenTelemetry Collector]: https://github.com/open-telemetry/opentelemetry-collector
[OpenTelemetry Collector]:
https://github.com/open-telemetry/opentelemetry-collector
[OpenTelemetry Registry]: /registry/?component=exporter&language=java
[ParentBased]: https://github.com/open-telemetry/opentelemetry-java/blob/main/sdk/trace/src/main/java/io/opentelemetry/sdk/trace/samplers/ParentBasedSampler.java
[ParentBased]:
https://github.com/open-telemetry/opentelemetry-java/blob/main/sdk/trace/src/main/java/io/opentelemetry/sdk/trace/samplers/ParentBasedSampler.java
[Semantic Conventions]: /docs/reference/specification/trace/semantic_conventions
[TraceIdRatioBased]: https://github.com/open-telemetry/opentelemetry-java/blob/main/sdk/trace/src/main/java/io/opentelemetry/sdk/trace/samplers/TraceIdRatioBasedSampler.java
[TraceIdRatioBased]:
https://github.com/open-telemetry/opentelemetry-java/blob/main/sdk/trace/src/main/java/io/opentelemetry/sdk/trace/samplers/TraceIdRatioBasedSampler.java

0 comments on commit 05e3289

Please sign in to comment.