From b11b044ded7d05fa474672cda83fe64370f4e2e7 Mon Sep 17 00:00:00 2001 From: Jonas Kunz Date: Wed, 1 Mar 2023 12:31:39 +0100 Subject: [PATCH 1/3] Added documentation for Otel metrics --- docs/api-opentelemetry.asciidoc | 102 +++++++++++++++++++++++++++++--- docs/metrics.asciidoc | 8 +++ 2 files changed, 103 insertions(+), 7 deletions(-) diff --git a/docs/api-opentelemetry.asciidoc b/docs/api-opentelemetry.asciidoc index eaba3996a3..cb4f0d184b 100644 --- a/docs/api-opentelemetry.asciidoc +++ b/docs/api-opentelemetry.asciidoc @@ -7,7 +7,7 @@ endif::[] === OpenTelemetry bridge The Elastic APM OpenTelemetry bridge allows creating Elastic APM `Transactions` and `Spans`, -using the OpenTelemetry API. +using the OpenTelemetry API. OpenTelemetry metrics are collected and shipped to elastic as well. In other words, it translates the calls to the OpenTelemetry API to Elastic APM and thus allows for reusing existing instrumentation. @@ -136,17 +136,105 @@ try (Scope scope = custom.makeCurrent()) { To learn more about the OpenTelemetry API, head over do https://opentelemetry.io/docs/java/manual_instrumentation/[their documentation]. +[float] +[[otel-metrics]] +==== Metrics + +experimental::[] + +The Elastic APM Java Agent supports collecting metrics defined via OpenTelemetry. +You can either just use the <> or use the <> in case you need more customizations. + +In both cases the Elastic APM Agent will honor the <> and <> settings for OpenTelemetry metrics. + +You can use the <> setting to customize histogram bucket boundaries. +Alternatively you can use OpenTelemetry `Views` to define histogram buckets on a per-metric basis when providing your own `MeterProvider`. + +[float] +[[otel-metrics-api]] +==== API Usage + +You can define metrics and report metric data via `GlobalOpenTelemetry`: + +[source,java] +---- +import io.opentelemetry.api.GlobalOpenTelemetry; +import io.opentelemetry.api.metrics.LongCounter; +import io.opentelemetry.api.metrics.Meter; + +Meter myMeter = GlobalOpenTelemetry.getMeter("my_meter"); +LongCounter counter = meter.counterBuilder("my_counter").build(); +counter.add(42); +---- + +We don't require you to setup an OpenTelemetry `MeterProvider` within `GlobalOpenTelemetry` yourself. +The Elastic APM Java Agent will detect if no `MeterProvider` was configured and will provide its own automatically in this case. +If you provide your own `MeterProvider` (see <>), it will not be overridden by the agent. + +[float] +[[otel-metrics-sdk]] +==== Using a customized MeterProvider + +In some cases using just the <> might not be flexible enough. +Some example use cases are: + * You want to use OpenTelemetry Views (e.g. to customize histogram buckets on a per-metric basis) + * You want to export metrics to other tools in addition to Elastic APM (e.g. prometheus) + +For these use cases you can just setup you OpenTelemetry SDK `MeterProvider`. +The Elastic APM Agent will take care of installing an additional `MetricExporter` via instrumentation, +which will ship the metric data to Elastic APM. +This requires you to use OpenTelemetry version `1.16.0` or newer. + +To create your own `MeterProvider`, you will need to add the OpenTelemetry Metric SDK as dependency to your project: + +[source,xml] +.pom.xml +---- + + io.opentelemetry + opentelemetry-sdk-metrics + ${version.opentelemetry} + +---- + +[source,groovy] +.build.gradle +---- +compile "io.opentelemetry:opentelemetry-sdk-metrics:$openTelemetryVersion" +---- + +Afterwards you can create and use your own `MeterProvider` as shown below: + +[source,java] +---- +import io.opentelemetry.sdk.metrics.SdkMeterProvider; +import io.opentelemetry.api.metrics.DoubleHistogram; +import io.opentelemetry.api.metrics.Meter; +import io.opentelemetry.api.metrics.MeterProvider; +import io.opentelemetry.exporter.prometheus.PrometheusHttpServer; +import io.opentelemetry.sdk.metrics.InstrumentSelector; +import io.opentelemetry.sdk.metrics.View; + +//Elastic APM MetricReader will be registered automatically by the agent +SdkMeterProvider meterProvider = SdkMeterProvider.builder() + .registerMetricReader(PrometheusHttpServer.create()) + .registerView( + InstrumentSelector.builder().setName("my_histogram").build(), + View.builder().setAggregation(Aggregation.explicitBucketHistogram(List.of(1.0, 5.0))).build() + ) + .build(); + +Meter testMeter = meterProvider.get("my_meter"); +DoubleHistogram my_histogram = testMeter.histogramBuilder("my_histogram").build(); + +my_histogram.record(0.5); +---- + [float] [[otel-caveats]] ==== Caveats Not all features of the OpenTelemetry API are supported. -[float] -[[otel-metrics]] -===== Metrics -This bridge only supports the tracing API. -The Metrics API is currently not supported. - [float] [[otel-propagation]] ===== In process context propagation diff --git a/docs/metrics.asciidoc b/docs/metrics.asciidoc index 7d930b1427..6fd35150d4 100644 --- a/docs/metrics.asciidoc +++ b/docs/metrics.asciidoc @@ -25,6 +25,7 @@ When multiple JVMs are running on the same host and report data for the same ser * <> * <> * <> +* <> * <> * <> @@ -332,6 +333,13 @@ There are cases where you would want to use the agent only to collect and ship m In such cases, you may set the <> config option to `false`. By doing so, the agent will minimize its effect on the application, while still collecting and sending metrics to the APM Server. +[float] +[[metrics-otel]] +=== OpenTelemetry metrics + +The elastic APM Java Agent supports collecting metrics defined via OpenTelemetry. +See the corresponding <> for details. + [float] [[metrics-micrometer]] === Micrometer metrics From 691fa46cefffe77508a65492753db6c6cf121914 Mon Sep 17 00:00:00 2001 From: Jonas Kunz Date: Wed, 1 Mar 2023 14:10:40 +0100 Subject: [PATCH 2/3] Wording and layout fixes --- docs/api-opentelemetry.asciidoc | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/docs/api-opentelemetry.asciidoc b/docs/api-opentelemetry.asciidoc index cb4f0d184b..62bd0d1895 100644 --- a/docs/api-opentelemetry.asciidoc +++ b/docs/api-opentelemetry.asciidoc @@ -143,9 +143,9 @@ head over do https://opentelemetry.io/docs/java/manual_instrumentation/[their do experimental::[] The Elastic APM Java Agent supports collecting metrics defined via OpenTelemetry. -You can either just use the <> or use the <> in case you need more customizations. +You can either use the <> or the <> in case you need more customizations. -In both cases the Elastic APM Agent will honor the <> and <> settings for OpenTelemetry metrics. +In both cases the Elastic APM Agent will respect the <> and <> settings for OpenTelemetry metrics. You can use the <> setting to customize histogram bucket boundaries. Alternatively you can use OpenTelemetry `Views` to define histogram buckets on a per-metric basis when providing your own `MeterProvider`. @@ -177,6 +177,7 @@ If you provide your own `MeterProvider` (see <>), it will not In some cases using just the <> might not be flexible enough. Some example use cases are: + * You want to use OpenTelemetry Views (e.g. to customize histogram buckets on a per-metric basis) * You want to export metrics to other tools in addition to Elastic APM (e.g. prometheus) From df7d7632fe6304bad729db9e76470e29a2803f3e Mon Sep 17 00:00:00 2001 From: Jonas Kunz Date: Thu, 2 Mar 2023 09:27:27 +0100 Subject: [PATCH 3/3] Apply suggestions from code review Co-authored-by: SylvainJuge --- docs/api-opentelemetry.asciidoc | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/api-opentelemetry.asciidoc b/docs/api-opentelemetry.asciidoc index 62bd0d1895..bcc90655c7 100644 --- a/docs/api-opentelemetry.asciidoc +++ b/docs/api-opentelemetry.asciidoc @@ -7,7 +7,7 @@ endif::[] === OpenTelemetry bridge The Elastic APM OpenTelemetry bridge allows creating Elastic APM `Transactions` and `Spans`, -using the OpenTelemetry API. OpenTelemetry metrics are collected and shipped to elastic as well. +using the OpenTelemetry API. OpenTelemetry metrics are also collected. In other words, it translates the calls to the OpenTelemetry API to Elastic APM and thus allows for reusing existing instrumentation. @@ -169,7 +169,7 @@ counter.add(42); We don't require you to setup an OpenTelemetry `MeterProvider` within `GlobalOpenTelemetry` yourself. The Elastic APM Java Agent will detect if no `MeterProvider` was configured and will provide its own automatically in this case. -If you provide your own `MeterProvider` (see <>), it will not be overridden by the agent. +If you provide your own `MeterProvider` (see <>), the agent will use the provided instance. [float] [[otel-metrics-sdk]] @@ -178,13 +178,13 @@ If you provide your own `MeterProvider` (see <>), it will not In some cases using just the <> might not be flexible enough. Some example use cases are: - * You want to use OpenTelemetry Views (e.g. to customize histogram buckets on a per-metric basis) - * You want to export metrics to other tools in addition to Elastic APM (e.g. prometheus) + * Using OpenTelemetry Views (e.g. to customize histogram buckets on a per-metric basis) + * Exporting metrics to other tools in addition to Elastic APM (e.g. prometheus) For these use cases you can just setup you OpenTelemetry SDK `MeterProvider`. The Elastic APM Agent will take care of installing an additional `MetricExporter` via instrumentation, which will ship the metric data to Elastic APM. -This requires you to use OpenTelemetry version `1.16.0` or newer. +This requires using OpenTelemetry version `1.16.0` or newer. To create your own `MeterProvider`, you will need to add the OpenTelemetry Metric SDK as dependency to your project: