Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

UserGuide and example extended for Micrometer integration #5427

Merged
merged 11 commits into from
Oct 18, 2023
Merged

UserGuide and example extended for Micrometer integration #5427

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
11 commits
Select commit Hold shift + click to select a range
959c43f
UserGuide and example extended for Micrometer integration
senivam Sep 27, 2023
ecd71d1
example extended for Micrometer integration
senivam Oct 9, 2023
b1d2ae1
example extended for Micrometer integration
senivam Oct 10, 2023
429ef1a
example extended for Micrometer integration
senivam Oct 11, 2023
9f04352
alignment
senivam Oct 11, 2023
fdcfea5
alignment
senivam Oct 17, 2023
954668b
alignment
senivam Oct 17, 2023
bc912c0
Micrometer example improvement
senivam Oct 17, 2023
0233464
Micrometer example improvement
senivam Oct 18, 2023
5af43c4
Typos fix
senivam Oct 18, 2023
2e13720
Typos fix
senivam Oct 18, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
10 changes: 10 additions & 0 deletions bundles/apidocs/pom.xml
View file
Open in desktop
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
View file
Open in desktop
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
View file
Open in desktop
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
View file
Open in desktop
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
85 changes: 85 additions & 0 deletions docs/src/main/docbook/micrometer.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,85 @@
<?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. The 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 <literal>@Counted</literal> 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 a set of <literal>@Timed</literal>.
</para>
</section>
</chapter>
64 changes: 64 additions & 0 deletions docs/src/main/docbook/modules.xml
View file
Open in desktop
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
View file
Open in desktop
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 @@ -105,6 +105,7 @@ This line fits the page width.
<xi:include href="declarative-linking.xml" />
<xi:include href="resource-builder.xml" />
<xi:include href="mp-config.xml" />
<xi:include href="micrometer.xml" />
<xi:include href="sse.xml" />
<xi:include href="security.xml" />
<xi:include href="wadl.xml" />
Expand Down
49 changes: 24 additions & 25 deletions examples/micrometer/README.MD
View file
Open in desktop
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,20 +18,25 @@ The mapping of the URI path space is presented in the following table:

URI path | Resource class | HTTP methods
------------------------------------------ | ------------------------- | --------------
**_/micro/meter_** | JerseyResource | GET
**_/micro/metrics_** | JerseyResource | GET
**_/micro/metrics/metrics_** | JerseyResource | GET
**_/micro/timed_** | MeasuredTimedResource | GET
**_/micro/metrics_** | MetricsResource | GET
**_/micro/summary_** | SummaryResource | GET

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

```javascript
--- (micro/meter)
Hello World!
---- (micro/metrics)
Listing available meters: http.shared.metrics;
---- (micro/metric/metrics)
Overall requests counts: 9, total time (millis): 35.799483
```html
--- (micro/timed)
Requests to this method are measured. Use /init to see more
---- (micro/metrics)
Static meters are initialized, try summary. If you want more measurements just refresh this page several times.
---- (micro/summary)
Listing available meters
Many occurrences of the same name means that there are more meters which could be used with different tags, but this is actually a challenge to handle all available metrics :
http.timers;
http.shared.metrics;
Counts to the init page: 2, time spent on requests to the init page (millis): 2.759025
Requests to 'measure/timed' counts: 2, total time (millis): 40.110161
```


Expand All @@ -48,10 +47,10 @@ 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/timed>
- and see the responses from available resource pages
- then go to the
- - <http://localhost:8080/micro/metrics/metrics>
- <http://localhost:8080/micro/summary>
- and see statistics for the micro/meter page
12 changes: 3 additions & 9 deletions examples/micrometer/pom.xml
View file
Open in desktop
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
Loading