Skip to content

Commit

Permalink
Merge branch 'main' into rmatomic
Browse files Browse the repository at this point in the history
  • Loading branch information
MrAlias authored Dec 15, 2021
2 parents 4e1fb96 + 8f4a477 commit 039e1fe
Show file tree
Hide file tree
Showing 7 changed files with 102 additions and 29 deletions.
2 changes: 1 addition & 1 deletion CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
12 changes: 0 additions & 12 deletions internal/metric/global/meter.go
Original file line number Diff line number Diff line change
Expand Up @@ -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{}
Expand Down
8 changes: 4 additions & 4 deletions metric/config.go
Original file line number Diff line number Diff line change
Expand Up @@ -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
}

Expand Down Expand Up @@ -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
}

Expand Down
2 changes: 1 addition & 1 deletion metric/sdkapi/sdkapi.go
Original file line number Diff line number Diff line change
Expand Up @@ -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()
}
Expand Down
7 changes: 3 additions & 4 deletions trace_test.go
Original file line number Diff line number Diff line change
Expand Up @@ -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"
)
Expand All @@ -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)
}
Original file line number Diff line number Diff line change
Expand Up @@ -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" >}}
93 changes: 93 additions & 0 deletions website_docs/using_instrumentation_libraries.md
Original file line number Diff line number Diff line change
@@ -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.

0 comments on commit 039e1fe

Please sign in to comment.