Convert prometheus bridge readme to godocs (#4348)

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
 

bridges/prometheus/README.md

@@ -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.

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"

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))
+}

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"