diff --git a/sdk/metric/doc.go b/sdk/metric/doc.go index dde763d634e..6cbc7fdfc0d 100644 --- a/sdk/metric/doc.go +++ b/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" diff --git a/sdk/metric/example_test.go b/sdk/metric/example_test.go new file mode 100644 index 00000000000..eabe781738a --- /dev/null +++ b/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. +}