Merge pull request #371 from aws-otel/raphasil-update-java-metrics

* Fix minor inconsistencies in the documentation.
* Add examples for Manually adding metrics to an application.
* Reference existing SparkJava sample app that makes use of Traces and metrics.

Author: rapphil

src/docs/getting-started/java-sdk.mdx

@@ -17,8 +17,8 @@ backend.
 
 ## Getting Started
 
-* [Auto-Instrumentation for Traces with the Java agent](/docs/getting-started/java-sdk/trace-auto-instr)
-* [Manual Instrumentation for Traces with the Java SDK](/docs/getting-started/java-sdk/trace-manual-instr)
+* [Auto-Instrumentation for Traces and Metrics with the Java agent](/docs/getting-started/java-sdk/trace-auto-instr)
+* [Manual Instrumentation for Traces and Metrics with the Java SDK](/docs/getting-started/java-sdk/trace-manual-instr)
 
 ## Sample Code
 * [Sample Spring App using OpenTelemetry Java Auto-Instrumentation](https://catalog.us-east-1.prod.workshops.aws/v2/workshops/31676d37-bbe9-4992-9cd1-ceae13c5116c/en-US/adot/javawalkthrough)

src/docs/getting-started/java-sdk/trace-auto-instr.mdx

@@ -1,9 +1,9 @@
 ---
-title: 'Tracing with the AWS Distro for OpenTelemetry Java Auto-Instrumentation and X-Ray'
+title: 'Auto-Instrumentation for Traces and Metrics with the Java agent'
 description:
-    Learn how to get started with Java Auto-Instrumentation Agent... This package includes the instrumentation agent,
+    Learn how to get started with Java Auto-Instrumentation Agent. This package includes the instrumentation agent,
     instrumentations for all supported libraries and all available data exporters, providing a complete out of the box
-    experience for tracing on AWS. The agent is preconfigured to generate trace IDs compatible with AWS X-Ray, which
+    experience for tracing and metrics on AWS. The agent is preconfigured to generate trace IDs compatible with AWS X-Ray, which
     will also work with any other tracing system, and enables trace propagation using W3C Trace Context, B3, and X-Ray.
 path: '/docs/getting-started/java-sdk/trace-auto-instr'
 ---
@@ -50,12 +50,15 @@ automatically. For many cases, this is all you need to use tracing.
 
 By default OpenTelemetry Java agent uses the [OTLP exporter](https://github.com/open-telemetry/opentelemetry-java/tree/master/exporters/otlp)
 and is configured to send data to a [OpenTelemetry collector](https://github.com/open-telemetry/opentelemetry-collector/blob/master/receiver/otlpreceiver/README.md)
-at `http://localhost:4317`.
+at `http://localhost:4317` for both metrics and traces.
 
-The agent can be configured using [standard OpenTelemetry options for configuration](https://github.com/open-telemetry/opentelemetry-java-instrumentation/blob/main/docs/agent-config.md).
+The agent can be configured using [standard OpenTelemetry options for configuration](https://github.com/open-telemetry/opentelemetry-java/blob/main/sdk-extensions/autoconfigure/README.md) using either environment variables or system properties.
 For example, to set the random sampling rate for creating traces, you can set the environment variables
 `OTEL_TRACES_SAMPLER=parentbased_traceidratio` and `OTEL_TRACES_SAMPLER_ARG=0.3` to configure a sampling rate of 30%.
 
+Another useful configuration that can be used during development is to log traces and metrics. This can be achieved by
+setting `OTEL_TRACES_EXPORTER=logging` and `OTEL_METRICS_EXPORTER=logging`.
+
 ### Using X-Ray Remote Sampling
 
 The ADOT Java Auto-Instrumentation Agent can be configured to use [X-Ray remote sampling](https://docs.aws.amazon.com/xray/latest/devguide/xray-console-sampling.html)
@@ -90,7 +93,7 @@ artifact, any usage of it will be disabled by the agent.
 ##### For Gradle:
 ```kotlin lineNumbers=true
 dependencies {
-    implementation("io.opentelemetry:opentelemetry-api:1.6.0")
+    implementation("io.opentelemetry:opentelemetry-api:1.16.0")
 }
 ```
 
@@ -100,7 +103,7 @@ dependencies {
   <dependency>
     <groupId>io.opentelemetry</groupId>
     <artifactId>opentelemetry-api</artifactId>
-    <version>1.6.0</version>
+    <version>1.16.0</version>
   </dependency>
 </dependencies>
 ```
@@ -110,6 +113,7 @@ for more detail on using the OpenTelemetry API.
 
 <SectionSeparator />
 
-## Sample Application
+## Sample Applications
 
-Visit the [Sample Spring App using OpenTelemetry Java Auto-Instrumentation](https://catalog.us-east-1.prod.workshops.aws/v2/workshops/31676d37-bbe9-4992-9cd1-ceae13c5116c/en-US/adot/javawalkthrough).
+* Visit the [Sample Spring App using OpenTelemetry Java Auto-Instrumentation](https://catalog.us-east-1.prod.workshops.aws/v2/workshops/31676d37-bbe9-4992-9cd1-ceae13c5116c/en-US/adot/javawalkthrough).
+* [SparkJava Sample Application Using Traces and Metrics](https://github.com/aws-observability/aws-otel-java-instrumentation/tree/main/sample-apps/spark).

src/docs/getting-started/java-sdk/trace-manual-instr.mdx

@@ -1,5 +1,5 @@
 ---
-title: 'Tracing with the AWS Distro for OpenTelemetry Java SDK and X-Ray'
+title: 'Manual Instrumentation for Traces and Metrics with the Java SDK'
 description:
     Learn how to get started with Java SDK for adding tracing to applications and libraries.
 path: '/docs/getting-started/java-sdk/trace-manual-instr'
@@ -37,7 +37,7 @@ to align dependency versions for non-contrib components.
 ##### For Gradle:
 ```kotlin lineNumbers=true
 dependencies {
-    api(platform("io.opentelemetry:opentelemetry-bom:1.6.0"))
+    api(platform("io.opentelemetry:opentelemetry-bom:1.16.0"))
 
     implementation("io.opentelemetry:opentelemetry-api")
     implementation("io.opentelemetry:opentelemetry-exporter-otlp")
@@ -46,7 +46,7 @@ dependencies {
 
     implementation("io.opentelemetry:opentelemetry-extension-aws")
     implementation("io.opentelemetry:opentelemetry-sdk-extension-aws")
-    implementation("io.opentelemetry.contrib:opentelemetry-aws-xray:1.6.0")
+    implementation("io.opentelemetry.contrib:opentelemetry-aws-xray:1.16.0")
 }
 ```
 
@@ -57,7 +57,7 @@ dependencies {
     <dependency>
       <groupId>io.opentelemetry</groupId>
       <artifactId>opentelemetry-bom</artifactId>
-      <version>1.6.0</version>
+      <version>1.16.0</version>
       <type>pom</type>
       <scope>import</scope>
     <dependency>
@@ -87,7 +87,7 @@ dependencies {
   <dependency>
     <groupId>io.opentelemetry.contrib</groupId>
     <artifactId>opentelemetry-aws-xray</artifactId>
-    <version>1.6.0</version>
+    <version>1.16.0</version>
   </dependency>
 </dependencies>
 ```
@@ -159,6 +159,36 @@ OpenTelemetrySdk.builder()
         .buildAndRegisterGlobal();
 ```
 
+### Adding support for Metrics
+
+The API and SDK for Metrics became stable in v1.15.0 of OpenTelemetry for Java.
+The following piece of code initialize the OpenTelemetry SDK to use Metrics and Traces.
+
+```java
+MetricReader metricReader = PeriodicMetricReader.builder(
+        OtlpGrpcMetricExporter.getDefault())
+        .build();
+OpenTelemetry opentelemetry = OpenTelemetrySdk.builder()
+        // Traces configuration
+        .setPropagators(
+            ContextPropagators.create(
+                TextMapPropagator.composite(
+                    W3CTraceContextPropagator.getInstance(), AwsXrayPropagator.getInstance())))
+
+        .setTracerProvider(
+            SdkTracerProvider.builder()
+                .addSpanProcessor(
+                    BatchSpanProcessor.builder(OtlpGrpcSpanExporter.getDefault()).build())
+                .setIdGenerator(AwsXrayIdGenerator.getInstance())
+                .build()
+        // Metrics Configuration
+        .setMeterProvider(
+                SdkMeterProvider.builder()
+                        .registerMetricReader(metricReader)
+                        .build())
+        .buildAndRegisterGlobal();
+```
+
 ### Debug Logging
 
 The SDK uses `java.util.logging` to log messages at `FINE` level - logging frameworks like Logback or Log4J map this to
@@ -181,7 +211,7 @@ library instrumentation. When using this, do not include `opentelemetry-bom`.
 ##### For Gradle:
 ```kotlin lineNumbers=true
 dependencies {
-    api(platform("io.opentelemetry.instrumentation:opentelemetry-instrumentation-bom-alpha:1.6.0-alpha"))
+    api(platform("io.opentelemetry.instrumentation:opentelemetry-instrumentation-bom-alpha:1.16.0-alpha"))
 
     implementation("io.opentelemetry:opentelemetry-api")
     implementation("io.opentelemetry:opentelemetry-exporter-otlp")
@@ -200,7 +230,7 @@ dependencies {
     <dependency>
       <groupId>io.opentelemetry.instrumentation</groupId>
       <artifactId>opentelemetry-instrumentation-bom-alpha</artifactId>
-      <version>1.6.0</version>
+      <version>1.16.0-alpha</version>
       <type>pom</type>
       <scope>import</scope>
     <dependency>
@@ -234,7 +264,7 @@ The `opentelemetry-instrumentation-aws-sdk-2.2` artifact provides instrumentatio
 ##### For Gradle:
 ```java lineNumbers=true
 dependencies {
-    api(platform("io.opentelemetry.instrumentation:opentelemetry-instrumentation-bom-alpha:1.5.0-alpha"))\
+    api(platform("io.opentelemetry.instrumentation:opentelemetry-instrumentation-bom-alpha:1.16.0-alpha"))\
 
     implementation("io.opentelemetry.instrumentation:opentelemetry-aws-sdk-2.2")
 
@@ -249,7 +279,7 @@ dependencies {
     <dependency>
       <groupId>io.opentelemetry.instrumentation</groupId>
       <artifactId>opentelemetry-instrumentation-bom-alpha</artifactId>
-      <version>1.5.0</version>
+      <version>1.16.0-alpha</version>
       <type>pom</type>
       <scope>import</scope>
     <dependency>
@@ -364,3 +394,77 @@ class RequestHandler {
   }
 }
 ```
+
+### Creating Metrics
+
+Up to v1.16.0 of OpenTelemetry for Java, there are few libraries and frameworks that make use of the Metrics API.
+Similarly to Traces, you can create custom metrics in your application using the OpentTelemetry API and SDK.
+
+In the following example application we demonstrate how to use the three types of metric instruments that
+are available to record metrics: Counters, Gauges and Histograms.
+
+The theoretic application being depicted is a worker that process messages from 2 different queues.
+
+[Counters](https://opentelemetry.io/docs/reference/specification/metrics/api/#counter):
+```java
+Meter meter = opentelemetry.getMeter("consumer-application");
+
+LongCounter counter = meter.counterBuilder("messages_consumed")
+        .setDescription("Number of messages consumed")
+        .setUnit("n")
+        .build();
+
+Attributes attributes1 = Attributes.of(AttributeKey.stringKey("processing_place"), "Place1");
+Attributes attributes2 = Attributes.of(AttributeKey.stringKey("processing_place"), "Place2");
+
+// Counters can be synchronous
+counter.record(getProcessedMessagesQueue1(), attributes1);
+
+// Different attributes can be associated with the value
+counter.record(getProcessedMessagesQueue2(), attributes2);
+
+// Counters also have the asynchronous form
+LongCounter messagesDroppedCounter = meter.counterBuilder("messages_dropped")
+        .setDescription("Number of messages dropped")
+        .buildWithCallback( (consumer) -> consumer.record(getTotalMessagesDropped()));
+
+```
+
+[Gauges](https://opentelemetry.io/docs/reference/specification/metrics/api/#asynchronous-gauge):
+```java
+Meter meter = opentelemetry.getMeter("consumer-application");
+
+Attributes attributes1 = Attributes.of(AttributeKey.stringKey("queue_name"), "Queue1");
+Attributes attributes2 = Attributes.of(AttributeKey.stringKey("queue_name"), "Queue2");
+
+Gauge gauge = meter
+    .gaugeBuilder("consumer_queue_size")
+    .setDescription("The size of the queue that is being consumed")
+    .setUnit("1")
+    .ofLongs()
+    // Gauges are asynchronous
+    .buildWithCallback(
+        measurement -> {
+          measurement.record(getQueueSize1(), attributes1);
+          measurement.record(getQueueSize2(), attributes2);
+        });
+```
+
+[Histograms](https://opentelemetry.io/docs/reference/specification/metrics/api/#histogram):
+```java
+Meter meter = opentelemetry.getMeter("consumer-application");
+
+// Histograms metric data points convey a population of recorded measurements in a compressed format.
+// A histogram bundles a set of events into divided populations with an overall event count and aggregate sum for all events.
+// Histograms are useful to record measurements such as latency. With histograms we can extract the min, max and percentiles.
+LongHistogram histogram = meter.histogramBuilder("processing_time")
+      .setUnit("ms")
+      .setDescription("Amount of time it takes to process a message")
+      .ofLongs()
+      .build();
+
+histogram.record(messageProcessingTime)
+
+```
+
+There are more examples in the [OpenTelemetry Java Manual](https://opentelemetry.io/docs/instrumentation/java/manual/#metrics).