Add an example of view (#3177)

* Add an example of view

* Update meter name in view example

Co-authored-by: Sam Xie <sam@samxie.me>

* Update dependabot and versions.yaml

* Fix code review and add CHANGELOG

Co-authored-by: Sam Xie <sam@samxie.me>
Co-authored-by: Tyler Yahn <MrAlias@users.noreply.github.com>

.github/dependabot.yml

@@ -109,6 +109,15 @@ updates:
     schedule:
       interval: weekly
       day: sunday
+  - package-ecosystem: gomod
+    directory: /example/view
+    labels:
+      - dependencies
+      - go
+      - Skip Changelog
+    schedule:
+      interval: weekly
+      day: sunday
   - package-ecosystem: gomod
     directory: /example/zipkin
     labels:

CHANGELOG.md

@@ -8,6 +8,10 @@ This project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.htm
 
 ## [Unreleased]
 
+### Added
+
+- Added an example of using metric views to customize instruments. (#3177)
+
 ### Changed
 
 - `span.SetStatus` has been updated such that calls that lower the status are now no-ops. (#3214)

example/view/doc.go

@@ -0,0 +1,16 @@
+// 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 main provides a code sample of using metric views to customize instruments.
+package main

example/view/go.mod

@@ -0,0 +1,39 @@
+module go.opentelemetry.io/otel/example/view
+
+go 1.18
+
+require (
+	github.com/prometheus/client_golang v1.13.0
+	go.opentelemetry.io/otel v1.10.0
+	go.opentelemetry.io/otel/exporters/prometheus v0.31.0
+	go.opentelemetry.io/otel/metric v0.32.1
+	go.opentelemetry.io/otel/sdk v1.10.0
+	go.opentelemetry.io/otel/sdk/metric v0.32.1
+)
+
+require (
+	github.com/beorn7/perks v1.0.1 // indirect
+	github.com/cespare/xxhash/v2 v2.1.2 // indirect
+	github.com/go-logr/logr v1.2.3 // indirect
+	github.com/go-logr/stdr v1.2.2 // indirect
+	github.com/golang/protobuf v1.5.2 // indirect
+	github.com/matttproud/golang_protobuf_extensions v1.0.1 // indirect
+	github.com/prometheus/client_model v0.2.0 // indirect
+	github.com/prometheus/common v0.37.0 // indirect
+	github.com/prometheus/procfs v0.8.0 // indirect
+	go.opentelemetry.io/otel/trace v1.10.0 // indirect
+	golang.org/x/sys v0.0.0-20220520151302-bc2c85ada10a // indirect
+	google.golang.org/protobuf v1.28.1 // indirect
+)
+
+replace go.opentelemetry.io/otel => ../..
+
+replace go.opentelemetry.io/otel/exporters/prometheus => ../../exporters/prometheus
+
+replace go.opentelemetry.io/otel/sdk => ../../sdk
+
+replace go.opentelemetry.io/otel/sdk/metric => ../../sdk/metric
+
+replace go.opentelemetry.io/otel/metric => ../../metric
+
+replace go.opentelemetry.io/otel/trace => ../../trace

example/view/main.go

@@ -0,0 +1,112 @@
+// 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 main
+
+import (
+	"context"
+	"fmt"
+	"log"
+	"net/http"
+	"os"
+	"os/signal"
+
+	"github.com/prometheus/client_golang/prometheus"
+	"github.com/prometheus/client_golang/prometheus/promhttp"
+
+	"go.opentelemetry.io/otel/attribute"
+	otelprom "go.opentelemetry.io/otel/exporters/prometheus"
+	"go.opentelemetry.io/otel/metric/instrument"
+	"go.opentelemetry.io/otel/sdk/instrumentation"
+	"go.opentelemetry.io/otel/sdk/metric"
+	"go.opentelemetry.io/otel/sdk/metric/aggregation"
+	"go.opentelemetry.io/otel/sdk/metric/view"
+)
+
+const meterName = "github.com/open-telemetry/opentelemetry-go/example/view"
+
+func main() {
+	ctx := context.Background()
+
+	// The exporter embeds a default OpenTelemetry Reader, allowing it to be used in WithReader.
+	exporter := otelprom.New()
+
+	// View to customize histogram buckets and rename a single histogram instrument.
+	customBucketsView, err := view.New(
+		// Match* to match instruments
+		view.MatchInstrumentName("custom_histogram"),
+		view.MatchInstrumentationScope(instrumentation.Scope{Name: meterName}),
+
+		// With* to modify instruments
+		view.WithSetAggregation(aggregation.ExplicitBucketHistogram{
+			Boundaries: []float64{64, 128, 256, 512, 1024, 2048, 4096},
+		}),
+		view.WithRename("bar"),
+	)
+	if err != nil {
+		log.Fatal(err)
+	}
+
+	// Default view to keep all instruments
+	defaultView, err := view.New(view.MatchInstrumentName("*"))
+	if err != nil {
+		log.Fatal(err)
+	}
+
+	provider := metric.NewMeterProvider(metric.WithReader(exporter, customBucketsView, defaultView))
+	meter := provider.Meter(meterName)
+
+	// Start the prometheus HTTP server and pass the exporter Collector to it
+	go serveMetrics(exporter.Collector)
+
+	attrs := []attribute.KeyValue{
+		attribute.Key("A").String("B"),
+		attribute.Key("C").String("D"),
+	}
+
+	counter, err := meter.SyncFloat64().Counter("foo", instrument.WithDescription("a simple counter"))
+	if err != nil {
+		log.Fatal(err)
+	}
+	counter.Add(ctx, 5, attrs...)
+
+	histogram, err := meter.SyncFloat64().Histogram("custom_histogram", instrument.WithDescription("a histogram with custom buckets and rename"))
+	if err != nil {
+		log.Fatal(err)
+	}
+	histogram.Record(ctx, 136, attrs...)
+	histogram.Record(ctx, 64, attrs...)
+	histogram.Record(ctx, 701, attrs...)
+	histogram.Record(ctx, 830, attrs...)
+
+	ctx, _ = signal.NotifyContext(ctx, os.Interrupt)
+	<-ctx.Done()
+}
+
+func serveMetrics(collector prometheus.Collector) {
+	registry := prometheus.NewRegistry()
+	err := registry.Register(collector)
+	if err != nil {
+		fmt.Printf("error registering collector: %v", err)
+		return
+	}
+
+	log.Printf("serving metrics at localhost:2222/metrics")
+	http.Handle("/metrics", promhttp.HandlerFor(registry, promhttp.HandlerOpts{}))
+	err = http.ListenAndServe(":2222", nil)
+	if err != nil {
+		fmt.Printf("error serving http: %v", err)
+		return
+	}
+}

versions.yaml

@@ -47,6 +47,7 @@ module-sets:
       - go.opentelemetry.io/otel/sdk/metric
       - go.opentelemetry.io/otel/bridge/opencensus
       - go.opentelemetry.io/otel/bridge/opencensus/test
+      - go.opentelemetry.io/otel/example/view
   experimental-schema:
     version: v0.0.3
     modules: