Changelog, metrics manual instrumentation docs, and 1.3.0 pre-release changes (#421)

* Changelog, metrics manual instrumentation docs, and 1.3.0 pre-release changes

* code review comments

Author: Mateusz Rzeszutek

CHANGELOG.md

@@ -8,10 +8,36 @@ and this repository adheres to [Semantic Versioning](https://semver.org/spec/v2.
 
 ## Unreleased
 
+## v1.3.0 - 2021-08-23
+
 ### General
 
 - OpenTelemetry Java SDK and OpenTelemetry Instrumentation for Java dependencies have been updated to version 1.5.0.
 
+### Enhancements
+
+- Middleware attributes (`middleware.name` and `middleware.version`) have been renamed
+  to [webengine](docs/webengine-attributes.md) attributes (`webengine.name` and `webengine.version`) to follow
+  the [OpenTelemetry specification](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/resource/semantic_conventions/webengine.md)
+  .
+- We have added instrumentations for [c3p0](https://www.mchange.com/projects/c3p0/)
+  and [Vibur DBCP](https://github.com/vibur/vibur-dbcp) connection pools. The agent now collects and exports metrics for
+  both JDBC connection pools.
+- We have also introduced instrumentations for [Tomcat connector](https://tomcat.apache.org/tomcat-8.5-doc/index.html)
+  and [WebSphere Liberty web request](https://www.ibm.com/docs/en/was-liberty/base?topic=10-threadpool-monitoring)
+  thread pools. The agent now collects and exports metrics for these application server thread pools.
+- This release introduces the Micrometer bridge instrumentation. You can now use the Micrometer API inside your
+  application to manually define custom metrics and the javaagent will export them.
+  See [the documentation](docs/metrics.md) for more details.
+- The `splunk.metrics.export.interval` configuration property will now allow specifying time units; and if no units are
+  specified then the value is treated as number of milliseconds. For example `30s` means "30 seconds" and is equivalent
+  to `30000`.
+- This release also introduces
+  the [muzzle](https://github.com/open-telemetry/opentelemetry-java-instrumentation/blob/main/docs/contributing/muzzle.md)
+  safety checks to all Splunk instrumentations. Our instrumentations now offer exactly the same level
+  of [safety](https://github.com/open-telemetry/opentelemetry-java-instrumentation/blob/main/docs/safety-mechanisms.md)
+  as the upstream OpenTelemetry instrumentations.
+
 ## v1.2.0 - 2021-07-26
 
 ### General
@@ -21,9 +47,12 @@ and this repository adheres to [Semantic Versioning](https://semver.org/spec/v2.
 ### Enhancements
 
 - We have added instrumentation for [HikariCP](https://github.com/brettwooldridge/HikariCP)
-  and [Tomcat JDBC](https://tomcat.apache.org/tomcat-8.5-doc/jdbc-pool.html) connection pools. The agent now
-  collects and exports metrics for both JDBC connection pools.
-- You can now set the service name using the `OTEL_SERVICE_NAME` environment variable and the `otel.service.name` system property. This removes the need of using `OTEL_RESOURCE_ATTRIBUTES` to set the service name.
+  and [Tomcat JDBC](https://tomcat.apache.org/tomcat-8.5-doc/jdbc-pool.html) connection pools. The agent now collects
+  and exports metrics for both JDBC connection pools.
+- You can now set the service name using the `OTEL_SERVICE_NAME` environment variable and the `otel.service.name` system
+  property (see
+  the [OpenTelemetry specification](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/sdk-environment-variables.md#general-sdk-configuration)
+  . This removes the need of using `OTEL_RESOURCE_ATTRIBUTES` to set the service name.
 
 ## v1.1.0 - 2021-06-18
 

README.md

@@ -12,15 +12,18 @@
 
 <p align="center">
   <img alt="Stable" src="https://img.shields.io/badge/status-stable-informational?style=for-the-badge">
-  <a href="https://github.com/open-telemetry/opentelemetry-java-instrumentation/releases/tag/v1.4.0">
-    <img alt="OpenTelemetry Instrumentation for Java Version" src="https://img.shields.io/badge/otel-1.4.0-blueviolet?style=for-the-badge">
+  <a href="https://github.com/open-telemetry/opentelemetry-java-instrumentation/releases/tag/v1.5.0">
+    <img alt="OpenTelemetry Instrumentation for Java Version" src="https://img.shields.io/badge/otel-1.5.0-blueviolet?style=for-the-badge">
   </a>
   <a href="https://github.com/signalfx/gdi-specification/releases/tag/v1.0.0">
     <img alt="Splunk GDI specification" src="https://img.shields.io/badge/GDI-1.0.0-blueviolet?style=for-the-badge">
   </a>
   <a href="https://github.com/signalfx/splunk-otel-java/releases">
     <img alt="GitHub release (latest SemVer)" src="https://img.shields.io/github/v/release/signalfx/splunk-otel-java?include_prereleases&style=for-the-badge">
   </a>
+  <a href="https://maven-badges.herokuapp.com/maven-central/com.splunk/splunk-otel-javaagent">
+    <img alt="Maven Central" src="https://img.shields.io/maven-central/v/com.splunk/splunk-otel-javaagent?style=for-the-badge">
+  </a>
   <a href="https://github.com/signalfx/splunk-otel-java/actions?query=workflow%3A%22CI+build%22">
     <img alt="Build Status" src="https://img.shields.io/github/workflow/status/signalfx/splunk-otel-java/CI%20build?style=for-the-badge">
   </a>
@@ -44,11 +47,6 @@
 
 <!-- Comments, spacing, empty and new lines in the section below are intentional, please do not modify them! -->
 <!--DEV_DOCS_WARNING-->
-<!--DEV_DOCS_WARNING_START-->
-The documentation below refers to the in development version of this package. Docs for the latest version ([v1.2.0](https://github.com/signalfx/splunk-otel-java/releases/tag/v1.2.0)) can be found [here](https://github.com/signalfx/splunk-otel-java/blob/v1.2.0/README.md).
-
----
-<!--DEV_DOCS_WARNING_END-->
 
 # Splunk Distribution of OpenTelemetry Java
 
@@ -154,16 +152,19 @@ The Splunk Distribution of OpenTelemetry Java provides a way to correlate traces
 
 Documentation on how to manually instrument a Java application is available in the 
 [OpenTelemetry official documentation](https://github.com/open-telemetry/opentelemetry-java-instrumentation/blob/main/docs/manual-instrumentation.md).
+To learn how to add custom metrics to your application please consult [our docs](docs/metrics.md#manual-instrumentation)
+.
 
 To extend the instrumentation with the OpenTelemetry Instrumentation for Java,
 you have to use a compatible API version.
 
 <!-- IMPORTANT: do not change comments or break those lines below -->
-The Splunk Distribution of OpenTelemetry Java version <!--SPLUNK_VERSION-->1.2.0<!--SPLUNK_VERSION--> is compatible
+The Splunk Distribution of OpenTelemetry Java version <!--SPLUNK_VERSION-->1.3.0<!--SPLUNK_VERSION--> is compatible
 with:
 
-* OpenTelemetry API version <!--OTEL_VERSION-->1.4.1<!--OTEL_VERSION-->
-* OpenTelemetry Instrumentation for Java version <!--OTEL_INSTRUMENTATION_VERSION-->1.4.0<!--OTEL_INSTRUMENTATION_VERSION-->
+* OpenTelemetry API version <!--OTEL_VERSION-->1.5.0<!--OTEL_VERSION-->
+* OpenTelemetry Instrumentation for Java version <!--OTEL_INSTRUMENTATION_VERSION-->1.5.0<!--OTEL_INSTRUMENTATION_VERSION-->
+* Micrometer version 1.7.3
 
 ## Snapshot builds
 

buildSrc/src/main/kotlin/splunk.java-conventions.gradle.kts

@@ -17,6 +17,7 @@ val otelVersion = "1.5.0"
 val otelAlphaVersion = "1.5.0-alpha"
 val otelInstrumentationVersion = "1.5.0"
 val otelInstrumentationAlphaVersion = "1.5.0-alpha"
+val micrometerVersion = "1.7.3";
 
 // dependencyManagement can't into classifiers, we have to pass version the old way for deps with qualifiers
 extra["otelInstrumentationVersion"] = otelInstrumentationVersion
@@ -73,7 +74,7 @@ extensions.configure<DependencyManagementExtension>("dependencyManagement") {
 
   imports {
     mavenBom("io.grpc:grpc-bom:1.38.0")
-    mavenBom("io.micrometer:micrometer-bom:1.7.3")
+    mavenBom("io.micrometer:micrometer-bom:${micrometerVersion}")
     mavenBom("io.opentelemetry:opentelemetry-bom-alpha:${otelAlphaVersion}")
     mavenBom("io.opentelemetry:opentelemetry-bom:${otelVersion}")
     mavenBom("org.junit:junit-bom:5.7.2")

deployments/cloudfoundry/buildpack/README.md

@@ -40,7 +40,7 @@ If you want to use a specific version of the Java agent in your application, you
 environment variable before application deployment, either using `cf set-env` or the `manifest.yml` file:
 
 ```sh
-$ cf set-env SPLUNK_OTEL_JAVA_VERSION 1.2.0
+$ cf set-env SPLUNK_OTEL_JAVA_VERSION 1.3.0
 ```
 
 By default, the [latest](https://github.com/signalfx/splunk-otel-java/releases/latest) available agent version is used.

docs/faq.md

@@ -2,19 +2,15 @@
 
 # Frequently Asked Questions
 
-- **Can upstream opentelemetry-java or opentelemetry-java-instrumentation be
-  used instead?** Definitely, however Splunk only provides best-effort support.
-- **What’s different between Splunk Distribution of OpenTelemetry Java and
-  OpenTelemetry Instrumentation for Java?** Supported by Splunk, better defaults
-  for Splunk products, access to other open-source projects including
-  Micrometer. Note, we take an upstream-first approach, Splunk Distribution of
-  OpenTelemetry Java allow us to move fast.
-- **Why don't you publish the javaagent jar to a Maven repository?** It would
-  make it very easy to accidentally put the agent on the application runtime
-  classpath, which may cause all sorts of problems and confusion - and the
-  agent won't work anyway, because it has to be passed in the `-javaagent` JVM
-  parameter.
-- **How often do you release?** We strive to release the Splunk distribution
-  within 2 working days after the [upstream
-  project](https://github.com/open-telemetry/opentelemetry-java-instrumentation/releases)
+- **Can upstream opentelemetry-java or opentelemetry-java-instrumentation be used instead?** Definitely, however Splunk
+  only provides best-effort support.
+- **What’s different between Splunk Distribution of OpenTelemetry Java and OpenTelemetry Instrumentation for Java?**
+  Supported by Splunk, better defaults for Splunk products, access to other open-source projects including Micrometer.
+  Note, we take an upstream-first approach, Splunk Distribution of OpenTelemetry Java allow us to move fast.
+- **Should I add the agent as a Maven/Gradle dependency to my application?** No, you definitely shouldn't! The agent
+  will not function at all if it's just added to the classpath; it should never be added to the runtime classpath
+  directly. The only way to instrument the application automatically with the agent is to use the `-javaagent` command
+  line parameter.
+- **How often do you release?** We strive to release the Splunk distribution within 2 working days after
+  the [upstream project](https://github.com/open-telemetry/opentelemetry-java-instrumentation/releases)
   releases. OpenTelemetry Java generally releases a new version every 4 weeks.

docs/metrics.md

@@ -22,13 +22,63 @@ The following dimensions are automatically added to all metrics exported by the
 | `process.pid`            | The Java process identifier (PID).
 | `service`                | The value of the `service.name` resource attribute.
 
+## Manual instrumentation
+
+The Splunk Distribution of OpenTelemetry Java agent detects if the instrumented application is using Micrometer and
+injects a special `MeterRegistry` implementation that allows the agent to pick up custom user-defined meters, as long as
+they're registered in the global `Metrics.globalRegistry` instance provided by the Micrometer library.
+
+### Dependencies
+
+You'll need to add a dependency on the `micrometer-core` library to be able to export custom metrics with the javaagent.
+
+For Maven users:
+
+```xml
+
+<dependency>
+    <groupId>io.micrometer</groupId>
+    <artifactId>micrometer-core</artifactId>
+    <version>1.7.3</version>
+</dependency>
+```
+
+For Gradle users:
+
+```kotlin
+implementation("io.micrometer:micrometer-core:1.7.3")
+```
+
+### Adding custom metrics
+
+You can use one of meter factory methods provided by the `Metrics` class, or use meter builders and refer to
+the `Metrics.globalRegistry` directly:
+
+```java
+class MyClass {
+  Counter myCounter = Metrics.counter("my_custom_counter");
+  Timer myTimer = Timer.builder("my_custom_timer").register(Metrics.globalRegistry);
+
+  int foo() {
+    myCounter.increment();
+    return myTimer.record(this::fooImpl);
+  }
+
+  private int fooImpl() {
+    // ...
+  }
+}
+```
+
+For more details on using the Micrometer API please consult the [Micrometer docs](ohttps://micrometer.io/docs/concepts).
+
 ## Supported libraries
 
 The following metrics are currently gathered by the agent:
 
 | Library/Framework                                                | Instrumentation name | Versions |
 | ---------------------------------------------------------------- | -------------------- | -------- |
-| [JVM metrics](#jvm)                                              | `jvm-metrics`        | [Java runtimes version 8 and higher](../README.md#supported-java-versions)
+| [JVM metrics](#jvm)                                              | `jvm-metrics`        | [Java runtimes version 8 and higher](../README.md#requirements)
 | [Apache DBCP2 connection pool metrics](#connection-pool-metrics) | `commons-dbcp2`      | 2.0 and higher
 | [c3p0 connection pool metrics](#connection-pool-metrics)         | `c3p0`               | 0.9.5 and higher
 | [HikariCP connection pool metrics](#connection-pool-metrics)     | `hikaricp`           | 3.0 and higher

docs/supported-libraries.md

@@ -8,7 +8,7 @@ them [here](https://github.com/open-telemetry/opentelemetry-java-instrumentation
 Aside from the instrumentations listed in the link above, the Splunk Distribution of OpenTelemetry Java provides a few
 additional custom features:
 
-* We instrument [several HTTP server frameworks](server-trace-info.md#supported-frameworks-and-libraries)
+* We instrument [several HTTP server frameworks](server-trace-info.md#frameworks-and-libraries)
   and return server trace information in the HTTP response;
 * We collect information about [application servers](webengine-attributes.md) that are being used and store it in
   server span attributes;