README and docs reorg (#2226)

docs/agent-config.md

@@ -0,0 +1,159 @@
+# Configuration parameters
+
+## NOTE: subject to change!
+
+Note: These parameter names are very likely to change over time, so please check
+back here when trying out a new version! Please report any bugs or unexpected
+behavior you find.
+
+## Contents
+
+* [Exporters](#exporters)
+  + [OTLP exporter (both span and metric exporters)](#otlp-exporter--both-span-and-metric-exporters-)
+  + [Jaeger exporter](#jaeger-exporter)
+  + [Zipkin exporter](#zipkin-exporter)
+  + [Prometheus exporter](#prometheus-exporter)
+  + [Logging exporter](#logging-exporter)
+* [Trace context propagation](#propagator)
+* [OpenTelemetry Resource](#opentelemetry-resource)
+* [Peer service name](#peer-service-name)
+* [Batch span processor](#batch-span-processor)
+* [Trace config](#trace-config)
+* [Interval metric reader](#interval-metric-reader)
+* [Customizing the OpenTelemetry SDK](#customizing-the-opentelemetry-sdk)
+* [Suppressing specific auto-instrumentation](#suppressing-specific-auto-instrumentation)
+
+
+## Exporters
+
+The following configuration properties are common to all exporters:
+
+| System property | Environment variable | Purpose                                                                                                                                                 |
+|-----------------|----------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------|
+| otel.trace.exporter   | OTEL_TRACE_EXPORTER        | The exporter to be used for tracing. Default is `otlp`. `none` means no exporter. |
+| otel.metrics.exporter   | OTEL_METRICS_EXPORTER        | The exporter to be used for metrics. Default is `otlp`. `none` means no exporter. |
+
+### OTLP exporter (both span and metric exporters)
+
+A simple wrapper for the OpenTelemetry Protocol (OTLP) span and metric exporters of opentelemetry-java.
+
+| System property              | Environment variable        | Description                                                               |
+|------------------------------|-----------------------------|---------------------------------------------------------------------------|
+| otel.trace.exporter=otlp (default) | OTEL_TRACE_EXPORTER=otlp          | Select the OpenTelemetry exporter for tracing (default)                                   |
+| otel.metrics.exporter=otlp (default) | OTEL_METRICS_EXPORTER=otlp          | Select the OpenTelemetry exporter for metrics (default)                                   |
+| otel.exporter.otlp.endpoint  | OTEL_EXPORTER_OTLP_ENDPOINT | The OTLP endpoint to connect to. Must be a URL with a scheme of either `http` or `https` based on the use of TLS. Default is `http://localhost:4317`.            |
+| otel.exporter.otlp.headers   | OTEL_EXPORTER_OTLP_HEADERS  | Key-value pairs separated by semicolons to pass as request headers        |
+| otel.exporter.otlp.timeout   | OTEL_EXPORTER_OTLP_TIMEOUT  | The maximum waiting time allowed to send each batch. Default is `1000`.   |
+
+To configure the service name for the OTLP exporter, add the `service.name` key
+to the OpenTelemetry Resource ([see below](#opentelemetry-resource)), e.g. `OTEL_RESOURCE_ATTRIBUTES=service.name=myservice`.
+
+### Jaeger exporter
+
+A simple wrapper for the Jaeger exporter of opentelemetry-java. This exporter uses gRPC for its communications protocol.
+
+| System property                   | Environment variable              | Description                                                                                        |
+|-----------------------------------|-----------------------------------|----------------------------------------------------------------------------------------------------|
+| otel.trace.exporter=jaeger              | OTEL_TRACE_EXPORTER=jaeger              | Select the Jaeger exporter                                                                         |
+| otel.exporter.jaeger.endpoint     | OTEL_EXPORTER_JAEGER_ENDPOINT     | The Jaeger gRPC endpoint to connect to. Default is `localhost:14250`.                              |
+
+### Zipkin exporter
+A simple wrapper for the Zipkin exporter of opentelemetry-java. It sends JSON in [Zipkin format](https://zipkin.io/zipkin-api/#/default/post_spans) to a specified HTTP URL.
+
+| System property                   | Environment variable              | Description                                                                                                               |
+|-----------------------------------|-----------------------------------|-----------------------------------------------------------------------------------------------------------------------|
+| otel.trace.exporter=zipkin              | OTEL_TRACE_EXPORTER=zipkin              | Select the Zipkin exporter                                                                                             |
+| otel.exporter.zipkin.endpoint     | OTEL_EXPORTER_ZIPKIN_ENDPOINT     | The Zipkin endpoint to connect to. Default is `http://localhost:9411/api/v2/spans`. Currently only HTTP is supported. |
+
+### Prometheus exporter
+A simple wrapper for the Prometheus exporter of opentelemetry-java.
+
+| System property               | Environment variable          | Description                                                                        |
+|-------------------------------|-------------------------------|------------------------------------------------------------------------------------|
+| otel.metrics.exporter=prometheus      | OTEL_METRICS_EXPORTER=prometheus      | Select the Prometheus exporter                                                     |
+| otel.exporter.prometheus.port | OTEL_EXPORTER_PROMETHEUS_PORT | The local port used to bind the prometheus metric server. Default is `9464`.       |
+| otel.exporter.prometheus.host | OTEL_EXPORTER_PROMETHEUS_HOST | The local address used to bind the prometheus metric server. Default is `0.0.0.0`. |
+
+### Logging exporter
+
+The logging exporter prints the name of the span along with its
+attributes to stdout. It's mainly used for testing and debugging.
+
+| System property              | Environment variable         | Description                                                                  |
+|------------------------------|------------------------------|------------------------------------------------------------------------------|
+| otel.trace.exporter=logging        | OTEL_TRACE_EXPORTER=logging        | Select the logging exporter for tracing                                               |
+| otel.metrics.exporter=logging        | OTEL_METRICS_EXPORTER=logging        | Select the logging exporter for metrics                                               |
+| otel.exporter.logging.prefix | OTEL_EXPORTER_LOGGING_PREFIX | An optional string printed in front of the span name and attributes.         |
+
+## Propagator
+
+The propagators determine which distributed tracing header formats are used, and which baggage propagation header formats are used.
+
+| System property  | Environment variable | Description                                                                                                     |
+|------------------|----------------------|-----------------------------------------------------------------------------------------------------------------|
+| otel.propagators | OTEL_PROPAGATORS     | The propagators to be used. Use a comma-separated list for multiple propagators. Supported propagators are `tracecontext`, `baggage`, `b3`, `b3multi`, `jaeger`, `ottracer`, and `xray`. Default is `tracecontext,baggage` (W3C). |
+
+## OpenTelemetry Resource
+
+The [OpenTelemetry Resource](https://github.com/open-telemetry/opentelemetry-specification/blob/master/specification/resource/sdk.md)
+is a representation of the entity producing telemetry.
+
+| System property          | Environment variable     | Description                                                                        |
+|--------------------------|--------------------------|------------------------------------------------------------------------------------|
+| otel.resource.attributes | OTEL_RESOURCE_ATTRIBUTES | Specify resource attributes in the following format: key1=val1,key2=val2,key3=val3 |
+
+## Peer service name
+
+The [peer service name](https://github.com/open-telemetry/opentelemetry-specification/blob/master/specification/trace/semantic_conventions/span-general.md#general-remote-service-attributes) is the name of a remote service being connected to. It corresponds to `service.name` in the [Resource](https://github.com/open-telemetry/opentelemetry-specification/tree/master/specification/resource/semantic_conventions#service) for the local service.
+
+| System property                     | Environment variable              | Description                                                                      |
+|------------------------------------|------------------------------------|----------------------------------------------------------------------------------|
+| otel.endpoint.peer.service.mapping | OTEL_ENDPOINT_PEER_SERVICE_MAPPING | Used to specify a mapping from hostnames or IP addresses to peer services, as a comma-separated list of host=name pairs. The peer service is added as an attribute to a span whose host or IP match the mapping. For example, if set to 1.2.3.4=cats-service,dogs-abcdef123.serverlessapis.com=dogs-api, 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`. |
+
+## Batch span processor
+
+| System property           | Environment variable      | Description                                                                        |
+|---------------------------|---------------------------|------------------------------------------------------------------------------------|
+| otel.bsp.schedule.delay   | OTEL_BSP_SCHEDULE_DELAY   | The interval, in milliseconds, between two consecutive exports. Default is `5000`. |
+| otel.bsp.max.queue.size   | OTEL_BSP_MAX_QUEUE_SIZE   | The maximum queue size. Default is `2048`.                                             |
+| otel.bsp.max.export.batch.size | OTEL_BSP_MAX_EXPORT_BATCH_SIZE | The maximum batch size. Default is `512`.                                              |
+| otel.bsp.export.timeout   | OTEL_BSP_EXPORT_TIMEOUT   | The maximum allowed time, in milliseconds, to export data. Default is `30000`.         |
+
+## Trace config
+
+| System property                 | Environment variable            | Description                                                  |
+|---------------------------------|---------------------------------|--------------------------------------------------------------|
+| otel.trace.sampler              | OTEL_TRACE_SAMPLER              | The sampler to use for tracing. Defaults to `parentbased_always_on` |
+| otel.trace.sampler.arg          | OTEL_TRACE_SAMPLER_ARG          | An argument to the configured tracer if supported, for example a ratio. |
+| otel.span.attribute.count.limit | OTEL_SPAN_ATTRIBUTE_COUNT_LIMIT | The maximum number of attributes per span. Default is `32`.  |
+| otel.span.event.count.limit     | OTEL_SPAN_EVENT_COUNT_LIMIT     | The maximum number of events per span. Default is `128`.     |
+| otel.span.link.count.limit      | OTEL_SPAN_LINK_COUNT_LIMIT      | The maximum number of links per span. Default is `32`        |
+
+Supported values for `otel.trace.sampler` are
+
+- "always_on": AlwaysOnSampler
+- "always_off": AlwaysOffSampler
+- "traceidratio": TraceIdRatioBased. `otel.trace.sampler.arg` sets the ratio.
+- "parentbased_always_on": ParentBased(root=AlwaysOnSampler)
+- "parentbased_always_off": ParentBased(root=AlwaysOffSampler)
+- "parentbased_traceidratio": ParentBased(root=TraceIdRatioBased). `otel.trace.sampler.arg` sets the ratio.
+
+## Interval metric reader
+
+| System property          | Environment variable     | Description                                                                       |
+|--------------------------|--------------------------|-----------------------------------------------------------------------------------|
+| otel.imr.export.interval | OTEL_IMR_EXPORT_INTERVAL | The interval, in milliseconds, between pushes to the exporter. Default is `60000`.|
+
+## Customizing the OpenTelemetry SDK
+
+*Customizing the SDK is highly advanced behavior and is still in the prototyping phase. It may change drastically or be removed completely. Use
+with caution*
+
+The OpenTelemetry SDK exposes SPI [hooks](https://github.com/open-telemetry/opentelemetry-java/tree/main/sdk-extensions/autoconfigure/src/main/java/io/opentelemetry/sdk/autoconfigure/spi)
+for customizing its behavior, such as the `Resource` attached to spans or the `Sampler`.
+
+Because the automatic instrumentation runs in a different classpath than the instrumented application, it is not possible for customization in the application to take advantage of this customization. In order to provide such customization, you can provide the path to a JAR file, including an SPI implementation using the system property `otel.initializer.jar`. Note that this JAR needs to shade the OpenTelemetry API in the same way as the agent does. The simplest way to do this is to use the same shading configuration as the agent from [here](https://github.com/open-telemetry/opentelemetry-java-instrumentation/blob/cfade733b899a2f02cfec7033c6a1efd7c54fd8b/java-agent/java-agent.gradle#L39). In addition, you must specify the `io.opentelemetry.javaagent.shaded.io.opentelemetry.api.trace.spi.TraceProvider` to the name of the class that implements the SPI.
+
+## Suppressing specific auto-instrumentation
+
+See [suppressing specific auto-instrumentation](suppressing-instrumentation.md)

docs/agent-features.md

@@ -4,13 +4,12 @@ This lists out some of the features specific to java agents that OpenTelemetry A
 provides.
 
 - Bundled exporters
-  - OTLP
+  - [OTLP](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/protocol/otlp.md)
   - Jaeger gRPC
-  - Jaeger Thrift (considering to remove in https://github.com/open-telemetry/opentelemetry-java-instrumentation/issues/1973)
   - Logging
   - Zipkin
 - Bundled propagators
-  - W3C TraceContext / Baggage
+  - [W3C TraceContext / Baggage](https://www.w3.org/TR/trace-context/)
   - All Java [trace propagator extensions](https://github.com/open-telemetry/opentelemetry-java/tree/master/extensions/trace-propagators)
 - Environment variable configuration as per [spec](https://github.com/open-telemetry/opentelemetry-specification/blob/master/specification/sdk-environment-variables.md)
   - Additional support for system properties for same variables by transforming UPPER_UNDERSCORE -> lower.dot

docs/manual-instrumentation.md

@@ -0,0 +1,121 @@
+# Manual instrumentation
+
+For most users, the out-of-the-box instrumentation is completely sufficient and nothing more has to
+be done.  Sometimes, however, users wish to add attributes to the otherwise automatic spans,
+or they might want to manually create spans for their own custom code.
+
+## Contents
+
+- [Manual instrumentation](#manual-instrumentation)
+- [Dependencies](#dependencies)
+  * [Maven](#maven)
+  * [Gradle](#gradle)
+- [Adding attributes to the current span](#adding-attributes-to-the-current-span)
+- [Creating spans around methods with `@WithSpan`](#creating-spans-around-methods-with---withspan-)
+  * [Suppressing `@WithSpan` instrumentation](#suppressing---withspan--instrumentation)
+  * [Creating spans around methods with `otel.instrumentation.methods.include`](#creating-spans-around-methods-with-otelinstrumentationmethodsinclude)
+- [Creating spans manually with a Tracer](#creating-spans-manually-with-a-tracer)
+
+# Dependencies
+
+> :warning: prior to version 1.0.0, `opentelemetry-javaagent-all.jar`
+only supports manual instrumentation using the `opentelemetry-api` version with the same version
+number as the Java agent you are using. Starting with 1.0.0, the Java agent will start supporting
+multiple (1.0.0+) versions of `opentelemetry-api`.
+
+You'll need to add a dependency on the `opentelemetry-api` library to get started; if you intend to
+use the `@WithSpan` annotation, also include the `opentelemetry-extension-annotations` dependency.
+
+## Maven
+
+```xml
+  <dependencies>
+    <dependency>
+      <groupId>io.opentelemetry</groupId>
+      <artifactId>opentelemetry-api</artifactId>
+      <version>0.15.0</version>
+    </dependency>
+    <dependency>
+      <groupId>io.opentelemetry</groupId>
+      <artifactId>opentelemetry-extension-annotations</artifactId>
+      <version>0.15.0</version>
+    </dependency>
+  </dependencies>
+```
+
+## Gradle
+
+```groovy
+dependencies {
+    implementation('io.opentelemetry:opentelemetry-api:0.15.0')
+    implementation('io.opentelemetry:opentelemetry-extension-annotations:0.15.0')
+}
+```
+
+# Adding attributes to the current span
+
+A common need when instrumenting an application is to capture additional application-specific or
+business-specific information as additional attributes to an existing span from the automatic
+instrumentation. Grab the current span with `Span.current()` and use the `setAttribute()`
+methods:
+
+```java
+import io.opentelemetry.api.trace.Span;
+
+// ...
+
+Span span = Span.current();
+span.setAttribute(..., ...);
+```
+
+# Creating spans around methods with `@WithSpan`
+
+Another common situation is to capture a span corresponding to one of your methods. The
+`@WithSpan` annotation makes this straightforward:
+
+```java
+import io.opentelemetry.extension.annotations.WithSpan;
+
+public class MyClass {
+  @WithSpan
+  public void MyLogic() {
+      <...>
+  }
+}
+```
+
+Each time the application invokes the annotated method, it creates a span that denote its duration
+and provides any thrown exceptions. Unless specified as an argument to the annotation, the span name
+will be `<className>.<methodName>`.
+
+## Suppressing `@WithSpan` instrumentation
+
+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.
+
+| System property                 | Environment variable            | Purpose                                                                                                                                  |
+|---------------------------------|---------------------------------|------------------------------------------------------------------------------------------------------------------------------------------|
+| otel.instrumentation.opentelemetry-annotations.exclude-methods | OTEL_INSTRUMENTATION_OPENTELEMETRY_ANNOTATIONS_EXCLUDE_METHODS | Suppress `@WithSpan` instrumentation for specific methods.
+Format is "my.package.MyClass1[method1,method2];my.package.MyClass2[method3]" |
+
+## Creating spans around methods with otel.instrumentation.methods.include
+This is a way to to create a span around a first-party code method without using `@WithSpan`.
+
+| System property                 | Environment variable            | Purpose                                                                                                                                  |
+|---------------------------------|---------------------------------|------------------------------------------------------------------------------------------------------------------------------------------|
+| otel.instrumentation.methods.include |                                 | Add instrumentation for specific methods in lieu of `@WithSpan`.
+Format is "my.package.MyClass1[method1,method2];my.package.MyClass2[method3]" |
+
+# Creating spans manually with a Tracer
+
+If `@WithSpan` doesn't work for your specific use case, you're still in luck!
+
+The underlying OpenTelemetry API allows you to [obtain a tracer](https://github.com/open-telemetry/opentelemetry-java/blob/main/QUICKSTART.md#tracing)
+that can be used to [manually create spans](https://github.com/open-telemetry/opentelemetry-java/blob/main/QUICKSTART.md#create-a-basic-span)
+and execute code within the scope of that span.
+
+See the [OpenTelemetry Java
+QuickStart](https://github.com/open-telemetry/opentelemetry-java/blob/master/QUICKSTART.md#tracing)
+for a detailed en example of how to configure OpenTelemetry with code and
+how to use the `Tracer`, `Scope` and `Span` interfaces to
+instrument your application.

docs/supported-libraries.md

@@ -0,0 +1,127 @@
+
+# Supported libraries, frameworks, and application servers
+
+We automatically instrument and support a huge number of libraries, frameworks,
+and application servers... right out of the box!
+
+Don't see your favorite tool listed here?  Consider [filing an issue](https://github.com/open-telemetry/opentelemetry-java-instrumentation/issues),
+or [contributing](../CONTRIBUTING.md).
+
+## Contents
+
+  * [Libraries / Frameworks](#libraries---frameworks)
+  * [Application Servers](#application-servers)
+  * [Disabled instrumentations](#disabled-instrumentations)
+    + [Grizzly instrumentation](#grizzly-instrumentation)
+
+## Libraries / Frameworks
+
+These are the supported libraries and frameworks:
+
+| Library/Framework                                                                                                                     | Versions                       |
+|---------------------------------------------------------------------------------------------------------------------------------------|--------------------------------|
+| [Akka HTTP](https://doc.akka.io/docs/akka-http/current/index.html)                                                                    | 10.0+                          |
+| [Apache Dubbo](https://github.com/apache/dubbo/)                                                                                      | 2.7+                           |
+| [Apache HttpAsyncClient](https://hc.apache.org/index.html)                                                                            | 4.1+                           |
+| [Apache HttpClient](https://hc.apache.org/index.html)                                                                                 | 2.0+                           |
+| [Apache Wicket](https://wicket.apache.org/)                                                                                           | 8.0+                           |
+| [Armeria](https://armeria.dev)                                                                                                        | 1.3+                           |
+| [AsyncHttpClient](https://github.com/AsyncHttpClient/async-http-client)                                                               | 1.9+ (not including 2.x yet)   |
+| [AWS Lambda](https://docs.aws.amazon.com/lambda/latest/dg/java-handler.html)                                                          | 1.0+                           |
+| [AWS SDK](https://aws.amazon.com/sdk-for-java/)                                                                                       | 1.11.x and 2.2.0+              |
+| [Cassandra Driver](https://github.com/datastax/java-driver)                                                                           | 3.0+                           |
+| [Couchbase Client](https://github.com/couchbase/couchbase-java-client)                                                                | 2.0+ (not including 3.x yet)   |
+| [Dropwizard Views](https://www.dropwizard.io/en/latest/manual/views.html)                                                             | 0.7+                           |
+| [Elasticsearch API](https://www.elastic.co/guide/en/elasticsearch/client/java-api/current/index.html)                                 | 5.0+ (not including 7.x yet)   |
+| [Elasticsearch REST Client](https://www.elastic.co/guide/en/elasticsearch/client/java-rest/current/index.html)                        | 5.0+                           |
+| [Finatra](https://github.com/twitter/finatra)                                                                                         | 2.9+                           |
+| [Geode Client](https://geode.apache.org/)                                                                                             | 1.4+                           |
+| [Google HTTP Client](https://github.com/googleapis/google-http-java-client)                                                           | 1.19+                          |
+| [Grizzly](https://javaee.github.io/grizzly/httpserverframework.html)                                                                  | 2.0+ (disabled by default)     |
+| [gRPC](https://github.com/grpc/grpc-java)                                                                                             | 1.5+                           |
+| [Hibernate](https://github.com/hibernate/hibernate-orm)                                                                               | 3.3+                           |
+| [HttpURLConnection](https://docs.oracle.com/en/java/javase/11/docs/api/java.base/java/net/HttpURLConnection.html)                     | Java 7+                        |
+| [http4k <sup>&dagger;</sup>](https://www.http4k.org/guide/modules/opentelemetry/)                                                     | 3.270.0+                       |
+| [Hystrix](https://github.com/Netflix/Hystrix)                                                                                         | 1.4+                           |
+| [JAX-RS](https://javaee.github.io/javaee-spec/javadocs/javax/ws/rs/package-summary.html)                                              | 0.5+                           |
+| [JAX-RS Client](https://javaee.github.io/javaee-spec/javadocs/javax/ws/rs/client/package-summary.html)                                | 2.0+                           |
+| [JAX-WS](https://jakarta.ee/specifications/xml-web-services/2.3/apidocs/javax/xml/ws/package-summary.html)                            | 2.0+ (not including 3.x yet)   |
+| [JDBC](https://docs.oracle.com/en/java/javase/11/docs/api/java.sql/java/sql/package-summary.html)                                     | Java 7+                        |
+| [Jedis](https://github.com/xetorthio/jedis)                                                                                           | 1.4+                           |
+| [JMS](https://javaee.github.io/javaee-spec/javadocs/javax/jms/package-summary.html)                                                   | 1.1+                           |
+| [JSP](https://javaee.github.io/javaee-spec/javadocs/javax/servlet/jsp/package-summary.html)                                           | 2.3+                           |
+| [Kafka](https://kafka.apache.org/20/javadoc/overview-summary.html)                                                                    | 0.11+                          |
+| [khttp](https://khttp.readthedocs.io)                                                                                                 | 0.1+                           |
+| [Kubernetes Client](https://github.com/kubernetes-client/java)                                                                        | 7.0+                           |
+| [Lettuce](https://github.com/lettuce-io/lettuce-core)                                                                                 | 4.0+ (not including 6.x yet)   |
+| [Log4j 1](https://logging.apache.org/log4j/1.2/)                                                                                      | 1.2+                           |
+| [Log4j 2](https://logging.apache.org/log4j/2.x/)                                                                                      | 2.7+                           |
+| [Logback](http://logback.qos.ch/)                                                                                                     | 1.0+                           |
+| [Mojarra](https://projects.eclipse.org/projects/ee4j.mojarra)                                                                         | 1.2+ (not including 3.x yet)   |
+| [MongoDB Drivers](https://mongodb.github.io/mongo-java-driver/)                                                                       | 3.3+                           |
+| [MyFaces](https://myfaces.apache.org/)                                                                                                | 1.2+ (not including 3.x yet)   |
+| [Netty](https://github.com/netty/netty)                                                                                               | 3.8+                           |
+| [OkHttp](https://github.com/square/okhttp/)                                                                                           | 3.0+                           |
+| [Play](https://github.com/playframework/playframework)                                                                                | 2.3+ (not including 2.8.x yet) |
+| [Play WS](https://github.com/playframework/play-ws)                                                                                   | 1.0+                           |
+| [RabbitMQ Client](https://github.com/rabbitmq/rabbitmq-java-client)                                                                   | 2.7+                           |
+| [Ratpack](https://github.com/ratpack/ratpack)                                                                                         | 1.4+                           |
+| [Reactor](https://github.com/reactor/reactor-core)                                                                                    | 3.1+                           |
+| [Reactor Netty](https://github.com/reactor/reactor-netty)                                                                             | 0.9+                           |
+| [Rediscala](https://github.com/etaty/rediscala)                                                                                       | 1.8+                           |
+| [Redisson](https://github.com/redisson/redisson)                                                                                      | 3.0+                           |
+| [RMI](https://docs.oracle.com/en/java/javase/11/docs/api/java.rmi/java/rmi/package-summary.html)                                      | Java 7+                        |
+| [RxJava](https://github.com/ReactiveX/RxJava)                                                                                         | 1.0+                           |
+| [Servlet](https://javaee.github.io/javaee-spec/javadocs/javax/servlet/package-summary.html)                                           | 2.2+ (not including 5.x yet)   |
+| [Spark Web Framework](https://github.com/perwendel/spark)                                                                             | 2.3+                           |
+| [Spring Batch](https://spring.io/projects/spring-batch)                                                                               | 3.0+                           |
+| [Spring Data](https://spring.io/projects/spring-data)                                                                                 | 1.8+                           |
+| [Spring Scheduling](https://docs.spring.io/spring/docs/current/javadoc-api/org/springframework/scheduling/package-summary.html)       | 3.1+                           |
+| [Spring Web MVC](https://docs.spring.io/spring/docs/current/javadoc-api/org/springframework/web/servlet/mvc/package-summary.html)     | 3.1+                           |
+| [Spring Webflux](https://docs.spring.io/spring/docs/current/javadoc-api/org/springframework/web/reactive/package-summary.html)        | 5.0+                           |
+| [Spring Web Services](https://spring.io/projects/spring-ws)                                                                           | 2.0+                           |
+| [Spymemcached](https://github.com/couchbase/spymemcached)                                                                             | 2.12+                          |
+| [Struts2](https://github.com/apache/struts)                                                                                           | 2.3+                           |
+| [Twilio](https://github.com/twilio/twilio-java)                                                                                       | 6.6+ (not including 8.x yet)   |
+| [Vert.x](https://vertx.io)                                                                                                            | 3.0+                           |
+| [Vert.x RxJava2](https://vertx.io/docs/vertx-rx/java2/)                                                                               | 3.5+                           |
+
+<sup>&dagger;</sup> OpenTelemetry support provided by the library
+
+## Application Servers
+
+These are the supported application servers:
+
+| Application server                                                                        | Version                     | JVM              | OS                             |
+| ----------------------------------------------------------------------------------------- | --------------------------- | ---------------- | ------------------------------ |
+| [Glassfish](https://javaee.github.io/glassfish/)                                          | 5.0.x, 5.1.x                | OpenJDK 8, 11    | Ubuntu 18, Windows Server 2019 |
+| [JBoss EAP](https://www.redhat.com/en/technologies/jboss-middleware/application-platform) | 7.1.x, 7.3.x                | OpenJDK 8, 11    | Ubuntu 18, Windows Server 2019 |
+| [Jetty](https://www.eclipse.org/jetty/)                                                   | 9.4.x, 10.0.x, 11.0.x       | OpenJDK 8, 11    | Ubuntu 20                      |
+| [Payara](https://www.payara.fish/)                                                        | 5.0.x, 5.1.x                | OpenJDK 8, 11    | Ubuntu 18, Windows Server 2019 |
+| [Tomcat](http://tomcat.apache.org/)                                                       | 7.0.x, 8.5.x, 9.0.x, 10.0.x | OpenJDK 8, 11    | Ubuntu 18                      |
+| [TomEE](https://tomee.apache.org/)                                                        | 7.x, 8.x                    | OpenJDK 8, 11    | Ubuntu 18                      |
+| [Weblogic](https://www.oracle.com/java/weblogic/)                                         | 12                          | Oracle JDK 8     | Oracle Linux 7, 8              |
+| [Weblogic](https://www.oracle.com/java/weblogic/)                                         | 14                          | Oracle JDK 8, 11 | Oracle Linux 7, 8              |
+| [Websphere Liberty Profile](https://www.ibm.com/cloud/websphere-liberty)                  | 20.0.0.12                   | OpenJDK 8, 11    | Ubuntu 18, Windows Server 2019 |
+| [WildFly](https://www.wildfly.org/)                                                       | 13.0.x                      | OpenJDK 8        | Ubuntu 18, Windows Server 2019 |
+| [WildFly](https://www.wildfly.org/)                                                       | 17.0.1, 21.0.0              | OpenJDK 8, 11    | Ubuntu 18, Windows Server 2019 |
+
+## Disabled instrumentations
+
+Some instrumentations can produce too many spans and make traces very noisy.
+For this reason, the following instrumentations are disabled by default:
+
+- `jdbc-datasource` which creates spans whenever the `java.sql.DataSource#getConnection` method is called.
+
+To enable them, add the `otel.instrumentation.<name>.enabled` system property:
+`-Dotel.instrumentation.jdbc-datasource.enabled=true`
+
+### Grizzly instrumentation
+
+When you use
+[Grizzly](https://javaee.github.io/grizzly/httpserverframework.html) for
+Servlet-based applications, you get better experience from Servlet-specific
+support. As these two instrumentations conflict with each other, more generic
+instrumentation for Grizzly HTTP server is disabled by default. If needed,
+you can enable it by adding the following system property:
+`-Dotel.instrumentation.grizzly.enabled=true`