Merge branch 'main' into mvaggregator

CHANGELOG.md

@@ -12,6 +12,7 @@ This project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.htm
 
 - Deprecate module `"go.opentelemetry.io/otel/sdk/export/metric"`, new functionality available in "go.opentelemetry.io/otel/sdk/metric" module:
   - Import path changed `import "go.opentelemetry.io/otel/sdk/export/metric"` to `import go.opentelemetry.io/otel/sdk/metric/export` (#2382).
+- Deprecate `AtomicFieldOffsets`, unnecessary public func (#2445)
 
 ## [1.3.0] - 2021-12-10
 

CONTRIBUTING.md

@@ -478,7 +478,7 @@ Approvers:
 
 - [Evan Torrie](https://github.com/evantorrie), Verizon Media
 - [Josh MacDonald](https://github.com/jmacd), LightStep
-- [Sam Xie](https://github.com/XSAM)
+- [Sam Xie](https://github.com/XSAM), Cisco/AppDynamics
 - [David Ashpole](https://github.com/dashpole), Google
 - [Gustavo Silva Paiva](https://github.com/paivagustavo), LightStep
 - [Robert Pająk](https://github.com/pellared), Splunk

internal/metric/global/meter.go

@@ -92,18 +92,6 @@ type asyncImpl struct {
 	runner sdkapi.AsyncRunner
 }
 
-// SyncImpler is implemented by all of the sync metric
-// instruments.
-type SyncImpler interface {
-	SyncImpl() sdkapi.SyncImpl
-}
-
-// AsyncImpler is implemented by all of the async
-// metric instruments.
-type AsyncImpler interface {
-	AsyncImpl() sdkapi.AsyncImpl
-}
-
 var _ metric.MeterProvider = &meterProvider{}
 var _ sdkapi.MeterImpl = &meterImpl{}
 var _ sdkapi.InstrumentImpl = &syncImpl{}

metric/config.go

@@ -25,12 +25,12 @@ type InstrumentConfig struct {
 }
 
 // Description describes the instrument in human-readable terms.
-func (cfg InstrumentConfig) Description() string {
+func (cfg *InstrumentConfig) Description() string {
 	return cfg.description
 }
 
 // Unit describes the measurement unit for a instrument.
-func (cfg InstrumentConfig) Unit() unit.Unit {
+func (cfg *InstrumentConfig) Unit() unit.Unit {
 	return cfg.unit
 }
 
@@ -78,12 +78,12 @@ type MeterConfig struct {
 }
 
 // InstrumentationVersion is the version of the library providing instrumentation.
-func (cfg MeterConfig) InstrumentationVersion() string {
+func (cfg *MeterConfig) InstrumentationVersion() string {
 	return cfg.instrumentationVersion
 }
 
 // SchemaURL is the schema_url of the library providing instrumentation.
-func (cfg MeterConfig) SchemaURL() string {
+func (cfg *MeterConfig) SchemaURL() string {
 	return cfg.schemaURL
 }
 

metric/sdkapi/sdkapi.go

@@ -72,7 +72,7 @@ type AsyncImpl interface {
 // AsyncBatchRunner.  SDKs will encounter an error if the AsyncRunner
 // does not satisfy one of these interfaces.
 type AsyncRunner interface {
-	// AnyRunner() is a non-exported method with no functional use
+	// AnyRunner is a non-exported method with no functional use
 	// other than to make this a non-empty interface.
 	AnyRunner()
 }

sdk/metric/alignment_test.go

@@ -17,13 +17,17 @@ package metric
 import (
 	"os"
 	"testing"
+	"unsafe"
 
 	ottest "go.opentelemetry.io/otel/internal/internaltest"
 )
 
 // Ensure struct alignment prior to running tests.
 func TestMain(m *testing.M) {
-	offsets := AtomicFieldOffsets()
+	offsets := map[string]uintptr{
+		"record.refMapped.value": unsafe.Offsetof(record{}.refMapped.value),
+		"record.updateCount":     unsafe.Offsetof(record{}.updateCount),
+	}
 	var r []ottest.FieldOffset
 	for name, offset := range offsets {
 		r = append(r, ottest.FieldOffset{

sdk/metric/atomicfields.go

@@ -16,6 +16,7 @@ package metric // import "go.opentelemetry.io/otel/sdk/metric"
 
 import "unsafe"
 
+// Deprecated: will be removed soon.
 func AtomicFieldOffsets() map[string]uintptr {
 	return map[string]uintptr{
 		"record.refMapped.value": unsafe.Offsetof(record{}.refMapped.value),

trace_test.go

@@ -17,6 +17,8 @@ package otel
 import (
 	"testing"
 
+	"github.com/stretchr/testify/assert"
+
 	"go.opentelemetry.io/otel/internal/trace/noop"
 	"go.opentelemetry.io/otel/trace"
 )
@@ -36,8 +38,5 @@ func TestMultipleGlobalTracerProvider(t *testing.T) {
 	SetTracerProvider(p2)
 
 	got := GetTracerProvider()
-	want := p2
-	if got != want {
-		t.Fatalf("TracerProvider: got %p, want %p\n", got, want)
-	}
+	assert.Equal(t, p2, got)
 }

website_docs/instrumentation.md → website_docs/manual_instrumentation.md

@@ -107,10 +107,3 @@ otel.SetTextMapPropagator(propagation.TraceContext{})
 > OpenTelemetry also supports the B3 header format, for compatibility with existing tracing systems (`go.opentelemetry.io/contrib/propagators/b3`) that do not support the W3C TraceContext standard.
 
 After configuring context propagation, you'll most likely want to use automatic instrumentation to handle the behind-the-scenes work of actually managing serializing the context.
-
-# Automatic Instrumentation
-
-Automatic instrumentation, broadly, refers to instrumentation code that you didn't write. OpenTelemetry for Go supports this process through wrappers and helper functions around many popular frameworks and libraries. You can find a current list [here](https://github.com/open-telemetry/opentelemetry-go-contrib/tree/main/instrumentation), as well as at the [registry](/registry).
-
-[OpenTelemetry Specification]: {{< relref "/docs/reference/specification" >}}
-[Trace semantic conventions]: {{< relref "/docs/reference/specification/trace/semantic_conventions" >}}

website_docs/using_instrumentation_libraries.md

@@ -0,0 +1,93 @@
+---
+title: Using instrumentation libraries
+weight: 3
+---
+
+Go does not support truly automatic instrumentation like other languages today. Instead, you'll need to depend on [instrumentation libraries](https://opentelemetry.io/docs/reference/specification/glossary/#instrumentation-library) that generate telemetry data for a particular instrumented library. For example, the instrumentation library for `net/hhtp` will automatically create spans that track inbound and outbound requests once you configure it in your code.
+
+## Setup
+
+Each instrumentation library is a package. In general, this means you need to `go get` the appropriate package:
+
+```console
+go get go.opentelemetry.io/contrib/instrumentation/{import-path}/otel{package-name}
+```
+
+And then configure it in your code based on what the library requires to be activated.
+
+## Example with `net/http`
+
+As an example, here's how you can set up automatic instrumentation for inbound HTTP requests for `net/http`:
+
+First, get the `net/http` instrumentation library:
+
+```console
+go get go.opentelemetry.io/contrib/instrumentation/net/http/otelhttp
+```
+
+Next, use the library to wrap an HTTP handler in your code:
+
+```go
+package main
+
+import (
+	"context"
+	"fmt"
+	"log"
+	"net/http"
+	"time"
+
+	"go.opentelemetry.io/contrib/instrumentation/net/http/otelhttp"
+	"go.opentelemetry.io/otel"
+	"go.opentelemetry.io/otel/attribute"
+)
+
+// Package-level tracer.
+// This should be configured in your code setup instead of here.
+var tracer = otel.Tracer("github.com/full/path/to/mypkg")
+
+// sleepy mocks work that your application does.
+func sleepy(ctx context.Context) {
+	_, span := tracer.Start(ctx, "sleep")
+	defer span.End()
+
+	sleepTime := 1 * time.Second
+	time.Sleep(sleepTime)
+	span.SetAttributes(attribute.Int("sleep.duration", int(sleepTime)))
+}
+
+// httpHandler is an HTTP handler function that is going to be instrumented.
+func httpHandler(w http.ResponseWriter, r *http.Request) {
+	fmt.Fprintf(w, "Hello, World! I am instrumented autoamtically!")
+	ctx := r.Context()
+	sleepy(ctx)
+}
+
+func main() {
+	// Wrap your httpHandler function.
+	handler := http.HandlerFunc(httpHandler)
+	wrappedHandler := otelhttp.NewHandler(handler, "hello-instrumented")
+	http.Handle("/hello-instrumented", wrappedHandler)
+
+	// And start the HTTP serve.
+	log.Fatal(http.ListenAndServe(":3030", nil))
+}
+```
+
+Assuming that you have a `Tracer` and [exporter](exporting_data.md) configured, this code will:
+
+* Start an HTTP server on port `3030`
+* Automatically generate a span for each inbound HTTP request to `/hello-instrumented`
+* Create a child span of the automatically-generated one that tracks the work done in `sleepy`
+
+Connecting manual instrumentation you write in your app with instrumentation generated from a library is essential to get good observability into your apps and services.
+
+## Available packages
+
+A full list of instrumentation libraries available can be found in the [OpenTelementry registry](https://opentelemetry.io/registry/?language=go&component=instrumentation).
+
+## Next steps
+
+Instrumentation libraries can do things like generate telemtry data for inbound and outbound HTTP requests, but they don't instrument your actual application.
+
+To get richer telemetry data, use [manual instrumentatiion](manual_instrumentation.md) to enrich your telemetry data from instrumentation libraries with instrumentation from your running application.