From 074ac11af93345a4a701412bf252a8ebec8f7367 Mon Sep 17 00:00:00 2001 From: David Ashpole Date: Mon, 9 Oct 2023 09:11:22 -0400 Subject: [PATCH] Convert prometheus bridge readme to godocs (#4348) --- README.md | 1 + bridges/prometheus/README.md | 28 ----------------------- bridges/prometheus/doc.go | 12 ++++++++++ bridges/prometheus/example_test.go | 36 ++++++++++++++++++++++++++++++ doc.go | 2 +- 5 files changed, 50 insertions(+), 29 deletions(-) delete mode 100644 bridges/prometheus/README.md create mode 100644 bridges/prometheus/example_test.go diff --git a/README.md b/README.md index 9cbe96b8b..d1c64924f 100644 --- a/README.md +++ b/README.md @@ -15,6 +15,7 @@ Collection of 3rd-party packages for [OpenTelemetry-Go](https://github.com/open- - [Detectors](./detectors/): Packages providing OpenTelemetry resource detectors for 3rd-party cloud computing environments. - [Exporters](./exporters/): Packages providing OpenTelemetry exporters for 3rd-party export formats. - [Samplers](./samplers/): Packages providing additional implementations of OpenTelemetry samplers. +- [Bridges](./bridges/): Packages providing adapters for 3rd-party instrumentation frameworks. ## Project Status diff --git a/bridges/prometheus/README.md b/bridges/prometheus/README.md deleted file mode 100644 index 8c2e71b3b..000000000 --- a/bridges/prometheus/README.md +++ /dev/null @@ -1,28 +0,0 @@ -# Prometheus Bridge - -Status: Experimental - -The Prometheus Bridge allows using the Prometheus Golang client library -(github.com/prometheus/client_golang) with the OpenTelemetry SDK. - -## Usage - -```golang -// Make a Promethes bridge "Metric Producer" that adds metrics from the -// Prometheus DefaultGatherer. Add the WithGatherer(registry) option to add -// metrics from other registries. -bridge := prometheus.NewMetricProducer() -// Make a Periodic Reader to periodically gather metrics from the bridge, and -// push to an OpenTelemetry exporter. -reader := metric.NewPeriodicReader(otelExporter, metric.WithProducer(bridge)) -// Create an OTel MeterProvider with our reader. Metrics from OpenTelemetry -// instruments are combined with metrics from Prometheus instruments in -// exported batches of metrics. -mp := metric.NewMeterProvider(metric.WithReader(reader)) -``` - -## Limitations - -* Summary metrics are dropped by the bridge. -* Start times for histograms and counters are set to the process start time. -* It does not currently support exponential histograms. diff --git a/bridges/prometheus/doc.go b/bridges/prometheus/doc.go index 58d8a0c6b..ea2084ddc 100644 --- a/bridges/prometheus/doc.go +++ b/bridges/prometheus/doc.go @@ -13,4 +13,16 @@ // limitations under the License. // Package prometheus provides a bridge from Prometheus to OpenTelemetry. +// +// The Prometheus Bridge allows using the [Prometheus Golang client library] +// with the OpenTelemetry SDK. This enables prometheus instrumentation libraries +// to be used with OpenTelemetry exporters, including OTLP. +// +// Limitations: +// - Summary metrics are dropped by the bridge. +// - Start times for histograms and counters are set to the process start time. +// - Prometheus histograms are translated to OpenTelemetry fixed-bucket +// histograms, rather than exponential histograms. +// +// [Prometheus Golang client library]: https://github.com/prometheus/client_golang package prometheus // import "go.opentelemetry.io/contrib/bridges/prometheus" diff --git a/bridges/prometheus/example_test.go b/bridges/prometheus/example_test.go new file mode 100644 index 000000000..7a37885aa --- /dev/null +++ b/bridges/prometheus/example_test.go @@ -0,0 +1,36 @@ +// Copyright The OpenTelemetry Authors +// +// Licensed under the Apache License, Version 2.0 (the "License"); +// you may not use this file except in compliance with the License. +// You may obtain a copy of the License at +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, software +// distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +// See the License for the specific language governing permissions and +// limitations under the License. + +package prometheus_test + +import ( + "go.opentelemetry.io/contrib/bridges/prometheus" + "go.opentelemetry.io/otel/sdk/metric" +) + +func ExampleNewMetricProducer() { + // Create a Promethes bridge "Metric Producer" which adds metrics from the + // prometheus.DefaultGatherer. Add the WithGatherer option to add metrics + // from other registries. + bridge := prometheus.NewMetricProducer() + // This reader is used as a stand-in for a reader that will actually export + // data. See https://pkg.go.dev/go.opentelemetry.io/otel/exporters for + // exporters that can be used as or with readers. The metric.WithProducer + // option adds metrics from the Prometheus bridge to the reader. + reader := metric.NewManualReader(metric.WithProducer(bridge)) + // Create an OTel MeterProvider with our reader. Metrics from OpenTelemetry + // instruments are combined with metrics from Prometheus instruments in + // exported batches of metrics. + _ = metric.NewMeterProvider(metric.WithReader(reader)) +} diff --git a/doc.go b/doc.go index ebd756720..09e293f13 100644 --- a/doc.go +++ b/doc.go @@ -14,5 +14,5 @@ // Package contrib is a collection of extensions for the opentelemetry-go // project. It provides 3rd parth resource detectors, propagators, samplers, -// and instrumentation as submodules. +// bridges, and instrumentation as submodules. package contrib // import "go.opentelemetry.io/contrib"