Add sdk/metric Go pkg docs and example (#3139)

* Add sdk/metric Go pkg docs

* Add example_test.go

* Add Go 1.18 build guard to example_test.go

sdk/metric/doc.go

@@ -12,4 +12,35 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 
+// Package metric provides an implementation of the OpenTelemetry metric SDK.
+//
+// See https://opentelemetry.io/docs/concepts/signals/metrics/ for information
+// about the concept of OpenTelemetry metrics and
+// https://opentelemetry.io/docs/concepts/components/ for more information
+// about OpenTelemetry SDKs.
+//
+// The entry point for the metric package is the MeterProvider. It is the
+// object that all API calls use to create Meters, instruments, and ultimately
+// make metric measurements. Also, it is an object that should be used to
+// control the life-cycle (start, flush, and shutdown) of the SDK.
+//
+// A MeterProvider needs to be configured to export the measured data, this is
+// done by configuring it with a Reader implementation (using the WithReader
+// MeterProviderOption). Readers take two forms: ones that push to an endpoint
+// (NewPeriodicReader), and ones that an endpoint pulls from. See the
+// go.opentelemetry.io/otel/exporters package for exporters that can be used as
+// or with these Readers.
+//
+// Each Reader, when registered with the MeterProvider, can be augmented with a
+// View. Views allow users that run OpenTelemetry instrumented code to modify
+// the generated data of that instrumentation. See the
+// go.opentelemetry.io/otel/sdk/metric/view package for more information about
+// Views.
+//
+// The data generated by a MeterProvider needs to include information about its
+// origin. A MeterProvider needs to be configured with a Resource, using the
+// WithResource MeterProviderOption, to include this information. This Resource
+// should be used to describe the unique runtime environment instrumented code
+// is being run on. That way when multiple instances of the code are collected
+// at a single endpoint their origin is decipherable.
 package metric // import "go.opentelemetry.io/otel/sdk/metric"

sdk/metric/example_test.go

@@ -0,0 +1,63 @@
+// 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.
+
+//go:build go1.18
+// +build go1.18
+
+package metric_test
+
+import (
+	"context"
+	"log"
+
+	"go.opentelemetry.io/otel/metric/global"
+	"go.opentelemetry.io/otel/sdk/metric"
+	"go.opentelemetry.io/otel/sdk/resource"
+	semconv "go.opentelemetry.io/otel/semconv/v1.12.0"
+)
+
+func Example() {
+	// This reader is used as a stand-in for a reader that will actually export
+	// data. See exporters in the go.opentelemetry.io/otel/exporters package
+	// for more information.
+	reader := metric.NewManualReader()
+
+	// See the go.opentelemetry.io/otel/sdk/resource package for more
+	// information about how to create and use Resources.
+	res := resource.NewWithAttributes(
+		semconv.SchemaURL,
+		semconv.ServiceNameKey.String("my-service"),
+		semconv.ServiceVersionKey.String("v0.1.0"),
+	)
+
+	meterProvider := metric.NewMeterProvider(
+		metric.WithResource(res),
+		metric.WithReader(reader),
+	)
+	global.SetMeterProvider(meterProvider)
+	defer func() {
+		err := meterProvider.Shutdown(context.Background())
+		if err != nil {
+			log.Fatalln(err)
+		}
+	}()
+	// The MeterProvider is configured and registered globally. You can now run
+	// your code instrumented with the OpenTelemetry API that uses the global
+	// MeterProvider without having to pass this MeterProvider instance. Or,
+	// you can pass this instance directly to your instrumented code if it
+	// accepts a MeterProvider instance.
+	//
+	// See the go.opentelemetry.io/otel/metric package for more information
+	// about the metric API.
+}