open-telemetry
/
opentelemetry.io
mirror of https://github.com/open-telemetry/opentelemetry.io.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Enable Prettier check over instrumentation/java (#2363)

This commit is contained in:
Patrice Chalin 2023-02-20 10:32:13 -05:00 committed by GitHub
parent 8120fdb4a6
commit 1ff41b1ac3
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
8 changed files with 315 additions and 264 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

1
.prettierignore
View File

@ -23,7 +23,6 @@ package-lock.json
content/en/docs/instrumentation/cpp
content/en/docs/instrumentation/erlang
content/en/docs/instrumentation/go
content/en/docs/instrumentation/java
content/en/docs/instrumentation/js
content/en/docs/instrumentation/net
content/en/docs/instrumentation/other

6
content/en/docs/instrumentation/java/_index.md
View File

@ -3,8 +3,7 @@ title: Java
description: >-
<img width="35" class="img-initial"
src="https://raw.githubusercontent.com/open-telemetry/opentelemetry.io/main/iconography/32x32/Java_SDK.svg"
alt="Java"></img>
A language-specific implementation of OpenTelemetry in Java.
alt="Java"></img> A language-specific implementation of OpenTelemetry in Java.
aliases: [/java, /java/metrics, /java/tracing]
weight: 18
cascade:
@ -73,6 +72,7 @@ dependencies {
```
[maven central]: https://mvnrepository.com/artifact/io.opentelemetry
[opentelemetry-java-docs]: https://github.com/open-telemetry/opentelemetry-java-docs#java-opentelemetry-examples
[opentelemetry-java-docs]:
https://github.com/open-telemetry/opentelemetry-java-docs#java-opentelemetry-examples
[releases]: https://github.com/open-telemetry/opentelemetry-java/releases
[components]: https://github.com/open-telemetry/opentelemetry-java#releases

46
content/en/docs/instrumentation/java/automatic/_index.md
View File

@ -17,20 +17,21 @@ service or app code, see [Manual instrumentation](../manual).
## Setup
1. Download [opentelemetry-javaagent.jar][] from [Releases][] of the
`opentelemetry-java-instrumentation` repo and place the JAR in your preferred directory.
The JAR file contains the agent and instrumentation libraries.
2. Add `-javaagent:path/to/opentelemetry-javaagent.jar` and other config
to your JVM's startup arguments and launch your app:
1. Download [opentelemetry-javaagent.jar][] from [Releases][] of the
`opentelemetry-java-instrumentation` repo and place the JAR in your
preferred directory. The JAR file contains the agent and instrumentation
libraries.
2. Add `-javaagent:path/to/opentelemetry-javaagent.jar` and other config to
your JVM's startup arguments and launch your app:
- Directly on the startup command:
```console
$ java -javaagent:path/to/opentelemetry-javaagent.jar -Dotel.service.name=your-service-name -jar myapp.jar
```shell
java -javaagent:path/to/opentelemetry-javaagent.jar -Dotel.service.name=your-service-name -jar myapp.jar
```
- Via the `JAVA_TOOL_OPTIONS` and other environment variables:
```console
$ export JAVA_TOOL_OPTIONS="-javaagent:path/to/opentelemetry-javaagent.jar"
$ export OTEL_SERVICE_NAME="your-service-name"
$ java -jar myapp.jar
```shell
export JAVA_TOOL_OPTIONS="-javaagent:path/to/opentelemetry-javaagent.jar"
export OTEL_SERVICE_NAME="your-service-name"
java -jar myapp.jar
```
## Configuring the agent
@ -56,7 +57,8 @@ java -javaagent:path/to/opentelemetry-javaagent.jar \
-jar myapp.jar
```
You can also supply a Java properties file and load configuration values from there:
You can also supply a Java properties file and load configuration values from
there:
```sh
java -javaagent:path/to/opentelemetry-javaagent.jar \
@ -76,8 +78,9 @@ To see the full range of configuration options, see [Agent Configuration][].
## Supported libraries, frameworks, application services, and JVMs
The Java agent ships with instrumentation libraries for many popular components.
For the full list, see [Supported libraries, frameworks, application services, and JVMs][support].
The Java agent ships with instrumentation libraries for many popular components.
For the full list, see [Supported libraries, frameworks, application services,
and JVMs][support].
## Troubleshooting
@ -87,10 +90,13 @@ debug logs. Note that these are quite verbose.
## Next steps
After you have automatic instrumentation configured for your app or service, you
might want to [annotate](annotations) selected methods or add [manual
instrumentation](../manual) to collect custom telemetry data.
might want to [annotate](annotations) selected methods or add
[manual instrumentation](../manual) to collect custom telemetry data.
[Agent Configuration]: agent-config
[opentelemetry-javaagent.jar]: https://github.com/open-telemetry/opentelemetry-java-instrumentation/releases/latest/download/opentelemetry-javaagent.jar
[releases]: https://github.com/open-telemetry/opentelemetry-java-instrumentation/releases
[support]: https://github.com/open-telemetry/opentelemetry-java-instrumentation/blob/main/docs/supported-libraries.md
[agent configuration]: agent-config
[opentelemetry-javaagent.jar]:
https://github.com/open-telemetry/opentelemetry-java-instrumentation/releases/latest/download/opentelemetry-javaagent.jar
[releases]:
https://github.com/open-telemetry/opentelemetry-java-instrumentation/releases
[support]:
https://github.com/open-telemetry/opentelemetry-java-instrumentation/blob/main/docs/supported-libraries.md

294
content/en/docs/instrumentation/java/automatic/agent-config.md
View File

@ -3,7 +3,7 @@ title: Agent Configuration
linkTitle: Configuration
weight: 2
spelling:
cSpell:ignore autoconfiguration Autoconfiguration Dotel HSET javaagent
cSpell:ignore akka autoconfiguration Autoconfiguration Dotel HSET javaagent
cSpell:ignore serverlessapis Servlet servlet
---
@ -45,15 +45,16 @@ The agent can consume configuration from one or more of the following sources
## Configuring with Environment Variables
In some environments, configuring via Environment Variables is more preferred.
Any setting configurable with a System Property can also be configured with an Environment Variable.
Many settings below include both options, but where they don't apply the following steps
to determine the correct name mapping of the desired System Property:
Any setting configurable with a System Property can also be configured with an
Environment Variable. Many settings below include both options, but where they
don't apply the following steps to determine the correct name mapping of the
desired System Property:
- Convert the System Property to uppercase.
- Replace all `.` and `-` characters with `_`.
For example `otel.instrumentation.common.default-enabled`
would convert to `OTEL_INSTRUMENTATION_COMMON_DEFAULT_ENABLED`.
For example `otel.instrumentation.common.default-enabled` would convert to
`OTEL_INSTRUMENTATION_COMMON_DEFAULT_ENABLED`.
### Configuration file
@ -68,9 +69,12 @@ Java properties file which contains the agent configuration.
You can enable [extensions][] by setting the following property:
{{% config_option name="otel.javaagent.extensions" %}} Path to an extension jar
file or folder, containing jar files. If pointing to a folder, every jar file in
that folder will be treated as separate, independent extension.
{{% config_option name="otel.javaagent.extensions" %}}
Path to an extension jar file or folder, containing jar files. If pointing to a
folder, every jar file in that folder will be treated as separate, independent
extension.
{{% /config_option %}}
## Common instrumentation configuration
@ -87,6 +91,7 @@ is the name of a remote service to which a connection is made. It corresponds to
for the local service.
{{% config_option name="otel.instrumentation.common.peer-service-mapping" %}}
Used to specify a mapping from host names or IP addresses to peer services, as a
comma-separated list of `<host_or_ip>=<user_assigned_name>` pairs. The peer
service is added as an attribute to a span whose host or IP address match the
@ -98,7 +103,9 @@ For example, if set to the following:
Then, requests to `1.2.3.4` will have a `peer.service` attribute of
`cats-service` and requests to `dogs-abcdef123.serverlessapis.com` will have an
attribute of `dogs-api`. {{% /config_option %}}
attribute of `dogs-api`.
{{% /config_option %}}
### DB statement sanitization
@ -132,14 +139,17 @@ Use the following properties to define which HTTP headers you want to capture:
A comma-separated list of HTTP header names. HTTP client instrumentations will
capture HTTP request header values for all configured header names.
{{% /config_option %}}
{{% config_option name="otel.instrumentation.http.capture-headers.client.response" %}}
A comma-separated list of HTTP header names. HTTP client instrumentations will
capture HTTP response header values for all configured header names.
{{% /config_option %}}
{{% config_option name="otel.instrumentation.http.capture-headers.server.request" %}}
A comma-separated list of HTTP header names. HTTP server instrumentations will
capture HTTP request header values for all configured header names.
{{% /config_option %}}
{{% config_option name="otel.instrumentation.http.capture-headers.server.response" %}}
A comma-separated list of HTTP header names. HTTP server instrumentations will
capture HTTP response header values for all configured header names.
@ -188,18 +198,22 @@ equivalent environment variable `OTEL_JAVAAGENT_ENABLED=false`).
### Enable only specific instrumentation
You can disable all default auto instrumentation and selectively re-enable individual instrumentation.
This may be desireable to reduce startup overhead or to have more control of which instrumentation is applied.
You can disable all default auto instrumentation and selectively re-enable
individual instrumentation. This may be desireable to reduce startup overhead or
to have more control of which instrumentation is applied.
- Disable all instrumentation in the agent using `-Dotel.instrumentation.common.default-enabled=false`
(or using the equivalent environment variable `OTEL_INSTRUMENTATION_COMMON_DEFAULT_ENABLED=false`).
- Enable each desired instrumentation individually using `-Dotel.instrumentation.[name].enabled=true`
(or using the equivalent environment variable `OTEL_INSTRUMENTATION_[NAME]_ENABLED`) where `[name]`
(`[NAME]`) is the corresponding instrumentation `name` below.
- Disable all instrumentation in the agent using
`-Dotel.instrumentation.common.default-enabled=false` (or using the equivalent
environment variable `OTEL_INSTRUMENTATION_COMMON_DEFAULT_ENABLED=false`).
- Enable each desired instrumentation individually using
`-Dotel.instrumentation.[name].enabled=true` (or using the equivalent
environment variable `OTEL_INSTRUMENTATION_[NAME]_ENABLED`) where `[name]`
(`[NAME]`) is the corresponding instrumentation `name` below.
> **Note**: Some instrumentation relies on other instrumentation to function properly. When selectively
enabling instrumentation, be sure to enable the transitive dependencies too. Determining this dependency
relationship is left as an exercise to the user.
> **Note**: Some instrumentation relies on other instrumentation to function
> properly. When selectively enabling instrumentation, be sure to enable the
> transitive dependencies too. Determining this dependency relationship is left
> as an exercise to the user.
### Enable manual instrumentation only
@ -214,125 +228,125 @@ You can suppress agent instrumentation of specific libraries by using
environment variable `OTEL_INSTRUMENTATION_[NAME]_ENABLED`) where `name`
(`NAME`) is the corresponding instrumentation `name`:
| Library/Framework | Instrumentation name |
| ------------------------------------------------ | ------------------------- |
| Additional methods tracing | methods |
| Additional tracing annotations | external-annotations |
| Akka Actor | akka-actor |
| Akka HTTP | akka-http |
| Apache Axis2 | axis2 |
| Apache Camel | apache-camel |
| Apache Cassandra | cassandra |
| Apache CXF | cxf |
| Apache DBCP | apache-dbcp |
| Apache Dubbo | apache-dubbo |
| Apache Geode | geode |
| Apache HttpAsyncClient | apache-httpasyncclient |
| Apache HttpClient | apache-httpclient |
| Apache Kafka | kafka |
| Apache MyFaces | myfaces |
| Apache RocketMQ | rocketmq-client |
| Apache Struts 2 | struts |
| Apache Tapestry | tapestry |
| Apache Tomcat | tomcat |
| Apache Wicket | wicket |
| Armeria | armeria |
| AsyncHttpClient (AHC) | async-http-client |
| AWS Lambda | aws-lambda |
| AWS SDK | aws-sdk |
| Azure SDK | azure-core |
| Couchbase | couchbase |
| C3P0 | c3p0 |
| Dropwizard Views | dropwizard-views |
| Dropwizard Metrics | dropwizard-metrics |
| Eclipse Grizzly | grizzly |
| Eclipse Jersey | jersey |
| Eclipse Jetty | jetty |
| Eclipse Jetty HTTP Client | jetty-httpclient |
| Eclipse Metro | metro |
| Eclipse Mojarra | mojarra |
| Eclipse Vert.x HttpClient | vertx-http-client |
| Eclipse Vert.x Kafka Client | vertx-kafka-client |
| Eclipse Vert.x RxJava | vertx-rx-java |
| Eclipse Vert.x Web | vertx-web |
| Elasticsearch client | elasticsearch-transport |
| Elasticsearch REST client | elasticsearch-rest |
| Google Guava | guava |
| Google HTTP client | google-http-client |
| Google Web Toolkit | gwt |
| Grails | grails |
| GraphQL Java | graphql-java |
| GRPC | grpc |
| Hibernate | hibernate |
| HikariCP | hikaricp |
| Java HTTP Client | java-http-client |
| Java `HttpURLConnection` | http-url-connection |
| Java JDBC | jdbc |
| Java JDBC `DataSource` | jdbc-datasource |
| Java RMI | rmi |
| Java Servlet | servlet |
| java.util.concurrent | executor |
| java.util.logging | java-util-logging |
| JAX-RS (Client) | jaxrs-client |
| JAX-RS (Server) | jaxrs |
| JAX-WS | jaxws |
| JBoss Logging Appender | jboss-logmanager-appender |
| JBoss Logging MDC | jboss-logmanager-mdc |
| JMS | jms |
| JSP | jsp |
| K8s Client | kubernetes-client |
| kotlinx.coroutines | kotlinx-coroutines |
| Log4j Appender | log4j-appender |
| Log4j MDC (1.x) | log4j-mdc |
| Log4j Context Data (2.x) | log4j-context-data |
| Logback Appender | logback-appender |
| Logback MDC | logback-mdc |
| Micrometer | micrometer |
| MongoDB | mongo |
| Netflix Hystrix | hystrix |
| Netty | netty |
| OkHttp | okhttp |
| OpenLiberty | liberty |
| OpenTelemetry Extension Annotations | opentelemetry-extension-annotations |
| Library/Framework | Instrumentation name |
| ------------------------------------------------ | ----------------------------------------- |
| Additional methods tracing | methods |
| Additional tracing annotations | external-annotations |
| Akka Actor | akka-actor |
| Akka HTTP | akka-http |
| Apache Axis2 | axis2 |
| Apache Camel | apache-camel |
| Apache Cassandra | cassandra |
| Apache CXF | cxf |
| Apache DBCP | apache-dbcp |
| Apache Dubbo | apache-dubbo |
| Apache Geode | geode |
| Apache HttpAsyncClient | apache-httpasyncclient |
| Apache HttpClient | apache-httpclient |
| Apache Kafka | kafka |
| Apache MyFaces | myfaces |
| Apache RocketMQ | rocketmq-client |
| Apache Struts 2 | struts |
| Apache Tapestry | tapestry |
| Apache Tomcat | tomcat |
| Apache Wicket | wicket |
| Armeria | armeria |
| AsyncHttpClient (AHC) | async-http-client |
| AWS Lambda | aws-lambda |
| AWS SDK | aws-sdk |
| Azure SDK | azure-core |
| Couchbase | couchbase |
| C3P0 | c3p0 |
| Dropwizard Views | dropwizard-views |
| Dropwizard Metrics | dropwizard-metrics |
| Eclipse Grizzly | grizzly |
| Eclipse Jersey | jersey |
| Eclipse Jetty | jetty |
| Eclipse Jetty HTTP Client | jetty-httpclient |
| Eclipse Metro | metro |
| Eclipse Mojarra | mojarra |
| Eclipse Vert.x HttpClient | vertx-http-client |
| Eclipse Vert.x Kafka Client | vertx-kafka-client |
| Eclipse Vert.x RxJava | vertx-rx-java |
| Eclipse Vert.x Web | vertx-web |
| Elasticsearch client | elasticsearch-transport |
| Elasticsearch REST client | elasticsearch-rest |
| Google Guava | guava |
| Google HTTP client | google-http-client |
| Google Web Toolkit | gwt |
| Grails | grails |
| GraphQL Java | graphql-java |
| GRPC | grpc |
| Hibernate | hibernate |
| HikariCP | hikaricp |
| Java HTTP Client | java-http-client |
| Java `HttpURLConnection` | http-url-connection |
| Java JDBC | jdbc |
| Java JDBC `DataSource` | jdbc-datasource |
| Java RMI | rmi |
| Java Servlet | servlet |
| java.util.concurrent | executor |
| java.util.logging | java-util-logging |
| JAX-RS (Client) | jaxrs-client |
| JAX-RS (Server) | jaxrs |
| JAX-WS | jaxws |
| JBoss Logging Appender | jboss-logmanager-appender |
| JBoss Logging MDC | jboss-logmanager-mdc |
| JMS | jms |
| JSP | jsp |
| K8s Client | kubernetes-client |
| kotlinx.coroutines | kotlinx-coroutines |
| Log4j Appender | log4j-appender |
| Log4j MDC (1.x) | log4j-mdc |
| Log4j Context Data (2.x) | log4j-context-data |
| Logback Appender | logback-appender |
| Logback MDC | logback-mdc |
| Micrometer | micrometer |
| MongoDB | mongo |
| Netflix Hystrix | hystrix |
| Netty | netty |
| OkHttp | okhttp |
| OpenLiberty | liberty |
| OpenTelemetry Extension Annotations | opentelemetry-extension-annotations |
| OpenTelemetry Instrumentation Annotations | opentelemetry-instrumentation-annotations |
| OpenTelemetry API | opentelemetry-api |
| Oracle UCP | oracle-ucp |
| OSHI (Operating System and Hardware Information) | oshi |
| Play Framework | play |
| Play WS HTTP Client | play-ws |
| Quartz | quartz |
| RabbitMQ Client | rabbitmq |
| Ratpack | ratpack |
| ReactiveX RxJava | rxjava |
| Reactor | reactor |
| Reactor Netty | reactor-netty |
| Redis Jedis | jedis |
| Redis Lettuce | lettuce |
| Rediscala | rediscala |
| Redisson | redisson |
| Restlet | restlet |
| Scala ForkJoinPool | scala-fork-join |
| Spark Web Framework | spark |
| Spring Batch | spring-batch |
| Spring Core | spring-core |
| Spring Data | spring-data |
| Spring JMS | spring-jms |
| Spring Integration | spring-integration |
| Spring Kafka | spring-kafka |
| Spring RabbitMQ | spring-rabbit |
| Spring RMI | spring-rmi |
| Spring Scheduling | spring-scheduling |
| Spring Web | spring-web |
| Spring WebFlux | spring-webflux |
| Spring Web MVC | spring-webmvc |
| Spring Web Services | spring-ws |
| Spymemcached | spymemcached |
| Tomcat JDBC | tomcat-jdbc |
| Twilio SDK | twilio |
| Twitter Finatra | finatra |
| Undertow | undertow |
| Vaadin | vaadin |
| Vibur DBCP | vibur-dbcp |
| OpenTelemetry API | opentelemetry-api |
| Oracle UCP | oracle-ucp |
| OSHI (Operating System and Hardware Information) | oshi |
| Play Framework | play |
| Play WS HTTP Client | play-ws |
| Quartz | quartz |
| RabbitMQ Client | rabbitmq |
| Ratpack | ratpack |
| ReactiveX RxJava | rxjava |
| Reactor | reactor |
| Reactor Netty | reactor-netty |
| Redis Jedis | jedis |
| Redis Lettuce | lettuce |
| Rediscala | rediscala |
| Redisson | redisson |
| Restlet | restlet |
| Scala ForkJoinPool | scala-fork-join |
| Spark Web Framework | spark |
| Spring Batch | spring-batch |
| Spring Core | spring-core |
| Spring Data | spring-data |
| Spring JMS | spring-jms |
| Spring Integration | spring-integration |
| Spring Kafka | spring-kafka |
| Spring RabbitMQ | spring-rabbit |
| Spring RMI | spring-rmi |
| Spring Scheduling | spring-scheduling |
| Spring Web | spring-web |
| Spring WebFlux | spring-webflux |
| Spring Web MVC | spring-webmvc |
| Spring Web Services | spring-ws |
| Spymemcached | spymemcached |
| Tomcat JDBC | tomcat-jdbc |
| Twilio SDK | twilio |
| Twitter Finatra | finatra |
| Undertow | undertow |
| Vaadin | vaadin |
| Vibur DBCP | vibur-dbcp |
**Note:** When using environment variables, dashes (`-`) should be converted to
underscores (`_`). For example, to suppress traces from `akka-actor` library,
@ -351,7 +365,9 @@ instrumentation which would also disable the instrumentation's capturing of
{{% config_option
name="otel.instrumentation.common.experimental.controller-telemetry.enabled"
default=true
%}} Enables the controller telemetry. {{% /config_option %}} {{% config_option
%}} Enables the controller telemetry. {{% /config_option %}}
{{% config_option
name="otel.instrumentation.common.experimental.view-telemetry.enabled"
default=true
%}} Enables the view telemetry. {{% /config_option %}}

46
content/en/docs/instrumentation/java/automatic/annotations.md
View File

@ -7,14 +7,15 @@ javaAnnotationsVersion: 1.23.0
---
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
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
You'll need to add a dependency on the `opentelemetry-instrumentation-annotations`
library to use the `@WithSpan` annotation.
You'll need to add a dependency on the
`opentelemetry-instrumentation-annotations` library to use the `@WithSpan`
annotation.
### Maven
@ -57,22 +58,22 @@ 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)
* [com.google.common.util.concurrent.ListenableFuture](https://guava.dev/releases/10.0/api/docs/com/google/common/util/concurrent/ListenableFuture.html)
* [org.reactivestreams.Publisher](https://www.reactive-streams.org/reactive-streams-1.0.1-javadoc/org/reactivestreams/Publisher.html)
* [reactor.core.publisher.Mono](https://projectreactor.io/docs/core/3.1.0.RELEASE/api/reactor/core/publisher/Mono.html)
* [reactor.core.publisher.Flux](https://projectreactor.io/docs/core/3.1.0.RELEASE/api/reactor/core/publisher/Flux.html)
* [io.reactivex.Completable](https://reactivex.io/RxJava/2.x/javadoc/index.html?io/reactivex/Completable.html)
* [io.reactivex.Maybe](https://reactivex.io/RxJava/2.x/javadoc/index.html?io/reactivex/Maybe.html)
* [io.reactivex.Single](https://reactivex.io/RxJava/2.x/javadoc/index.html?io/reactivex/Single.html)
* [io.reactivex.Observable](https://reactivex.io/RxJava/2.x/javadoc/index.html?io/reactivex/Observable.html)
* [io.reactivex.Flowable](https://reactivex.io/RxJava/2.x/javadoc/index.html?io/reactivex/Flowable.html)
* [io.reactivex.parallel.ParallelFlowable](https://reactivex.io/RxJava/2.x/javadoc/index.html?io/reactivex/parallel/ParallelFlowable.html)
- [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)
- [com.google.common.util.concurrent.ListenableFuture](https://guava.dev/releases/10.0/api/docs/com/google/common/util/concurrent/ListenableFuture.html)
- [org.reactivestreams.Publisher](https://www.reactive-streams.org/reactive-streams-1.0.1-javadoc/org/reactivestreams/Publisher.html)
- [reactor.core.publisher.Mono](https://projectreactor.io/docs/core/3.1.0.RELEASE/api/reactor/core/publisher/Mono.html)
- [reactor.core.publisher.Flux](https://projectreactor.io/docs/core/3.1.0.RELEASE/api/reactor/core/publisher/Flux.html)
- [io.reactivex.Completable](https://reactivex.io/RxJava/2.x/javadoc/index.html?io/reactivex/Completable.html)
- [io.reactivex.Maybe](https://reactivex.io/RxJava/2.x/javadoc/index.html?io/reactivex/Maybe.html)
- [io.reactivex.Single](https://reactivex.io/RxJava/2.x/javadoc/index.html?io/reactivex/Single.html)
- [io.reactivex.Observable](https://reactivex.io/RxJava/2.x/javadoc/index.html?io/reactivex/Observable.html)
- [io.reactivex.Flowable](https://reactivex.io/RxJava/2.x/javadoc/index.html?io/reactivex/Flowable.html)
- [io.reactivex.parallel.ParallelFlowable](https://reactivex.io/RxJava/2.x/javadoc/index.html?io/reactivex/parallel/ParallelFlowable.html)
## Adding attributes to the span with `@SpanAttribute`
@ -108,9 +109,8 @@ code.
{{% config_option
name="otel.instrumentation.opentelemetry-instrumentation-annotations.exclude-methods" %}}
Suppress `@WithSpan` instrumentation for specific methods. Format is
`my.package.MyClass1[method1,method2];my.package.MyClass2[method3]`. {{%
/config_option %}}
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`
@ -118,8 +118,8 @@ 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]`. {{%
instrumentation for specific methods in lieu of `@WithSpan`. Format is
`my.package.MyClass1[method1,method2];my.package.MyClass2[method3]`. {{%
/config_option %}}
## Next steps

51
content/en/docs/instrumentation/java/getting-started.md
View File

@ -16,9 +16,9 @@ if you aren't familiar with gRPC.
First, get and run the hello-world example without instrumentation:
1. [Get the example code.][]
2. [Run the example:][] you should see the client output "Hello world".
3. Stop the server before proceeding, if it is still running.
1. [Get the example code.][]
2. [Run the example:][] you should see the client output "Hello world".
3. Stop the server before proceeding, if it is still running.
## Run the instrumented example
@ -26,12 +26,14 @@ Next, you'll use a [Java agent to automatically instrument](../automatic) the
client and server at launch time. While you can [configure the Java agent][] in
a number of ways, the steps below use environment variables.
1. Download [opentelemetry-javaagent.jar][] from [Releases][] of the
1. Download [opentelemetry-javaagent.jar][] from [Releases][] of the
`opentelemetry-java-instrumentation` repo. The JAR file contains the agent
and all automatic instrumentation packages. {{% alert color="info" %}}<i class="fas fa-edit"></i> Take note of the path to the JAR file.{{% /alert %}}
2. Set and export variables that specify the Java agent JAR and a [console
exporter][], using a notation suitable for your shell/terminal
environment &mdash; we illustrate a notation for bash-like shells:
and all automatic instrumentation packages.
{{% alert color="info" %}}<i class="fas fa-edit"></i> Take note of the path
to the JAR file.{{% /alert %}}
2. Set and export variables that specify the Java agent JAR and a [console
exporter][], using a notation suitable for your shell/terminal environment
&mdash; we illustrate a notation for bash-like shells:
```console
$ export JAVA_OPTS="-javaagent:PATH/TO/opentelemetry-javaagent.jar"
@ -41,7 +43,8 @@ a number of ways, the steps below use environment variables.
{{% alert title="Important" color="warning" %}}Replace `PATH/TO` above, with
your path to the JAR.{{% /alert %}}
3. Run the **server** as a background process. For example, for bash-like
3. Run the **server** as a background process. For example, for bash-like
shells run:
```console
@ -52,7 +55,8 @@ a number of ways, the steps below use environment variables.
```
Note the output from the `otel.javaagent`.
4. From the _same_ terminal, run the **client**:
4. From the _same_ terminal, run the **client**:
```console
$ ./build/install/examples/bin/hello-world-client
@ -64,7 +68,7 @@ a number of ways, the steps below use environment variables.
INFO: Greeting: Hello world
```
5. Stop the server process. For example, for bash-like shells run:
5. Stop the server process. For example, for bash-like shells run:
```console
$ jobs
@ -139,15 +143,22 @@ For more:
- Run this example with another [exporter][] for telemetry data.
- Try [automatic instrumentation](../automatic/) on one of your own apps.
- For light-weight customized telemetry, try [annotations][].
- Learn about [manual instrumentation][] and try out more [examples]({{% relref examples %}}).
- Learn about [manual instrumentation][] and try out more
[examples]({{% relref examples %}}).
[annotations]: ../automatic/annotations
[configure the Java agent]: ../automatic/#configuring-the-agent
[console exporter]: https://github.com/open-telemetry/opentelemetry-java/blob/main/sdk-extensions/autoconfigure/README.md#logging-exporter
[exporter]: https://github.com/open-telemetry/opentelemetry-java/blob/main/sdk-extensions/autoconfigure/README.md#exporters
[Get the example code.]: https://grpc.io/docs/languages/java/quickstart/#get-the-example-code
[Java Quick start example]: https://grpc.io/docs/languages/java/quickstart/
[configure the java agent]: ../automatic/#configuring-the-agent
[console exporter]:
https://github.com/open-telemetry/opentelemetry-java/blob/main/sdk-extensions/autoconfigure/README.md#logging-exporter
[exporter]:
https://github.com/open-telemetry/opentelemetry-java/blob/main/sdk-extensions/autoconfigure/README.md#exporters
[get the example code.]:
https://grpc.io/docs/languages/java/quickstart/#get-the-example-code
[java quick start example]: https://grpc.io/docs/languages/java/quickstart/
[manual instrumentation]: ../manual
[opentelemetry-javaagent.jar]: https://github.com/open-telemetry/opentelemetry-java-instrumentation/releases/latest/download/opentelemetry-javaagent.jar
[releases]: https://github.com/open-telemetry/opentelemetry-java-instrumentation/releases
[Run the example:]: https://grpc.io/docs/languages/java/quickstart/#run-the-example
[opentelemetry-javaagent.jar]:
https://github.com/open-telemetry/opentelemetry-java-instrumentation/releases/latest/download/opentelemetry-javaagent.jar
[releases]:
https://github.com/open-telemetry/opentelemetry-java-instrumentation/releases
[run the example:]:
https://grpc.io/docs/languages/java/quickstart/#run-the-example

133
content/en/docs/instrumentation/java/manual.md
View File

@ -23,17 +23,18 @@ interface.
If you are an application developer, you need to configure an instance of the
`OpenTelemetrySdk` as early as possible in your application. This can be done
using the `OpenTelemetrySdk.builder()` method.
The returned `OpenTelemetrySdkBuilder` instance gets the providers related to the
signals, tracing and metrics, in order to build the `OpenTelemetry` instance.
using the `OpenTelemetrySdk.builder()` method. The returned
`OpenTelemetrySdkBuilder` instance gets the providers related to the signals,
tracing and metrics, in order to build the `OpenTelemetry` instance.
You can build the providers by using the `SdkTracerProvider.builder()` and
`SdkMeterProvider.builder()` methods.
It is also strongly recommended to define a `Resource` instance as a representation of the
entity producing the telemetry; in particular the `service.name` attribute is
the most important piece of telemetry source-identifying info.
`SdkMeterProvider.builder()` methods. It is also strongly recommended to define
a `Resource` instance as a representation of the entity producing the telemetry;
in particular the `service.name` attribute is the most important piece of
telemetry source-identifying info.
### Maven
```xml
<project>
<dependencyManagement>
@ -71,6 +72,7 @@ the most important piece of telemetry source-identifying info.
```
### Gradle
```kotlin
dependencies {
implementation 'io.opentelemetry:opentelemetry-api:{{% param javaVersion %}}'
@ -81,6 +83,7 @@ dependencies {
```
### Imports
```java
import io.opentelemetry.api.OpenTelemetry;
import io.opentelemetry.api.common.Attributes;
@ -98,6 +101,7 @@ import io.opentelemetry.semconv.resource.attributes.ResourceAttributes;
```
### Example
```java
Resource resource = Resource.getDefault()
.merge(Resource.create(Attributes.of(ResourceAttributes.SERVICE_NAME, "logical-service-name")));
@ -135,8 +139,8 @@ need to acquire a [`Tracer`](/docs/concepts/signals/traces/#tracer).
First, a `Tracer` must be acquired, which is responsible for creating spans and
interacting with the [Context](#context-propagation). A tracer is acquired by
using the OpenTelemetry API specifying the name and version of the
[library instrumenting][Instrumentation Library] the [instrumented library] or
using the OpenTelemetry API specifying the name and version of the [library
instrumenting][instrumentation library] the [instrumented library] or
application to be monitored. More information is available in the specification
chapter [Obtaining a Tracer].
@ -273,7 +277,7 @@ span.setAttribute("http.url", url.toString());
There are semantic conventions for spans representing operations in well-known
protocols like HTTP or database calls. Semantic conventions for these spans are
defined in the specification at
[Trace Semantic Conventions]({{< relref "/docs/reference/specification/trace/semantic_conventions" >}}).
[Trace Semantic Conventions](/docs/reference/specification/trace/semantic_conventions/).
First add the semantic conventions as a dependency to your application:
@ -306,9 +310,9 @@ span.setAttribute(SemanticAttributes.HTTP_URL, url.toString());
[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 itself is a key:value map
paired automatically with a timestamp.
[Span Events](/docs/concepts/signals/traces/#span-events)) that can carry zero
or more [Span Attributes](#span-attributes), each of which itself is a key:value
map paired automatically with a timestamp.
```java
span.addEvent("Init");
@ -328,9 +332,9 @@ span.addEvent("End Computation", eventAttributes);
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.
[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")
@ -567,8 +571,8 @@ available:
processing a request. Histogram measurements are aggregated to explicit bucket
histograms by default.
**Note**: The asynchronous varieties of counter and up down counter assume that the
registered callback is observing the cumulative sum. For example, if you
**Note**: The asynchronous varieties of counter and up down counter assume that
the registered callback is observing the cumulative sum. For example, if you
register an asynchronous counter whose callback records bytes sent over a
network, it must record the cumulative sum of all bytes sent over the network,
rather than trying to compute and record the difference since last call.
@ -693,9 +697,9 @@ exporters out of the box:
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`.
- 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].
@ -759,9 +763,9 @@ OpenTelemetry provides the following exporters out of the box:
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`.
- 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].
@ -797,11 +801,13 @@ instrument.
### Auto Configuration
Instead of manually creating the `OpenTelemetry` instance by using the SDK builders
directly from your code, it is also possible to use the SDK auto-configuration extension
through the `opentelemetry-sdk-extension-autoconfigure` module.
Instead of manually creating the `OpenTelemetry` instance by using the SDK
builders directly from your code, it is also possible to use the SDK
auto-configuration extension through the
`opentelemetry-sdk-extension-autoconfigure` module.
This module is made available by adding the following dependency to your application.
This module is made available by adding the following dependency to your
application.
```xml
<dependency>
@ -810,39 +816,44 @@ This module is made available by adding the following dependency to your applica
</dependency>
```
It allows you to auto-configure the OpenTelemetry SDK based on a standard set of supported
environment variables and system properties.
Each environment variable has a corresponding system property named the same way but as
lower case and using the `.` (dot) character instead of the `_` (underscore) as separator.
It allows you to auto-configure the OpenTelemetry SDK based on a standard set of
supported environment variables and system properties. Each environment variable
has a corresponding system property named the same way but as lower case and
using the `.` (dot) character instead of the `_` (underscore) as separator.
The logical service name can be specified via the `OTEL_SERVICE_NAME` environment variable
(or `otel.service.name` system property).
The logical service name can be specified via the `OTEL_SERVICE_NAME`
environment variable (or `otel.service.name` system property).
The traces, metrics or logs exporters can be set via the `OTEL_TRACES_EXPORTER`,
`OTEL_METRICS_EXPORTER` and `OTEL_LOGS_EXPORTER` environment variables.
For example `OTEL_TRACES_EXPORTER=jaeger` configures your application to use the Jaeger exporter.
The corresponding Jaeger exporter library has to be provided in the classpath of the application as well.
`OTEL_METRICS_EXPORTER` and `OTEL_LOGS_EXPORTER` environment variables. For
example `OTEL_TRACES_EXPORTER=jaeger` configures your application to use the
Jaeger exporter. The corresponding Jaeger exporter library has to be provided in
the classpath of the application as well.
It's also possible to set up the propagators via the `OTEL_PROPAGATORS` environment variable,
like for example using the `tracecontext` value to use [W3C Trace Context](https://www.w3.org/TR/trace-context/).
It's also possible to set up the propagators via the `OTEL_PROPAGATORS`
environment variable, like for example using the `tracecontext` value to use
[W3C Trace Context](https://www.w3.org/TR/trace-context/).
For more details, see all the supported configuration options in the module's
[README](https://github.com/open-telemetry/opentelemetry-java/tree/main/sdk-extensions/autoconfigure).
The SDK auto-configuration has to be initialized from your code in order to allow the module
to go through the provided environment variables (or system properties) and set up the
`OpenTelemetry` instance by using the builders internally.
The SDK auto-configuration has to be initialized from your code in order to
allow the module to go through the provided environment variables (or system
properties) and set up the `OpenTelemetry` instance by using the builders
internally.
```java
OpenTelemetrySdk sdk = AutoConfiguredOpenTelemetrySdk.initialize()
.getOpenTelemetrySdk();
```
When environment variables or system properties are not sufficient, you can use some extension points
provided through the auto-configure [SPI](https://github.com/open-telemetry/opentelemetry-java/tree/main/sdk-extensions/autoconfigure-spi)
When environment variables or system properties are not sufficient, you can use
some extension points provided through the auto-configure
[SPI](https://github.com/open-telemetry/opentelemetry-java/tree/main/sdk-extensions/autoconfigure-spi)
and several methods in the `AutoConfiguredOpenTelemetrySdk` class.
Following an example with a code snippet for adding an additional custom span processor.
Following an example with a code snippet for adding an additional custom span
processor.
```java
AutoConfiguredOpenTelemetrySdk.builder()
@ -909,15 +920,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
[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 Registry]: /ecosystem/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
[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
[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 registry]: /ecosystem/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
[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

2
layouts/shortcodes/config_option.html
View File

@ -16,5 +16,5 @@
<span class="label">Default</span>: {{ .Get "default" }}<br>
{{ end -}}
<span class="label">Description</span>:
{{- .Inner }}
{{ trim .InnerDeindent "\n " }}
</div>