From db047023162da51e9217c3cf7e264c9863a97cc3 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Fabian=20St=C3=A4ber?= Date: Tue, 26 Sep 2023 22:10:46 +0200 Subject: [PATCH] Add OTel docs outline MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Fabian Stäber --- docs/content/otel/names.md | 5 ++++- docs/content/otel/otlp.md | 5 ++++- docs/content/otel/tracing.md | 11 ++++++++++- 3 files changed, 18 insertions(+), 3 deletions(-) diff --git a/docs/content/otel/names.md b/docs/content/otel/names.md index 89f6515c7..45b94fcc2 100644 --- a/docs/content/otel/names.md +++ b/docs/content/otel/names.md @@ -3,4 +3,7 @@ title: Names weight: 3 --- -TODO: How to iplement OpenTelemetry semantic conventions, and how OpenTelemetry metric and label names are converted to Prometheus. +TODO: This section will contain information on: + +* Mapping Prometheus metric names to OpenTelemetry when using the `OpenTelemetryExporter`. See OpenTelemetry's [Prometheus and OpenMetrics Compatibility](https://opentelemetry.io/docs/specs/otel/compatibility/prometheus_and_openmetrics/). +* Using dots in label and metric names to implement OpenTelemetry's semantic conventions. diff --git a/docs/content/otel/otlp.md b/docs/content/otel/otlp.md index 9c7938d99..345542606 100644 --- a/docs/content/otel/otlp.md +++ b/docs/content/otel/otlp.md @@ -3,4 +3,7 @@ title: OTLP weight: 1 --- -TODO: How to push metrics to an OpenTelemetry endpoint using the OpenTelemetry exporter. +TODO: This section will describe how to push metrics to an OpenTelemetry endpoint using the OpenTelemetry exporter. + +In the meantime, have a look at the example in [examples/example-exporter-opentelemetry](https://github.com/prometheus/client_java/tree/main/examples/example-exporter-opentelemetry). +It has an example Java program with the `OpenTelemetryExporter`, and a Docker compose setting up a pipeline with the OpenTelemetry collector and a Prometheus server. diff --git a/docs/content/otel/tracing.md b/docs/content/otel/tracing.md index 47af209cc..99bcbd6cb 100644 --- a/docs/content/otel/tracing.md +++ b/docs/content/otel/tracing.md @@ -3,4 +3,13 @@ title: Tracing weight: 2 --- -TODO: How to integrate Prometheus metrics with OTel traces. +It is a common scenario that you use the Prometheus Java client for metrics, and the OpenTelemetry Java instrumentation agent for tracing. + +The Prometheus Java client has some awesome features under the hood to support integration with OpenTelemetry tracing: + +* `service.name` and `service.instance.id` are used in OpenTelemetry to uniquely identify a service instance. If an OpenTelemetry Java agent is attached, the Prometheus library will automatically use the same `service.name` and `service.instance.id` as the agent when pushing metrics in OpenTelemetry format. That way the monitoring backend will see that the metrics and the traces are coming from the same instance. +* Exemplars are added automatically if a Prometheus metric is updated in the context of a distributed OpenTelemetry trace. +* If a Span is used as an Exemplar, the Span is marked with the Span attribute `exemplar="true"`. This can be used in the OpenTelemetry's sampling policy to make sure Exemplars are always sampled. + +TODO: We will add more information on integration OTel tracing with Prometheus metrics here. +In the meantime, have a look at the tail sampling end-to-end example in [examples/example-exemplars-tail-sampling](https://github.com/prometheus/client_java/tree/main/examples/example-exemplars-tail-sampling).