diff --git a/instrumentation/jmx-metrics/library/README.md b/instrumentation/jmx-metrics/library/README.md new file mode 100644 index 000000000000..c7df1232e73f --- /dev/null +++ b/instrumentation/jmx-metrics/library/README.md @@ -0,0 +1,47 @@ +# Library Instrumentation for JMX Metrics + +Provides OpenTelemetry instrumentation for [Java Management Extensions (JMX)](https://docs.oracle.com/javase/tutorial/jmx/). + +This instrumentation collects JMX-based metrics and exports them as OpenTelemetry metrics. + +## Quickstart + +### Add these dependencies to your project + +Replace `OPENTELEMETRY_VERSION` with the [latest release](https://central.sonatype.com/artifact/io.opentelemetry.instrumentation/opentelemetry-jmx-metrics). + +For Maven, add to your `pom.xml` dependencies: + +```xml + + + io.opentelemetry.instrumentation + opentelemetry-jmx-metrics + OPENTELEMETRY_VERSION + + +``` + +For Gradle, add to your dependencies: + +```kotlin +implementation("io.opentelemetry.instrumentation:opentelemetry-jmx-metrics:OPENTELEMETRY_VERSION") +``` + +### Usage + +```java +import io.opentelemetry.api.OpenTelemetry; +import io.opentelemetry.instrumentation.jmx.engine.JmxMetricInsight; +import io.opentelemetry.instrumentation.jmx.engine.MetricConfiguration; + +// Get an OpenTelemetry instance +OpenTelemetry openTelemetry = ...; + +JmxMetricInsight jmxMetricInsight = JmxMetricInsight.createService(openTelemetry, 5000); + +// Configure your JMX metrics +MetricConfiguration config = new MetricConfiguration(); + +jmxMetricInsight.startLocal(config); +``` diff --git a/instrumentation/lettuce/lettuce-5.1/library/README.md b/instrumentation/lettuce/lettuce-5.1/library/README.md new file mode 100644 index 000000000000..5cbc4d98da53 --- /dev/null +++ b/instrumentation/lettuce/lettuce-5.1/library/README.md @@ -0,0 +1,50 @@ +# Library Instrumentation for Lettuce version 5.1 and higher + +Provides OpenTelemetry instrumentation for [Lettuce](https://lettuce.io/), enabling database client +spans and metrics. + +## Quickstart + +### Add these dependencies to your project + +Replace `OPENTELEMETRY_VERSION` with the [latest release](https://central.sonatype.com/artifact/io.opentelemetry.instrumentation/opentelemetry-lettuce-5.1). + +For Maven, add to your `pom.xml` dependencies: + +```xml + + + io.opentelemetry.instrumentation + opentelemetry-lettuce-5.1 + OPENTELEMETRY_VERSION + + +``` + +For Gradle, add to your dependencies: + +```kotlin +implementation("io.opentelemetry.instrumentation:opentelemetry-lettuce-5.1:OPENTELEMETRY_VERSION") +``` + +### Usage + +```java +import io.lettuce.core.RedisClient; +import io.lettuce.core.api.StatefulRedisConnection; +import io.lettuce.core.resource.ClientResources; +import io.opentelemetry.api.OpenTelemetry; +import io.opentelemetry.instrumentation.lettuce.v5_1.LettuceTelemetry; + +// Get an OpenTelemetry instance +OpenTelemetry openTelemetry = ...; + +LettuceTelemetry lettuceTelemetry = LettuceTelemetry.create(openTelemetry); + +ClientResources clientResources = ClientResources.builder() + .tracing(lettuceTelemetry.newTracing()) + .build(); + +RedisClient redisClient = RedisClient.create(clientResources, "redis://localhost:6379"); +StatefulRedisConnection connection = redisClient.connect(); +``` diff --git a/instrumentation/netty/netty-4.1/library/README.md b/instrumentation/netty/netty-4.1/library/README.md new file mode 100644 index 000000000000..e66ea4ccecf3 --- /dev/null +++ b/instrumentation/netty/netty-4.1/library/README.md @@ -0,0 +1,105 @@ +# Library Instrumentation for Netty version 4.1 and higher + +Provides OpenTelemetry instrumentation for [Netty](https://netty.io/), enabling HTTP client and +server spans and metrics. + +## Quickstart + +### Add these dependencies to your project + +Replace `OPENTELEMETRY_VERSION` with the [latest release](https://central.sonatype.com/artifact/io.opentelemetry.instrumentation/opentelemetry-netty-4.1). + +For Maven, add to your `pom.xml` dependencies: + +```xml + + + io.opentelemetry.instrumentation + opentelemetry-netty-4.1 + OPENTELEMETRY_VERSION + + +``` + +For Gradle, add to your dependencies: + +```kotlin +implementation("io.opentelemetry.instrumentation:opentelemetry-netty-4.1:OPENTELEMETRY_VERSION") +``` + +### Usage + +#### HTTP Client + +```java +import io.netty.bootstrap.Bootstrap; +import io.netty.channel.Channel; +import io.netty.channel.ChannelInitializer; +import io.netty.channel.EventLoopGroup; +import io.netty.channel.socket.SocketChannel; +import io.netty.handler.codec.http.HttpClientCodec; +import io.opentelemetry.api.OpenTelemetry; +import io.opentelemetry.context.Context; +import io.opentelemetry.instrumentation.netty.v4_1.NettyClientTelemetry; + +// Get an OpenTelemetry instance +OpenTelemetry openTelemetry = ...; + +NettyClientTelemetry clientTelemetry = NettyClientTelemetry.create(openTelemetry); + +EventLoopGroup eventLoopGroup = ...; // Use appropriate EventLoopGroup for your platform +Class channelClass = ...; // Use appropriate Channel class for your platform + +Bootstrap bootstrap = new Bootstrap(); +bootstrap.group(eventLoopGroup) + .channel(channelClass) + .handler(new ChannelInitializer() { + @Override + protected void initChannel(SocketChannel ch) { + ch.pipeline() + .addLast(new HttpClientCodec()) + .addLast(clientTelemetry.createCombinedHandler()) + .addLast(new YourClientHandler()); // Your application handler + } + }); + +Channel channel = bootstrap.connect("localhost", 8080).sync().channel(); +NettyClientTelemetry.setChannelContext(channel, Context.current()); +``` + +#### HTTP Server + +```java +import io.netty.bootstrap.ServerBootstrap; +import io.netty.channel.ChannelInitializer; +import io.netty.channel.EventLoopGroup; +import io.netty.channel.ServerChannel; +import io.netty.channel.socket.SocketChannel; +import io.netty.handler.codec.http.HttpServerCodec; +import io.opentelemetry.api.OpenTelemetry; +import io.opentelemetry.instrumentation.netty.v4_1.NettyServerTelemetry; + +// Get an OpenTelemetry instance +OpenTelemetry openTelemetry = ...; + +NettyServerTelemetry serverTelemetry = NettyServerTelemetry.create(openTelemetry); + +EventLoopGroup bossGroup = ...; // Use appropriate EventLoopGroup for your platform +EventLoopGroup workerGroup = ...; // Use appropriate EventLoopGroup for your platform +Class serverChannelClass = ...; // Use appropriate ServerChannel class for your platform + +ServerBootstrap bootstrap = new ServerBootstrap(); +bootstrap.group(bossGroup, workerGroup) + .channel(serverChannelClass) + .childHandler(new ChannelInitializer() { + @Override + protected void initChannel(SocketChannel ch) { + ch.pipeline() + .addLast(new HttpServerCodec()) + .addLast(serverTelemetry.createCombinedHandler()) + .addLast(new YourServerHandler()); // Your application handler + } + }); + +bootstrap.bind(8080).sync(); +``` diff --git a/instrumentation/oshi/library/README.md b/instrumentation/oshi/library/README.md new file mode 100644 index 000000000000..046b3cb63b5a --- /dev/null +++ b/instrumentation/oshi/library/README.md @@ -0,0 +1,52 @@ +# Library Instrumentation for OSHI version 5.3.1 and higher + +Provides OpenTelemetry instrumentation for [OSHI](https://github.com/oshi/oshi). + +This instrumentation collects system metrics such as memory usage, network I/O, and disk operations. + +## Quickstart + +### Add these dependencies to your project + +Replace `OPENTELEMETRY_VERSION` with the [latest release](https://central.sonatype.com/artifact/io.opentelemetry.instrumentation/opentelemetry-oshi). + +For Maven, add to your `pom.xml` dependencies: + +```xml + + + io.opentelemetry.instrumentation + opentelemetry-oshi + OPENTELEMETRY_VERSION + + +``` + +For Gradle, add to your dependencies: + +```kotlin +implementation("io.opentelemetry.instrumentation:opentelemetry-oshi:OPENTELEMETRY_VERSION") +``` + +### Usage + +```java +import io.opentelemetry.api.OpenTelemetry; +import io.opentelemetry.instrumentation.oshi.SystemMetrics; +import java.util.List; + +// Get an OpenTelemetry instance +OpenTelemetry openTelemetry = ...; + +List observables = SystemMetrics.registerObservers(openTelemetry); + +// The observers will automatically collect and export system metrics +// Close the observables when shutting down your application +observables.forEach(observable -> { + try { + observable.close(); + } catch (Exception e) { + // Handle exception + } +}); +``` diff --git a/instrumentation/quartz-2.0/library/README.md b/instrumentation/quartz-2.0/library/README.md new file mode 100644 index 000000000000..0174c5498d70 --- /dev/null +++ b/instrumentation/quartz-2.0/library/README.md @@ -0,0 +1,49 @@ +# Library Instrumentation for Quartz version 2.0 and higher + +Provides OpenTelemetry instrumentation for [Quartz Scheduler](https://www.quartz-scheduler.org/), +enabling job execution spans. + +## Quickstart + +### Add these dependencies to your project + +Replace `OPENTELEMETRY_VERSION` with the [latest release](https://central.sonatype.com/artifact/io.opentelemetry.instrumentation/opentelemetry-quartz-2.0). + +For Maven, add to your `pom.xml` dependencies: + +```xml + + + io.opentelemetry.instrumentation + opentelemetry-quartz-2.0 + OPENTELEMETRY_VERSION + + +``` + +For Gradle, add to your dependencies: + +```kotlin +implementation("io.opentelemetry.instrumentation:opentelemetry-quartz-2.0:OPENTELEMETRY_VERSION") +``` + +### Usage + +```java +import io.opentelemetry.api.OpenTelemetry; +import io.opentelemetry.instrumentation.quartz.v2_0.QuartzTelemetry; +import org.quartz.Scheduler; +import org.quartz.SchedulerException; +import org.quartz.impl.StdSchedulerFactory; + +// Get an OpenTelemetry instance +OpenTelemetry openTelemetry = ...; + +QuartzTelemetry quartzTelemetry = QuartzTelemetry.create(openTelemetry); + +Scheduler scheduler = StdSchedulerFactory.getDefaultScheduler(); +quartzTelemetry.configure(scheduler); + +scheduler.start(); +// Schedule your jobs - they will now be traced with OpenTelemetry +```