openTelemetry 文档翻译之 instrumentation go语言

Using instrumentation libraries

Go does not support truly automatic instrumentation like other languages today. Instead, you’ll need to depend on instrumentation libraries that generate telemetry data for a particular instrumented library.

For example, the instrumentation library for net/http will automatically create spans that track inbound and outbound requests once you configure it in your code.

go 语言不像今天的其他语言支持真正的自动检测。相反，你需要依赖于为特定 instrumented library 生成遥测数据的仪器库生成 telemetry data 的 instrumentation libraries 。例如，只要在代码中进行配置，“net/http” 的检测库将自动创建 spans 来跟踪 inbound 和 outbound 请求。

设置 Setup

Each instrumentation library is a package. In general, this means you need to go get the appropriate package:

每个仪器库（ instrumentation library ）都是一个包。通常来说，这意味着你需要 “go get” 合适的 package ：

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:

例如，以下是如何为“net/HTTP”的 inbound HTTP 请求设置自动检测：

First, get the net/http instrumentation library:

go get go.opentelemetry.io/contrib/instrumentation/net/http/otelhttp

Next, use the library to wrap an HTTP handler in your code:

接着，在你的代码中使用这个库来包装 HTTP 处理程序

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 automatically!")
  ctx := r.Context()
  sleepy(ctx)
}

func main() {
  // Wrap your httpHandler function. 包装 httpHandler 函数
  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 configured, this code will:

假设你已经有一个配置好的 Tracer 和 exporter，这个代码将

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 OpenTelemetry registry.

可以在 OpenTelemetry registry 找到可用 instrumentation libraries 的完整列表

Next steps

Instrumentation libraries can do things like generate telemetry data for inbound and outbound HTTP requests, but they don’t instrument your actual application.

检测库（Instrumentation libraries ）可以为 inbound 和 outbound HTTP 请求生成 telemetry data，但它们不检测实际应用程序。

To get richer telemetry data, use manual instrumentation to enrich your telemetry data from instrumentation libraries with instrumentation from your running application.

要获得更丰富的 telemetry data，在应用程序中使用 manual instrumentation 来丰富来自 instrumentation libraries 的 telemetry data .

openTelemetry go instrumentation libraries