diff --git a/website_docs/_index.md b/website_docs/_index.md index f1031aac637..d0b91d73cd3 100644 --- a/website_docs/_index.md +++ b/website_docs/_index.md @@ -6,8 +6,6 @@ description: > A language-specific implementation of OpenTelemetry in Java. --- -**Note**: As of 3/29 this is a copy of the documentation live on opentelemetry.io, and requires updates to become current with the current Java release. - OpenTelemetry Java consists of the following repositories: - [opentelemetry-java](https://github.com/open-telemetry/opentelemetry-java): @@ -26,7 +24,7 @@ OpenTelemetry Java consists of the following repositories: | Traces | Metrics | Logs | | ------ | ------- | ------------ | -| Beta | Alpha | Experimental | +| Stable | Alpha | Experimental | ### Components @@ -44,25 +42,39 @@ OpenTelemetry Java consists of the following repositories: ### Releases -Published releases are available on maven central. +Published releases are available on maven central. We strongly recommend using our BOM to keep the +versions of the various components in sync. #### Maven ```xml + + + + + io.opentelemetry + opentelemetry-bom + 1.0.1 + pom + import + + + io.opentelemetry opentelemetry-api - 0.10.0 + ``` #### Gradle ```groovy dependencies { - implementation('io.opentelemetry:opentelemetry-api:0.10.0') + implementation platform("io.opentelemetry:opentelemetry-bom:1.0.1") + implementation('io.opentelemetry:opentelemetry-api') } ``` @@ -70,40 +82,8 @@ dependencies { - [releases](https://github.com/open-telemetry/opentelemetry-java/releases) - [maven](https://mvnrepository.com/artifact/io.opentelemetry) - - [bintray](https://bintray.com/open-telemetry/maven/opentelemetry-java) - -### Additional Information - -- [Javadoc](https://www.javadoc.io/doc/io.opentelemetry) -- [Example code](https://github.com/open-telemetry/opentelemetry-java/tree/main/examples) - -## opentelemetry-java-instrumentation - -| Traces | Metrics | Logs | -| ------ | ------- | ------------ | -| Beta | Alpha | Experimental | - -### Releases - -> Published releases are *NOT* available on maven central, but will be by GA. - - - [releases](https://github.com/open-telemetry/opentelemetry-java-instrumentation/releases) - - [bintray](https://bintray.com/open-telemetry/maven/opentelemetry-java-instrumentation) - -> Snapshots are also available as documented -> [here](https://github.com/open-telemetry/opentelemetry-java/blob/main/CONTRIBUTING.md#snapshots). ### Additional Information - [Javadoc](https://www.javadoc.io/doc/io.opentelemetry) - [Example code](https://github.com/open-telemetry/opentelemetry-java/tree/main/examples) - -## opentelemetry-java-contrib - -| Component | Status | -| ----------------- | ------ | -| JMX Metric Gather | Alpha | - -### Releases - - - [releases](https://github.com/open-telemetry/opentelemetry-java-contrib/releases) diff --git a/website_docs/automatic_instrumentation.md b/website_docs/automatic_instrumentation.md deleted file mode 100644 index 58f8df04eaf..00000000000 --- a/website_docs/automatic_instrumentation.md +++ /dev/null @@ -1,391 +0,0 @@ ---- -title: "Automatic Instrumentation" -weight: 3 ---- - -**Note**: As of 3/29 this is a copy of the documentation live on opentelemetry.io, and requires updates to become current with the current Java release. - -## Supported Libraries and Frameworks - -| Library/Framework | Versions | -|---------------------------------------------------------------------------------------------------------------------------------------|--------------------------------| -| [Akka HTTP](https://doc.akka.io/docs/akka-http/current/index.html) | 10.0+ | -| [Apache HttpAsyncClient](https://hc.apache.org/index.html) | 4.0+ | -| [Apache HttpClient](https://hc.apache.org/index.html) | 2.0+ | -| [Armeria](https://armeria.dev) | 0.99.8+ | -| [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, see below) | -| [Grizzly Client](https://github.com/javaee/grizzly-ahc) | 1.9+ | -| [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+ | -| [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+ | -| [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+ | -| [Jetty](https://www.eclipse.org/jetty/) | 8.0+ | -| [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+ | -| [MongoDB Drivers](https://mongodb.github.io/mongo-java-driver/) | 3.3+ | -| [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+ | -| [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+ | -| [Spark Web Framework](https://github.com/perwendel/spark) | 2.3+ | -| [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+ | -| [Spymemcached](https://github.com/couchbase/spymemcached) | 2.12+ | -| [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+ | - -### 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 `java.sql.DataSource#getConnection` method is called. -- `servlet-filter` which creates spans around Servlet Filter methods. -- `servlet-service` which creates spans around Servlet methods. - -To enable them, add `otel.integration..enabled` system property: -`-Dotel.integration.jdbc-datasource.enabled=true` - -### Grizzly Instrumentation - -Whenever 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 add the following system property: -`-Dotel.integration.grizzly.enabled=true` - -### Suppressing Instrumentation - -#### Specific Libraries - -You can suppress auto-instrumentation of specific libraries by using -`-Dotel.integration.[id].enabled=false` where `id` is the instrumentation `id`. - -#### Specific Classes - -You can also exclude specific classes from being instrumented. This can be -useful for a few reasons including: - -- To completely silence spans from a given class/package. -- As a quick workaround for an instrumentation bug, when byte code in one specific class is problematic. - -> This option should not be used lightly, as it can leave some instrumentation -> partially applied, which could have unknown side-effects. - -| System property | Environment variable | Purpose | -|-----------------------|-----------------------|---------------------------------------------------------------------------------------------------| -| otel.trace.classes.exclude | OTEL_TRACE_CLASSES_EXCLUDE | Suppresses all instrumentation for specific classes, format is "my.package.MyClass,my.package2.\*" | - -### Logger MDC auto-instrumentation - -The agent injects several pieces of information about the current span into -each logging event's MDC copy. As a result any services or tools that parse the -application logs can correlate traces/spans with log statements. - -- `traceId` (same as `Span.current().getSpanContext().getTraceIdAsHexString()`) -- `spanId` (same as `Span.current().getSpanContext().getSpanIdAsHexString()`) -- `sampled` (same as `Span.current().getSpanContext().isSampled()`) - -This information can be included in log statements produced by the logging library -by specifying them in the pattern/format. - -Example for Spring Boot configuration (which uses logback): - -```properties -logging.pattern.console = %d{yyyy-MM-dd HH:mm:ss} - %logger{36} - %msg trace_id=%X{trace_id} span_id=%X{span_id} trace_flags=%X{trace_flags} %n -``` - -#### Supported logging libraries - -| Library | Version | -|---------|---------| -| Log4j 1 | 1.2+ | -| Log4j 2 | 2.7+ | -| Logback | 1.0+ | - -## Configuration Options - -> Configuration parameters names are very likely to change until GA. - -### Exporters - -The following configuration properties are common to all exporters: - -| System property | Environment variable | Purpose | -|-----------------|----------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------| -| otel.exporter | OTEL_EXPORTER | Exporter to be used, can be a comma-separated list to use multiple exporters. Currently does not support multiple metric exporters. Defaults to `otlp`. | - -#### OTLP exporter (both span and metric exporters) - -> In order to configure the service name for the OTLP exporter, you must add -`service.name` key to the OpenTelemetry Resource ([see -below](#opentelemetry-resource)). For example: -`OTEL_RESOURCE_ATTRIBUTES=service.name=myservice`. - -| System property | Environment variable | Purpose | -|------------------------------|-----------------------------|-----------------------------------------------------------------------| -| otel.exporter=otlp (default) | OTEL_EXPORTER=otlp | To select OpenTelemetry exporter (default) | -| otel.exporter.otlp.endpoint | OTEL_EXPORTER_OTLP_ENDPOINT | The OTLP endpoint to connect to, default is "localhost:55680" | -| otel.exporter.otlp.insecure | OTEL_EXPORTER_OTLP_INSECURE | Whether to enable client transport security for the connection | -| otel.exporter.otlp.headers | OTEL_EXPORTER_OTLP_HEADERS | The key-value pairs separated by semicolon to pass as request headers | -| otel.exporter.otlp.timeout | OTEL_EXPORTER_OTLP_TIMEOUT | The max waiting time allowed to send each batch, default is 1000 | - -#### Jaeger exporter - -> Currently only supports gRPC. - -| System property | Environment variable | Purpose | -|-----------------------------------|-----------------------------------|----------------------------------------------------------------------------------------------------| -| otel.exporter=jaeger | OTEL_EXPORTER=jaeger | To select Jaeger exporter | -| otel.exporter.jaeger.endpoint | OTEL_EXPORTER_JAEGER_ENDPOINT | The Jaeger endpoint to connect to, default is "localhost:14250", currently only gRPC is supported. | -| otel.exporter.jaeger.service.name | OTEL_EXPORTER_JAEGER_SERVICE_NAME | The service name of this JVM instance, default is "unknown". | - -#### Zipkin exporter - -| System property | Environment variable | Purpose | -|-----------------------------------|-----------------------------------|-----------------------------------------------------------------------------------------------------------------------| -| otel.exporter=zipkin | OTEL_EXPORTER=zipkin | To select 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. | -| otel.exporter.zipkin.service.name | OTEL_EXPORTER_ZIPKIN_SERVICE_NAME | The service name of this JVM instance, default is "unknown". | - -#### Prometheus exporter - -| System property | Environment variable | Purpose | -|-------------------------------|-------------------------------|------------------------------------------------------------------------------------| -| otel.exporter=prometheus | OTEL_EXPORTER=prometheus | To select Prometheus exporter | -| otel.exporter.prometheus.port | OTEL_EXPORTER_PROMETHEUS_PORT | The local port used to bind the prometheus metric server, defaults to 9464 | -| otel.exporter.prometheus.host | OTEL_EXPORTER_PROMETHEUS_HOST | The local address used to bind the prometheus metric server, defaults to "0.0.0.0" | - -#### Logging exporter - -> The logging exporter simply prints the name of the span along with its -attributes to stdout. It is used mainly for testing and debugging. - -| System property | Environment variable | Purpose | -|------------------------------|------------------------------|------------------------------------------------------------------------------| -| otel.exporter=logging | OTEL_EXPORTER=logging | To select logging exporter | -| otel.exporter.logging.prefix | OTEL_EXPORTER_LOGGING_PREFIX | An optional string that is printed in front of the span name and attributes. | - -### Propagator - -The propagator controls which distributed tracing header format is used. - -If this is set to a comma-delimited list of the values, the multi-propagator -will be used. The multi-propagator will try to extract the context from -incoming requests using each of the configured propagator formats (in order), -stopping after the first successful context extraction. The multi-propagator -will inject the context into outgoing requests using all the configured -propagator formats. - -| System property | Environment variable | Purpose | -|------------------|----------------------|-------------------------------------------------------------------------------------------------------------| -| otel.propagators | OTEL_PROPAGATORS | Default is "tracecontext" (W3C). Other supported values are "b3", "b3single", "jaeger", "ottracer", "xray". | - -### OpenTelemetry Resource - -The [OpenTelemetry -Resource](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/resource/sdk.md) -is a representation of the entity producing telemetry. - -| System property | Environment variable | Purpose | -|--------------------------|--------------------------|------------------------------------------------------------------------------| -| otel.resource.attributes | OTEL_RESOURCE_ATTRIBUTES | Used to specify resource attributes in format: key1=val1,key2=val2,key3=val3 | - -### Peer service name - -The [peer service -name](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/trace/semantic_conventions/span-general.md#general-remote-service-attributes) -is the name of a remote service that is being connected to. It corresponds to -`service.name` in the -[Resource](https://github.com/open-telemetry/opentelemetry-specification/tree/main/specification/resource/semantic_conventions#service) -for the local service. - -| System property | Environment variable | Purpose | -|------------------------------------|------------------------------------|------------------------------------------------------------------------------| -| 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 name will be 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 one of `dogs-api` | - -### Batch span processor - -| System property | Environment variable | Purpose | -|---------------------------|---------------------------|------------------------------------------------------------------------------| -| otel.bsp.schedule.delay | OTEL_BSP_SCHEDULE_DELAY | The interval in milliseconds between two consecutive exports (default: 5000) | -| otel.bsp.max.queue | OTEL_BSP_MAX_QUEUE | Maximum queue size (default: 2048) | -| otel.bsp.max.export.batch | OTEL_BSP_MAX_EXPORT_BATCH | Maximum batch size (default: 512) | -| otel.bsp.export.timeout | OTEL_BSP_EXPORT_TIMEOUT | Maximum allowed time in milliseconds to export data (default: 30000) | -| otel.bsp.export.sampled | OTEL_BSP_EXPORT_SAMPLED | Whether only sampled spans should be exported (default: true) | - -### Trace config - -| System property | Environment variable | Purpose | -|---------------------------------|---------------------------------|------------------------------------------------------| -| otel.config.sampler.probability | OTEL_CONFIG_SAMPLER_PROBABILITY | Sampling probability between 0 and 1 (default: 1) | -| otel.config.max.attrs | OTEL_CONFIG_MAX_ATTRS | Maximum number of attributes per span (default: 32) | -| otel.config.max.events | OTEL_CONFIG_MAX_EVENTS | Maximum number of events per span (default: 128) | -| otel.config.max.links | OTEL_CONFIG_MAX_LINKS | Maximum number of links per span (default: 32) | -| otel.config.max.event.attrs | OTEL_CONFIG_MAX_EVENT_ATTRS | Maximum number of attributes per event (default: 32) | -| otel.config.max.link.attrs | OTEL_CONFIG_MAX_LINK_ATTRS | Maximum number of attributes per link (default: 32) | - -### Interval metric reader - -| System property | Environment variable | Purpose | -|--------------------------|--------------------------|------------------------------------------------------------------------------| -| otel.imr.export.interval | OTEL_IMR_EXPORT_INTERVAL | The interval in milliseconds between pushes to the exporter (default: 60000) | - -#### Customizing the OpenTelemetry SDK - -> This is highly advanced behavior and still in the prototyping phase. It may -change drastically or be removed completely. Use with caution - -The OpenTelemetry API exposes SPI -[hooks](https://github.com/open-telemetry/opentelemetry-java/blob/main/api/src/main/java/io/opentelemetry/trace/spi/TracerProviderFactory.java) -for customizing its behavior, such as the `Resource` attached to spans or the -`Sampler`. - -Because the auto instrumentation runs in a separate 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 will need 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 will have to specify the -`io.opentelemetry.javaagent.shaded.io.opentelemetry.api.trace.spi.TraceProvider` -to the name of the class that implements the SPI. - -## Manual Instrumentation - -> Starting with 0.6.0, and 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`. - -With auto-instrumentation it may be desirable to also add manual -instrumentation. In this scenario, it is critical that both automatic and -manual instrumentation stitch together properly. Two options exist to configure -manual instrumentation with the appropriate span context: - -- `@WithSpan` annotation: Simply annotate the functions or methods you wish to instrument -- `getTracer`: Traditional way to instrument with OpenTelemetry - -Both options require a dependency on the `opentelemetry-api` library to get started. - -### Dependency - -#### Maven - -```xml - - - io.opentelemetry - opentelemetry-api - 0.10.0 - - -``` - -#### Gradle - -```groovy -dependencies { - compile('io.opentelemetry:opentelemetry-api:0.10.0') -} -``` - -### Configure `@WithSpan` annotation - -Add the trace annotation to your application's code. Then, each time the -application invokes the annotated method, it creates a span that denotes its -duration and provides any thrown exceptions. - -```java -import io.opentelemetry.extensions.auto.annotations.WithSpan; - -public class MyClass { - @WithSpan - public void MyLogic() { - <...> - } -} -``` - -#### Dependency - -An additional dependency is required for this annotation: - -##### Maven - -```xml - - - io.opentelemetry - opentelemetry-extension-auto-annotations - 0.10.0 - - -``` - -##### Groovy - -```groovy -dependencies { - compile('io.opentelemetry:opentelemetry-extension-auto-annotations:0.10.0') -} -``` - -#### Suppressing `@WithSpan` instrumentation - -This is useful in case 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 | -|---------------------------------|---------------------------------|------------------------------------------------------------------------------------------------------------------------------------------| -| trace.annotated.methods.exclude | TRACE_ANNOTATED_METHODS_EXCLUDE | Suppress `@WithSpan` instrumentation for specific methods, format is "my.package.MyClass1[method1,method2];my.package.MyClass2[method3]" | - -### Configure the OpenTelemetry getTracer - -See the [Manual Instrumentation documentation](/docs/java/manual_instrumentation/#instantiate-tracer) -for configuration information and examples. - -## Troubleshooting - -To turn on the agent's internal debug logging: - -`-Dio.opentelemetry.javaagent.slf4j.simpleLogger.defaultLogLevel=debug` - -> Note these logs are extremely verbose. Enable debug logging only when needed. -Debug logging negatively impacts the performance of your application. diff --git a/website_docs/getting_started.md b/website_docs/getting_started.md deleted file mode 100644 index 27706e52bc6..00000000000 --- a/website_docs/getting_started.md +++ /dev/null @@ -1,58 +0,0 @@ ---- -title: "Getting Started" -weight: 2 ---- - -**Note**: As of 3/29 this is a copy of the documentation live on opentelemetry.io, and requires updates to become current with the current Java release. - -## Automatic Instrumentation - -> Automatic instrumentation is applicable to trace data only today. - -Download the [latest version](/docs/java/#releases-1). This package includes -the instrumentation agent, instrumentations for all supported libraries and all -available data exporters. - -The instrumentation agent is enabled by passing the `-javaagent` flag to the JVM. - -```java -java -javaagent:path/to/opentelemetry-javaagent-all.jar \ - -jar myapp.jar -``` - -By default OpenTelemetry Java agent uses the [OTLP -exporter](https://github.com/open-telemetry/opentelemetry-java/tree/main/exporters/otlp) -configured to send data to a local [OpenTelemetry -Collector](https://github.com/open-telemetry/opentelemetry-collector/blob/main/receiver/otlpreceiver/README.md) -at `localhost:55680`. - -Configuration parameters are passed as Java system properties (`-D` flags) or as -environment variables. For example: - -```java -java -javaagent:path/to/opentelemetry-javaagent-all.jar \ - -Dotel.exporter=zipkin \ - -jar myapp.jar -``` - -An exporter jar can be specified via the `otel.exporter.jar` system property: - -```java -java -javaagent:path/to/opentelemetry-javaagent-all.jar \ - -Dotel.exporter.jar=path/to/external-exporter.jar \ - -jar myapp.jar -``` - -For additional information, see the [Automatic Instrumentation documentation](/docs/java/automatic_instrumentation). - -## Manual Instrumentation - -Please see the [QuickStart Guide](https://github.com/open-telemetry/opentelemetry-java/blob/v1.0.0/QUICKSTART.md). - -#### Example - -Several -[examples](https://github.com/open-telemetry/opentelemetry-java/tree/main/examples) -are provided to get started. The [metrics -examples](https://github.com/open-telemetry/opentelemetry-java/tree/main/examples/metrics) -demonstrates how to generate other types of metrics. diff --git a/website_docs/instrumentation_examples.md b/website_docs/instrumentation_examples.md index 6961f07401e..994a39186b2 100644 --- a/website_docs/instrumentation_examples.md +++ b/website_docs/instrumentation_examples.md @@ -3,8 +3,6 @@ title: "Instrumentation Examples" weight: 4 --- -**Note**: As of 3/29 this is a copy of the documentation live on opentelemetry.io, and requires updates to become current with the current Java release. - Here are Some of the resources for Opentelemetry Instrumentation Examples ## Community Resources diff --git a/website_docs/manual_instrumentation.md b/website_docs/manual_instrumentation.md index f8c91a4bc58..e206ca0d1d2 100644 --- a/website_docs/manual_instrumentation.md +++ b/website_docs/manual_instrumentation.md @@ -3,17 +3,42 @@ Title: "Manual Instrumentation" Weight: 3 --- -**Note**: As of 3/29 this is a copy of the documentation live on opentelemetry.io, and requires updates to become current with the current Java release. - -## Traces - -### Instantiate `TracerProvider` and SDK - -In the [OpenTelemetry Tracing -API](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/trace/api.md), -the `TracerProvider` is the main entry point and is expected to be the stateful -object that holds any configuration. The `TracerProvider` provides access -to the [`Tracer`](#instantiate-tracer). + + + +- [Set up](#set-up) +- [Tracing](#tracing) + * [Create basic Span](#create-a-basic-span) + * [Create nested Spans](#create-nested-spans) + * [Span Attributes](#span-attributes) + * [Create Spans with events](#create-spans-with-events) + * [Create Spans with links](#create-spans-with-links) + * [Context Propagation](#context-propagation) +- [Metrics](#metrics-alpha-only) +- [Tracing SDK Configuration](#tracing-sdk-configuration) + * [Sampler](#sampler) + * [Span Processor](#span-processor) + * [Exporter](#exporter) +- [Auto Configuration](#auto-configuration) +- [Logging And Error Handling](#logging-and-error-handling) + * [Examples](#examples) + + +**Libraries** that want to export telemetry data using OpenTelemetry MUST only depend on the +`opentelemetry-api` package and should never configure or depend on the OpenTelemetry SDK. The SDK +configuration must be provided by **Applications** which should also depend on the +`opentelemetry-sdk` package, or any other implementation of the OpenTelemetry API. This way, +libraries will obtain a real implementation only if the user application is configured for it. For +more details, check out the [Library Guidelines]. + +## Set up + +The first step is to get a handle to an instance of the `OpenTelemetry` 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. + +For example: ```java SdkTracerProvider sdkTracerProvider = SdkTracerProvider.builder() @@ -26,29 +51,33 @@ to the [`Tracer`](#instantiate-tracer). .buildAndRegisterGlobal(); ``` -### Instantiate `Tracer` +As an aside, if you are writing library instrumentation, it is strongly recommended that you provide your users +the ability to inject an instance of `OpenTelemetry` into your instrumentation code. If this is +not possible for some 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 -In order to instrument, you must acquire a `Tracer`. A `Tracer` is responsible for -creating spans. To acquire a `Tracer` use the [OpenTelemetry Tracing -API](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/trace/api.md) -and specify the name and version of the [library -instrumenting](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/glossary.md#instrumentation-library) -the [instrumented -library](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/glossary.md#instrumented-library) -or application to be monitored. +In the following, we present how to trace code using the OpenTelemetry API. **Note:** Methods of the +OpenTelemetry SDK should never be called. + +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 application to be +monitored. More information is available in the specification chapter [Obtaining a Tracer]. ```java Tracer tracer = - openTelemetry.getTracer("instrumentation-library-name","1.0.0"); + openTelemetry.getTracer("instrumentation-library-name", "1.0.0"); ``` -### Create Spans - -#### Basic - -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. +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 +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. ```java Span span = tracer.spanBuilder("my span").startSpan(); // put the span into the current Context @@ -62,16 +91,13 @@ try (Scope scope = span.makeCurrent()) { } ``` -#### Nested +### 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 information about how to share context between remote processes, see [Context -Propagation](#context-propagation). - -For a method `parentOne` calling a method `childOne`, the spans could be manually linked in the -following way: +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). +For a method `a` calling a method `b`, the spans could be manually linked in the following way: ```java void parentOne() { Span parentSpan = tracer.spanBuilder("parent").startSpan(); @@ -90,9 +116,7 @@ void childOne(Span parentSpan) { childSpan.end(); } ``` - -The OpenTelemetry API also offers an automated way to propagate the parentSpan: - +The OpenTelemetry API offers also an automated way to propagate the parent span on the current thread: ```java void parentTwo() { Span parentSpan = tracer.spanBuilder("parent").startSpan(); @@ -113,23 +137,19 @@ void childTwo() { childSpan.end(); } } -``` +``` -To link spans from remote processes, it is sufficient to set the [Remote -Context](#context-propagation) as parent. +To link spans from remote processes, it is sufficient to set the +[Remote Context](#context-propagation) as parent. ```java Span childRemoteParent = tracer.spanBuilder("Child").setParent(remoteContext).startSpan(); ``` -### Enrich Spans - -#### Attributes - -In OpenTelemetry, you can create spans freely. It's up to the implementor to -annotate spans 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. +### 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. ```java Span span = tracer.spanBuilder("/resource/path").setSpanKind(SpanKind.CLIENT).startSpan(); @@ -137,17 +157,15 @@ span.setAttribute("http.method", "GET"); span.setAttribute("http.url", url.toString()); ``` -Some of these operations represent calls that use well-known protocols like -HTTP or database calls. For these operations, OpenTelemetry requires specific attributes -to be set. The full attribute list is available in the Semantic Conventions in -the cross-language specification. And, the standard attribute keys are available in the -`io.opentelemetry.api.trace.attributes.SemanticAttributes` class as constants. +Some of these operations represent calls that use well-known protocols like HTTP or database calls. +For these, OpenTelemetry requires specific attributes to be set. The full attribute list is +available in the [Semantic Conventions](https://github.com/open-telemetry/opentelemetry-specification/blob/master/specification/trace/semantic_conventions/README.md) in the cross-language specification. -#### Events +### Create Spans with events -Spans can be annotated with named events that can carry zero or more [Span -Attributes](#attributes), each of which is itself a name/value map paired -automatically with a timestamp. +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. ```java span.addEvent("Init"); @@ -163,12 +181,10 @@ Attributes eventAttributes = Attributes.of( span.addEvent("End Computation", eventAttributes); ``` -#### Links - -You can link a span to zero or more other spans that are causally related. -Use links to represent batched operations where a span was initiated by -multiple initiating spans, each representing a single incoming item being -processed in the batch. +### 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. ```java Span child = tracer.spanBuilder("childWithLink") @@ -179,17 +195,15 @@ Span child = tracer.spanBuilder("childWithLink") .startSpan(); ``` -For more information about how to read context from remote processes, see [Context -Propagation](#context-propagation). +For more details how to read context from remote processes, see +[Context Propagation](#context-propagation). ### Context Propagation -OpenTelemetry provides a text-based approach to propagate context to remote -services. By default, the [W3C Trace Context](https://www.w3.org/TR/trace-context/) -format is used. +OpenTelemetry provides a text-based approach to propagate context to remote services using the +[W3C Trace Context](https://www.w3.org/TR/trace-context/) HTTP headers. -The following example shows an outgoing HTTP request using -`HttpURLConnection`: +The following presents an example of an outgoing HTTP request using `HttpURLConnection`. ```java // Tell OpenTelemetry to inject the context in the HTTP headers @@ -205,7 +219,7 @@ TextMapSetter setter = URL url = new URL("http://127.0.0.1:8080/resource"); Span outGoing = tracer.spanBuilder("/resource").setSpanKind(SpanKind.CLIENT).startSpan(); try (Scope scope = outGoing.makeCurrent()) { - // Semantic Convention. + // Use the Semantic Conventions. // (Note that to set these, Span does not *need* to be the current instance in Context or Scope.) outGoing.setAttribute(SemanticAttributes.HTTP_METHOD, "GET"); outGoing.setAttribute(SemanticAttributes.HTTP_URL, url.toString()); @@ -219,10 +233,9 @@ try (Scope scope = outGoing.makeCurrent()) { ... ``` -Similarly, you can use the text-based approach to read the W3C Trace Context -from incoming requests. The following example demonstrates processing an -incoming HTTP request using -[HttpExchange](https://docs.oracle.com/javase/8/docs/jre/api/net/httpserver/spec/com/sun/net/httpserver/HttpExchange.html): +Similarly, the text-based approach can be used to read the W3C Trace Context from incoming requests. +The following presents an example of processing an incoming HTTP request using +[HttpExchange](https://docs.oracle.com/javase/8/docs/jre/api/net/httpserver/spec/com/sun/net/httpserver/HttpExchange.html). ```java TextMapGetter getter = @@ -265,90 +278,22 @@ public void handle(HttpExchange httpExchange) { } ``` -Other propagators are available as extensions, most notably -[Zipkin -B3](https://github.com/open-telemetry/opentelemetry-java/tree/main/extensions/trace-propagators/src/main/java/io/opentelemetry/extension/trace/propagation). - -### Configuring the default OpenTelemetry SDK - -In order to configure the SDK, options can be passed to the builder method of `SdkTracerProvider`. The following demonstrates a SDK that writes traces through a logger. - -```java - SdkTracerProvider tracerProvider = SdkTracerProvider.builder() - .addSpanProcessor(BatchSpanProcessor.builder(new LoggingSpanExporter()).build()) - .build(); -``` - -### Processors - -The following processors are available today: - -#### SimpleSpanProcessor - -This span processor exports spans immediately after they end. - -Example: - -```java -SimpleSpanProcessor simpleSpansProcessor = SimpleSpanProcessor.builder(exporter).build(); -tracerManagement.addSpanProcessor(simpleSpansProcessor); -``` - -#### BatchSpanProcessor - -This span processor exports spans in batches. - -Example: - -```java -BatchSpanProcessor batchSpansProcessor = - BatchSpanProcessor.builder(exporter).build(); -tracerManagement.addSpanProcessor(batchSpansProcessor); -``` - -You can also specify a variety of configuration parameters: - -```java -BatchSpanProcessor batchSpansProcessor = - BatchSpanProcessor.builder(exporter) - .setExportOnlySampled(true) // send only sampled spans to the exporter - .setMaxExportBatchSize(512) // maximum batch size to use - .setMaxQueueSize(2048) // queue size; mmust be >= the export batch size - .setExporterTimeoutMillis( - 30_000) // max amount of time an export can run before getting interrupted - .setScheduleDelayMillis(5000) // set time between two different exports - .build(); -tracerManagement.addSpanProcessor(batchSpansProcessor); -``` - -#### MultiSpanProcessor +## Metrics (alpha only!) -A MultiSpanProcessor accepts a list of span processors. - -Example: - -```java -SpanProcessor multiSpanProcessor = - MultiSpanProcessor.create(Arrays.asList(simpleSpansProcessor, batchSpansProcessor)); -tracerManagement.addSpanProcessor(multiSpanProcessor); -``` - -### Exporters - -*TODO* - -### Sampling - -*TODO* +Spans are a great way to get detailed information about what your application is doing, but +what about a more aggregated perspective? OpenTelemetry provides supports for metrics, a time series +of numbers that might express things such as CPU utilization, request count for an HTTP server, or a +business metric such as transactions. -## Metrics +In order to access the alpha metrics library, you will need to explicitly depend on the `opentelemetry-api-metrics` +and `opentelemetry-sdk-metrics` modules, which are not included in the opentelemetry-bom until they are +stable and ready for long-term-support. -OpenTelemetry provides support for metrics, a time series of numbers that might -express things such as CPU utilization, request count for an HTTP server, or a -business metric such as transactions. +All metrics can be annotated with labels: additional qualifiers that help describe what +subdivision of the measurements the metric represents. -All metrics can be annotated with labels. Labels are additional qualifiers that help -describe what subdivision of the measurements the metric represents. +First, you'll need to get access to a `MeterProvider`. Note the APIs for this are in flux, so no +example code is provided here for that. The following is an example of counter usage: @@ -391,3 +336,166 @@ The following is an example of observer usage: }) .build(); ``` + +## Tracing SDK Configuration + +The configuration examples reported in this document only apply to the SDK provided by +`opentelemetry-sdk`. Other implementation of the API might provide different configuration +mechanisms. + +The application has to install a span processor with an exporter and may customize the behavior of +the OpenTelemetry SDK. + +For example, a basic configuration instantiates the SDK tracer provider and sets to export the +traces to a logging stream. + +```java + SdkTracerProvider tracerProvider = SdkTracerProvider.builder() + .addSpanProcessor(BatchSpanProcessor.builder(new LoggingSpanExporter()).build()) + .build(); +``` + +### Sampler + +It is not always feasible to trace and export every user request in an application. +In order to strike a balance between observability and expenses, 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. +- [TraceIdRatioBased] which samples a configurable percentage of traces, and additionally samples any + trace that was sampled upstream. + +Additional samplers can be provided by implementing the `io.opentelemetry.sdk.trace.Sampler` +interface. + +```java + SdkTracerProvider tracerProvider = SdkTracerProvider.builder() + .setSampler(Sampler.alwaysOn()) + //or + .setSampler(Sampler.alwaysOff()) + //or + .setSampler(Sampler.traceIdRatioBased(0.5)) + .build(); +``` + +### Span Processor + +Different Span processors are offered by OpenTelemetry. The `SimpleSpanProcessor` immediately +forwards ended spans to the exporter, while the `BatchSpanProcessor` batches them and sends them +in bulk. Multiple Span processors can be configured to be active at the same time using the +`MultiSpanProcessor`. + +```java + SdkTracerProvider tracerProvider = SdkTracerProvider.builder() + .addSpanProcessor(SimpleSpanProcessor.create(new LoggingSpanExporter())) + .addSpanProcessor(BatchSpanProcessor.builder(new LoggingSpanExporter()).build()) + .build(); +``` + +### Exporter + +Span processors are initialized with an exporter which is responsible for sending the telemetry data +a particular backend. OpenTelemetry offers five exporters out of the box: +- In-Memory Exporter: keeps the data in memory, useful for debugging. +- Jaeger Exporter: prepares and sends the collected telemetry data to a Jaeger backend via gRPC. +- Zipkin Exporter: prepares and sends the collected telemetry data to a Zipkin backend via the Zipkin APIs. +- Logging Exporter: saves the telemetry data into log streams. +- OpenTelemetry Exporter: sends the data to the [OpenTelemetry Collector]. + +Other exporters can be found in the [OpenTelemetry Registry]. + +```java + ManagedChannel jaegerChannel = ManagedChannelBuilder.forAddress("localhost", 3336) + .usePlaintext() + .build(); + + JaegerGrpcSpanExporter jaegerExporter = JaegerGrpcSpanExporter.builder() + .setEndpoint("localhost:3336") + .setTimeout(30, TimeUnit.SECONDS) + .build(); + + SdkTracerProvider tracerProvider = SdkTracerProvider.builder() + .addSpanProcessor(BatchSpanProcessor.builder(jaegerExporter).build()) + .build(); +``` + +### Auto Configuration + +To configure the OpenTelemetry SDK based on the standard set of environment variables and system +properties, you can use the `opentelemetry-sdk-extension-autoconfigure` module. + +```java + OpenTelemetrySdk sdk = OpenTelemetrySdkAutoConfiguration.initialize(); +``` + +See the supported configuration options in the module's [README](https://github.com/open-telemetry/opentelemetry-java/tree/main/sdk-extensions/autoconfigure). + +[AlwaysOnSampler]: https://github.com/open-telemetry/opentelemetry-java/blob/main/sdk/tracing/src/main/java/io/opentelemetry/sdk/trace/samplers/Sampler.java#L29 +[AlwaysOffSampler]:https://github.com/open-telemetry/opentelemetry-java/blob/main/sdk/tracing/src/main/java/io/opentelemetry/sdk/trace/samplers/Sampler.java#L40 +[ParentBased]:https://github.com/open-telemetry/opentelemetry-java/blob/main/sdk/tracing/src/main/java/io/opentelemetry/sdk/trace/samplers/Sampler.java#L54 +[TraceIdRatioBased]:https://github.com/open-telemetry/opentelemetry-java/blob/main/sdk/tracing/src/main/java/io/opentelemetry/sdk/trace/samplers/Sampler.java#L78 +[Library Guidelines]: https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/library-guidelines.md +[OpenTelemetry Collector]: https://github.com/open-telemetry/opentelemetry-collector +[OpenTelemetry Registry]: https://opentelemetry.io/registry/?s=exporter +[OpenTelemetry Website]: https://opentelemetry.io/ +[Obtaining a Tracer]: https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/trace/api.md#get-a-tracer +[Semantic Conventions]: https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/trace/semantic_conventions +[Instrumentation Library]: https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/glossary.md#instrumentation-library +[instrumented library]: https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/glossary.md#instrumented-library + +## Logging and Error Handling + +OpenTelemetry uses [java.util.logging](https://docs.oracle.com/javase/7/docs/api/java/util/logging/package-summary.html) +to log information about OpenTelemetry, including errors and warnings about misconfigurations or failures exporting +data. + +By default, log messages are handled by the root handler in your application. If you have not +installed a custom root handler for your application, logs of level `INFO` or higher are sent to the console by default. + +You may +want to change the behavior of the logger for OpenTelemetry. For example, you can reduce the logging level +to output additional information when debugging, increase the level for a particular class to ignore errors coming +from that class, or install a custom handler or filter to run custom code whenever OpenTelemetry logs +a particular message. + +### Examples + +```properties +## Turn off all OpenTelemetry logging +io.opentelemetry.level = OFF +``` + +```properties +## Turn off logging for just the BatchSpanProcessor +io.opentelemetry.sdk.trace.export.BatchSpanProcessor.level = OFF +``` + +```properties +## Log "FINE" messages for help in debugging +io.opentelemetry.level = FINE + +## Sets the default ConsoleHandler's logger's level +## Note this impacts the logging outside of OpenTelemetry as well +java.util.logging.ConsoleHandler.level = FINE + +``` + +For more fine-grained control and special case handling, custom handlers and filters can be specified +with code. + +```java +// Custom filter which does not log errors that come from the export +public class IgnoreExportErrorsFilter implements Filter { + + public boolean isLoggable(LogRecord record) { + return !record.getMessage().contains("Exception thrown by the export"); + } +} +``` + +```properties +## Registering the custom filter on the BatchSpanProcessor +io.opentelemetry.sdk.trace.export.BatchSpanProcessor = io.opentelemetry.extension.logging.IgnoreExportErrorsFilter +```