Skip to content

Commit

Permalink
UserGuide and example extended for Micrometer integration
Browse files Browse the repository at this point in the history
Signed-off-by: Maxim Nesen <maxim.nesen@oracle.com>
  • Loading branch information
senivam committed Sep 27, 2023
1 parent 8a63706 commit 4b26f1a
Show file tree
Hide file tree
Showing 18 changed files with 397 additions and 160 deletions.
10 changes: 10 additions & 0 deletions bundles/apidocs/pom.xml
Original file line number Diff line number Diff line change
Expand Up @@ -101,6 +101,11 @@
<artifactId>jersey-jetty-connector</artifactId>
<version>${project.version}</version>
</dependency>
<dependency>
<groupId>org.glassfish.jersey.connectors</groupId>
<artifactId>jersey-jetty-http2-connector</artifactId>
<version>${project.version}</version>
</dependency>
<dependency>
<groupId>org.glassfish.jersey.connectors</groupId>
<artifactId>jersey-netty-connector</artifactId>
Expand Down Expand Up @@ -213,6 +218,11 @@
<artifactId>jersey-declarative-linking</artifactId>
<version>${project.version}</version>
</dependency>
<dependency>
<groupId>org.glassfish.jersey.ext.micrometer</groupId>
<artifactId>jersey-micrometer</artifactId>
<version>${project.version}</version>
</dependency>
<dependency>
<groupId>org.glassfish.jersey.ext.microprofile</groupId>
<artifactId>jersey-mp-config</artifactId>
Expand Down
2 changes: 1 addition & 1 deletion docs/pom.xml
Original file line number Diff line number Diff line change
Expand Up @@ -77,7 +77,7 @@
<plugin>
<groupId>com.agilejava.docbkx</groupId>
<artifactId>docbkx-maven-plugin</artifactId>
<version>2.0.15</version>
<version>2.0.17</version>
<dependencies>
<dependency>
<groupId>net.sf.docbook</groupId>
Expand Down
5 changes: 5 additions & 0 deletions docs/src/main/docbook/client.xml
Original file line number Diff line number Diff line change
Expand Up @@ -660,6 +660,11 @@ webTarget.request().post(Entity.entity(f, MediaType.TEXT_PLAIN_TYPE));
<entry>&jersey.jetty.JettyConnectorProvider;</entry>
<entry><literal>org.glassfish.jersey.connectors:jersey-jetty-connector</literal></entry>
</row>
<row>
<entry>Jetty HTTP/2 client</entry>
<entry>&jersey.jetty.JettyHttp2ConnectorProvider;</entry>
<entry><literal>org.glassfish.jersey.connectors:jersey-jetty-http2-connector</literal></entry>
</row>
<row>
<entry>Netty NIO framework</entry>
<entry>&jersey.netty.NettyConnectorProvider;</entry>
Expand Down
3 changes: 3 additions & 0 deletions docs/src/main/docbook/jersey.ent
Original file line number Diff line number Diff line change
Expand Up @@ -109,6 +109,8 @@
<!ENTITY helidon.link "<link xlink:href='https://helidon.io/'>Helidon</link>">
<!ENTITY smallrye.link "<link xlink:href='https://smallrye.io/'>SmallRye</link>">
<!ENTITY yasson.link "<link xlink:href='https://eclipse-ee4j.github.io/yasson/'>Yasson</link>">
<!ENTITY micrometer.link "<link xlink:href='https://micrometer.io/'>Micrometer project</link>">
<!ENTITY micrometer.jersey.link "<link xlink:href='https://micrometer.io/docs/ref/jetty'>Micrometer Jersey/Jetty support</link>">

<!-- API Docs links -->
<!ENTITY bv.Configuration "<link xlink:href='&bv11.javadoc.uri;/javax/validation/Configuration.html'>Configuration</link>">
Expand Down Expand Up @@ -476,6 +478,7 @@
<!ENTITY jersey.jetty.JettyClientProperties.SYNC_LISTENER_RESPONSE_MAX_SIZE "<link xlink:href='&jersey.javadoc.uri.prefix;/jetty/connector/JettyClientProperties.html#SYNC_LISTENER_RESPONSE_MAX_SIZE'>JettyClientProperties.SYNC_LISTENER_RESPONSE_MAX_SIZE</link>" >
<!ENTITY jersey.jetty.JettyClientProperties.TOTAL_TIMEOUT "<link xlink:href='&jersey.javadoc.uri.prefix;/jetty/connector/JettyClientProperties.html#TOTAL_TIMEOUT'>JettyClientProperties.TOTAL_TIMEOUT</link>" >
<!ENTITY jersey.jetty.JettyConnectorProvider "<link xlink:href='&jersey.javadoc.uri.prefix;/jetty/connector/JettyConnectorProvider.html'>JettyConnectorProvider</link>">
<!ENTITY jersey.jetty.JettyHttp2ConnectorProvider "<link xlink:href='&jersey.javadoc.uri.prefix;/jetty/http2/connector/JettyConnectorProvider.html'>JettyHttp2ConnectorProvider</link>">
<!ENTITY jersey.jetty.JettyHttpContainer "<link xlink:href='&jersey.javadoc.uri.prefix;/jetty/JettyHttpContainer.html'>JettyHttpContainer</link>">
<!ENTITY jersey.jetty.JettyHttpContainerFactory "<link xlink:href='&jersey.javadoc.uri.prefix;/jetty/JettyHttpContainerFactory.html'>JettyHttpContainerFactory</link>">
<!ENTITY jersey.jetty.JettyHttpContainerProvider "<link xlink:href='&jersey.javadoc.uri.prefix;/jetty/JettyHttpContainerProvider.html'>JettyHttpContainerProvider</link>">
Expand Down
92 changes: 92 additions & 0 deletions docs/src/main/docbook/micrometer.xml
Original file line number Diff line number Diff line change
@@ -0,0 +1,92 @@
<?xml version="1.0" encoding="UTF-8"?>
<!--
Copyright (c) 2023 Oracle and/or its affiliates. All rights reserved.
This program and the accompanying materials are made available under the
terms of the Eclipse Public License v. 2.0, which is available at
http://www.eclipse.org/legal/epl-2.0.
This Source Code may also be made available under the following Secondary
Licenses when the conditions for such availability set forth in the
Eclipse Public License v. 2.0 are satisfied: GNU General Public License,
version 2 with the GNU Classpath Exception, which is available at
https://www.gnu.org/software/classpath/license.html.
SPDX-License-Identifier: EPL-2.0 OR GPL-2.0 WITH Classpath-exception-2.0
-->

<!DOCTYPE chapter [<!ENTITY % ents SYSTEM "jersey.ent" > %ents; ]>
<chapter xmlns="http://docbook.org/ns/docbook"
version="5.0"
xml:lang="en"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:xi="http://www.w3.org/2001/XInclude"
xmlns:xlink="http://www.w3.org/1999/xlink"
xsi:schemaLocation="http://docbook.org/ns/docbook http://docbook.org/xml/5.0/xsd/docbook.xsd
http://www.w3.org/1999/xlink http://www.w3.org/1999/xlink.xsd"
xml:id="jersey-micrometer">
<title>Micrometer - application observability facade</title>
<para>
The chapter is about Micrometer integration into Jersey which comes since the version 2.41 as an extension module.
Before Jersey 2.41 it was possible to integrate Micrometer with Jersey using directly &micrometer.jersey.link;
There is also support for Jakarta EE 10 integration. Detailed documentation regarding metrics fine-tuning
can be found at the &micrometer.link;
</para>
<section xml:id="micrometer-integration">
<title>Integration into Jersey</title>
<para>
Since Jersey 2.41 it's possibly to use an extension module in order to use Micrometer instrumentation
inside your projects. The module shall be added as a dependency:
<programlisting language="xml" linenumbering="unnumbered">
&lt;dependency>
&lt;groupId>org.glassfish.jersey.ext.micrometer&lt;/groupId>
&lt;artifactId>jersey-micrometer&lt;/artifactId>
&lt;version>&version;&lt;/scope>
&lt;/dependency>
</programlisting>
After the dependency is added, the Micrometer can be configured as follows:
<programlisting language="java" linenumbering="unnumbered">
final ResourceConfig resourceConfig = new ResourceConfig();
resourceConfig.register(new MetricsApplicationEventListener(
registry,
new DefaultJerseyTagsProvider(),
"http.shared.metrics",
true));
final ServletContainer servletContainer = new ServletContainer(resourceConfig);
</programlisting>
the registry instance is of type <literal>MeterRegistry</literal> which could be
<literal>new SimpleMeterRegistry();</literal>. Then all metrics can be accessed like
<literal>registry.get("http.shared.metrics")</literal>. The "http.shared.metrics" string
is the name of a particular registry which was registered within the
<literal>MetricsApplicationEventListener</literal>.

Micrometer supports a set of <literal>Meter</literal> primitives, including <literal>Timer</literal>,
<literal>Counter</literal>, <literal>Gauge</literal>, <literal>DistributionSummary</literal>,
<literal>LongTaskTimer</literal>, <literal>FunctionCounter</literal>, <literal>FunctionTimer</literal>,
and <literal>TimeGauge</literal>.
Different meter types result in a different number of time series metrics. For example, while there is
a single metric that represents a <literal>Gauge</literal>, a <literal>Timer</literal> measures both the
count of timed events and the total time of all timed events.
</para>
<para>
Implementing resource methods, which should be measured, several annotations can be used. The basic example
demonstrates the <listeral>@Counted</listeral> annotation.
<example>
<title>Annotated Micrometer resource methods</title>
<programlisting language="java" linenumbering="unnumbered">
@GET
@Counted(value = COUNTER_NAME, description = COUNTER_DESCRIPTION)
@Produces(MediaType.TEXT_PLAIN)
@Path("counted")
public String getCounterMessage() {
return "Requests to this method are counted. Use /metrics to see more";
}
</programlisting>
</example>
Metrics however can be introduced using another annotations <literal>@Timed</literal>, or
<literal>@TimedSet</literal> which is set of <literal>@Timed</literal>.
</para>
</section>
</chapter>
64 changes: 64 additions & 0 deletions docs/src/main/docbook/modules.xml
Original file line number Diff line number Diff line change
Expand Up @@ -116,6 +116,14 @@
</row>
<row>
<entry>
<link xlink:href="https://eclipse-ee4j.github.io/jersey.github.io/project-info/&version;/jersey/project/jersey-container-jetty-http2/dependencies.html">
jersey-container-jetty-http2
</link>
</entry>
<entry>Jetty HTTP/2 Container</entry>
</row>
<row>
<entry>
<link xlink:href="https://eclipse-ee4j.github.io/jersey.github.io/project-info/&version;/jersey/project/jersey-container-jetty-servlet/dependencies.html">
jersey-container-jetty-servlet
</link>
Expand Down Expand Up @@ -178,6 +186,14 @@
<tbody>
<row>
<entry>
<link xlink:href="https://eclipse-ee4j.github.io/jersey.github.io/project-info/&version;/jersey/project/jersey-apache5-connector/dependencies.html">
jersey-apache5-connector
</link>
</entry>
<entry>Jersey Client Transport via Apache 5</entry>
</row>
<row>
<entry>
<link xlink:href="https://eclipse-ee4j.github.io/jersey.github.io/project-info/&version;/jersey/project/jersey-apache-connector/dependencies.html">
jersey-apache-connector
</link>
Expand All @@ -194,6 +210,14 @@
</row>
<row>
<entry>
<link xlink:href="https://eclipse-ee4j.github.io/jersey.github.io/project-info/&version;/jersey/project/jersey-helidon-connector/dependencies.html">
jersey-helidon-connector
</link>
</entry>
<entry>Jersey Client Transport via Helidon</entry>
</row>
<row>
<entry>
<link xlink:href="https://eclipse-ee4j.github.io/jersey.github.io/project-info/&version;/jersey/project/jersey-jdk-connector/dependencies.html">
jersey-jdk-connector
</link>
Expand All @@ -210,6 +234,14 @@
</row>
<row>
<entry>
<link xlink:href="https://eclipse-ee4j.github.io/jersey.github.io/project-info/&version;/jersey/project/jersey-jetty-http2-connector/dependencies.html">
jersey-jetty-http2-connector
</link>
</entry>
<entry>Jersey Client Transport via Jetty with HTTP/2 support</entry>
</row>
<row>
<entry>
<link xlink:href="https://eclipse-ee4j.github.io/jersey.github.io/project-info/&version;/jersey/project/jersey-netty-connector/dependencies.html">
jersey-netty-connector
</link>
Expand Down Expand Up @@ -398,6 +430,30 @@
</row>
<row>
<entry>
<link xlink:href="https://eclipse-ee4j.github.io/jersey.github.io/project-info/&version;/jersey/project/jersey-micrometer/dependencies.html">
jersey-micrometer
</link>
</entry>
<entry>Jersey extension module providing support for Micrometer.</entry>
</row>
<row>
<entry>
<link xlink:href="https://eclipse-ee4j.github.io/jersey.github.io/project-info/&version;/jersey/project/project/jersey-mp-config/dependencies.html">
jersey-mp-config
</link>
</entry>
<entry>Jersey extension module providing support for MicroProfile Configuration.</entry>
</row>
<row>
<entry>
<link xlink:href="https://eclipse-ee4j.github.io/jersey.github.io/project-info/&version;/jersey/project/project/jersey-mp-rest-client/dependencies.html">
jersey-mp-rest-client
</link>
</entry>
<entry>Jersey extension module providing support for MicroProfile REST Client.</entry>
</row>
<row>
<entry>
<link xlink:href="https://eclipse-ee4j.github.io/jersey.github.io/project-info/&version;/jersey/project/jersey-mvc/dependencies.html">
jersey-mvc
</link>
Expand Down Expand Up @@ -486,6 +542,14 @@
</row>
<row>
<entry>
<link xlink:href="https://eclipse-ee4j.github.io/jersey.github.io/project-info/&version;/jersey/project/jersey-spring5/dependencies.html">
jersey-spring5
</link>
</entry>
<entry>Jersey extension module providing support for Spring 5 integration.</entry>
</row>
<row>
<entry>
<link xlink:href="https://eclipse-ee4j.github.io/jersey.github.io/project-info/&version;/jersey/project/jersey-wadl-doclet/dependencies.html">
jersey-wadl-doclet
</link>
Expand Down
3 changes: 2 additions & 1 deletion docs/src/main/docbook/user-guide.xml
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
<?xml version="1.0"?>
<!--
Copyright (c) 2010, 2021 Oracle and/or its affiliates. All rights reserved.
Copyright (c) 2010, 2023 Oracle and/or its affiliates. All rights reserved.
This program and the accompanying materials are made available under the
terms of the Eclipse Public License v. 2.0, which is available at
Expand Down Expand Up @@ -104,6 +104,7 @@ This line fits the page width.
<xi:include href="uris-and-links.xml" />
<xi:include href="declarative-linking.xml" />
<xi:include href="resource-builder.xml" />
<xi:include href="micrometer.xml" />
<xi:include href="mp-config.xml" />
<xi:include href="sse.xml" />
<xi:include href="security.xml" />
Expand Down
39 changes: 18 additions & 21 deletions examples/micrometer/README.MD
Original file line number Diff line number Diff line change
@@ -1,16 +1,10 @@
[//]: # " Copyright (c) 2023 Oracle and/or its affiliates. All rights reserved. "
[//]: # " "
[//]: # " "
[//]: # " This program and the accompanying materials are made available under the "
[//]: # " terms of the Eclipse Public License v. 2.0, which is available at "
[//]: # " http://www.eclipse.org/legal/epl-2.0. "
[//]: # " "
[//]: # " This Source Code may also be made available under the following Secondary "
[//]: # " Licenses when the conditions for such availability set forth in the "
[//]: # " Eclipse Public License v. 2.0 are satisfied: GNU General Public License, "
[//]: # " version 2 with the GNU Classpath Exception, which is available at "
[//]: # " https://www.gnu.org/software/classpath/license.html. "
[//]: # " "
[//]: # " SPDX-License-Identifier: EPL-2.0 OR GPL-2.0 WITH Classpath-exception-2.0 "
[//]: # " terms of the Eclipse Distribution License v. 1.0, which is available at "
[//]: # " http://www.eclipse.org/org/documents/edl-v10.php. "
[//]: # " "
[//]: # " SPDX-License-Identifier: BSD-3-Clause "

jersey-micrometer-webapp
==========================================================
Expand All @@ -24,19 +18,21 @@ The mapping of the URI path space is presented in the following table:

URI path | Resource class | HTTP methods
------------------------------------------ | ------------------------- | --------------
**_/micro/meter_** | JerseyResource | GET
**_/micro/measure/timed_** | JerseyResource | GET
**_/micro/measure/counted_** | JerseyResource | GET
**_/micro/metrics_** | JerseyResource | GET
**_/micro/metrics/metrics_** | JerseyResource | GET

Sample Response
---------------

```javascript
--- (micro/meter)
Hello World!
```html
--- (micro/measure/timed)
Requests to this method are measured. Use /metrics to see more
--- (micro/measure/counted)
Requests to this method are counted. Use /metrics to see more
---- (micro/metrics)
Listing available meters: http.shared.metrics;
---- (micro/metric/metrics)
----)
Overall requests counts: 9, total time (millis): 35.799483
```

Expand All @@ -48,10 +44,11 @@ Run the example using [Grizzly](https://javaee.github.io/grizzly/) container as

> mvn clean compile exec:java
- <http://localhost:8080/micro/meter>
- <http://localhost:8080/micro/metrics>
- after few request to the main page go to the url
- - <http://localhost:8080/micro/metrics>
- and see the list of available meters
- - <http://localhost:8080/micro/measure/timed>
- - <http://localhost:8080/micro/measure/counted>
- and see the responses from available resource pages
- then go to the
- - <http://localhost:8080/micro/metrics/metrics>
- - <http://localhost:8080/micro/metrics>
- and see statistics for the micro/meter page
17 changes: 8 additions & 9 deletions examples/micrometer/pom.xml
Original file line number Diff line number Diff line change
Expand Up @@ -4,16 +4,10 @@
Copyright (c) 2023 Oracle and/or its affiliates. All rights reserved.
This program and the accompanying materials are made available under the
terms of the Eclipse Public License v. 2.0, which is available at
http://www.eclipse.org/legal/epl-2.0.
terms of the Eclipse Distribution License v. 1.0, which is available at
http://www.eclipse.org/org/documents/edl-v10.php.
This Source Code may also be made available under the following Secondary
Licenses when the conditions for such availability set forth in the
Eclipse Public License v. 2.0 are satisfied: GNU General Public License,
version 2 with the GNU Classpath Exception, which is available at
https://www.gnu.org/software/classpath/license.html.
SPDX-License-Identifier: EPL-2.0 OR GPL-2.0 WITH Classpath-exception-2.0
SPDX-License-Identifier: BSD-3-Clause
-->
<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
Expand Down Expand Up @@ -63,6 +57,11 @@
<artifactId>junit-jupiter-api</artifactId>
<scope>test</scope>
</dependency>
<dependency>
<groupId>org.aspectj</groupId>
<artifactId>aspectjweaver</artifactId>
<version>${aspectj.weaver.version}</version>
</dependency>
</dependencies>

<build>
Expand Down
Loading

0 comments on commit 4b26f1a

Please sign in to comment.