快速入门
本页面将向您展示如何在Go中使用OpenTelemetry入门。
您将了解如何手动为一个简单的应用程序提供仪表支持，以便在控制台上发出[跟踪][]和[度量][]。
先决条件
确保在本地安装了以下软件：
示例应用程序
以下示例使用基本的net/http应用程序。如果您没有使用net/http，没关系 —— 您也可以使用其他Web框架，如Gin和Echo，与OpenTelemetry Go一起使用。有关受支持的框架的完整列表，请参阅 registry。
有关更详细的示例，请参阅 examples。
设置
首先，在新目录中设置一个go.mod文件：
go mod init dice
创建并启动一个HTTP服务器
在同一个文件夹中，创建一个名为main.go的文件，并将以下代码添加到文件中：
package main
import (
"log"
"net/http"
)
func main() {
http.HandleFunc("/rolldice", rolldice)
log.Fatal(http.ListenAndServe(":8080", nil))
}
创建另一个名为rolldice.go的文件，并将以下代码添加到文件中：
package main
import (
"io"
"log"
"math/rand"
"net/http"
"strconv"
)
func rolldice(w http.ResponseWriter, r *http.Request) {
roll := 1 + rand.Intn(6)
resp := strconv.Itoa(roll) + "\n"
if _, err := io.WriteString(w, resp); err != nil {
log.Printf("写入失败：%v\n", err)
}
}
使用以下命令构建并运行应用程序：
go run .
在您的Web浏览器中打开http://localhost:8080/rolldice，以确保它正常工作。
添加OpenTelemetry仪表支持
现在我们将介绍如何向示例应用程序添加OpenTelemetry的仪表支持。如果您使用自己的应用程序，您可以按照以下步骤进行操作，只需注意您的代码可能有所不同。
添加依赖项
安装以下包：
go get "go.opentelemetry.io/otel" \
"go.opentelemetry.io/otel/exporters/stdout/stdoutmetric" \
"go.opentelemetry.io/otel/exporters/stdout/stdouttrace" \
"go.opentelemetry.io/otel/propagation" \
"go.opentelemetry.io/otel/sdk/metric" \
"go.opentelemetry.io/otel/sdk/resource" \
"go.opentelemetry.io/otel/sdk/trace" \
"go.opentelemetry.io/otel/semconv/v1.21.0" \
"go.opentelemetry.io/contrib/instrumentation/net/http/otelhttp"
这将安装OpenTelemetry SDK组件和net/http仪表。
如果要为其他网络请求库提供仪表支持，您需要安装相应的仪表库。有关更多信息，请参阅libraries。
初始化OpenTelemetry SDK
首先，我们将初始化OpenTelemetry SDK。这对于任何导出遥测数据的应用程序都是_必须_的。
创建一个名为otel.go的文件，其中包含OpenTelemetry SDK启动代码：
package main
import (
"context"
"errors"
"time"
"go.opentelemetry.io/otel"
"go.opentelemetry.io/otel/exporters/stdout/stdoutmetric"
"go.opentelemetry.io/otel/exporters/stdout/stdouttrace"
"go.opentelemetry.io/otel/propagation"
"go.opentelemetry.io/otel/sdk/metric"
"go.opentelemetry.io/otel/sdk/resource"
"go.opentelemetry.io/otel/sdk/trace"
semconv "go.opentelemetry.io/otel/semconv/v1.21.0"
)
// setupOTelSDK 引导OpenTelemetry管道。
// 如果此函数不返回错误，请确保调用shutdown函数以进行适当的清理。
func setupOTelSDK(ctx context.Context, serviceName, serviceVersion string) (shutdown func(context.Context) error, err error) {
var shutdownFuncs []func(context.Context) error
// shutdown函数调用通过shutdownFuncs注册的清理函数，并将错误连接在一起。
// 每个注册的清理函数将被调用一次。
shutdown = func(ctx context.Context) error {
var err error
for _, fn := range shutdownFuncs {
err = errors.Join(err, fn(ctx))
}
shutdownFuncs = nil
return err
}
// handleErr函数调用shutdown函数以进行清理，并确保返回所有错误。
handleErr := func(inErr error) {
err = errors.Join(inErr, shutdown(ctx))
}
// 设置资源。
res, err := newResource(serviceName, serviceVersion)
if err != nil {
handleErr(err)
return
}
// 设置传播器。
prop := newPropagator()
otel.SetTextMapPropagator(prop)
// 设置跟踪提供程序。
tracerProvider, err := newTraceProvider(res)
if err != nil {
handleErr(err)
return
}
shutdownFuncs = append(shutdownFuncs, tracerProvider.Shutdown)
otel.SetTracerProvider(tracerProvider)
// 设置度量仪提供程序。
meterProvider, err := newMeterProvider(res)
if err != nil {
handleErr(err)
return
}
shutdownFuncs = append(shutdownFuncs, meterProvider.Shutdown)
otel.SetMeterProvider(meterProvider)
return
}
func newResource(serviceName, serviceVersion string) (*resource.Resource, error) {
return resource.Merge(resource.Default(),
resource.NewWithAttributes(semconv.SchemaURL,
semconv.ServiceName(serviceName),
semconv.ServiceVersion(serviceVersion),
))
}
func newPropagator() propagation.TextMapPropagator {
return propagation.NewCompositeTextMapPropagator(
propagation.TraceContext{},
propagation.Baggage{},
)
}
func newTraceProvider(res *resource.Resource) (*trace.TracerProvider, error) {
traceExporter, err := stdouttrace.New(
stdouttrace.WithPrettyPrint())
if err != nil {
return nil, err
}
traceProvider := trace.NewTracerProvider(
trace.WithBatcher(traceExporter,
// 默认是5秒，这里设置为1秒以演示目的。
trace.WithBatchTimeout(time.Second)),
trace.WithResource(res),
)
return traceProvider, nil
}
func newMeterProvider(res *resource.Resource) (*metric.MeterProvider, error) {
metricExporter, err := stdoutmetric.New()
if err != nil {
return nil, err
}
meterProvider := metric.NewMeterProvider(
metric.WithResource(res),
metric.WithReader(metric.NewPeriodicReader(metricExporter,
// 默认是1分钟，这里设置为3秒以演示目的。
metric.WithInterval(3*time.Second))),
)
return meterProvider, nil
}
如果您只使用跟踪或度量仪表，您可以省略相应的TracerProvider或MeterProvider初始化代码。
为HTTP服务器提供仪表支持
现在，我们已经初始化了OpenTelemetry SDK，可以为HTTP服务器提供仪表支持。
修改main.go，包括代码来设置OpenTelemetry SDK并使用otelhttp仪表库为HTTP服务器提供仪表支持：
package main
import (
"context"
"errors"
"log"
"net"
"net/http"
"os"
"os/signal"
"time"
"go.opentelemetry.io/contrib/instrumentation/net/http/otelhttp"
)
func main() {
if err := run(); err != nil {
log.Fatalln(err)
}
}
func run() (err error) {
// 优雅地处理SIGINT（CTRL+C）。
ctx, stop := signal.NotifyContext(context.Background(), os.Interrupt)
defer stop()
// 设置OpenTelemetry。
serviceName := "dice"
serviceVersion := "0.1.0"
otelShutdown, err := setupOTelSDK(ctx, serviceName, serviceVersion)
if err != nil {
return err
}
// 适当处理关闭，以避免泄漏。
defer func() {
err = errors.Join(err, otelShutdown(context.Background()))
}()
// 启动HTTP服务器。
srv := &http.Server{
Addr: ":8080",
BaseContext: func(_ net.Listener) context.Context { return ctx },
ReadTimeout: time.Second,
WriteTimeout: 10 * time.Second,
Handler: newHTTPHandler(),
}
srvErr := make(chan error, 1)
go func() {
srvErr <- srv.ListenAndServe()
}()
// 等待中断。
select {
case err = <-srvErr:
// 启动HTTP服务器时发生错误。
return err
case <-ctx.Done():
// 等待第一次CTRL+C。
// 尽快停止接收信号通知。
stop()
}
// 当调用Shutdown时，ListenAndServe会立即返回ErrServerClosed。
err = srv.Shutdown(context.Background())
return err
}
func newHTTPHandler() http.Handler {
mux := http.NewServeMux()
// handleFunc是mux.HandleFunc的替代品
// 它将处理程序的HTTP仪表与模式作为http.route一起增强。
handleFunc := func(pattern string, handlerFunc func(http.ResponseWriter, *http.Request)) {
// 为HTTP仪表配置“http.route”。
handler := otelhttp.WithRouteTag(pattern, http.HandlerFunc(handlerFunc))
mux.Handle(pattern, handler)
}
// 注册处理程序。
handleFunc("/rolldice", rolldice)
// 为整个服务器添加HTTP仪表。
handler := otelhttp.NewHandler(mux, "/")
return handler
}
添加自定义仪表支持
仪表库在系统的边缘捕获遥测数据，如传入和传出的HTTP请求，但不捕获应用程序内部的运行情况。为此，您需要编写一些自定义的手动仪表支持。
修改rolldice.go，使用OpenTelemetry API包括自定义仪表支持的代码：
package main
import (
"io"
"log"
"math/rand"
"net/http"
"strconv"
"go.opentelemetry.io/otel"
"go.opentelemetry.io/otel/attribute"
"go.opentelemetry.io/otel/metric"
)
var (
tracer = otel.Tracer("rolldice")
meter = otel.Meter("rolldice")
rollCnt metric.Int64Counter
)
func init() {
var err error
rollCnt, err = meter.Int64Counter("dice.rolls",
metric.WithDescription("通过骰子点数计算投掷次数"),
metric.WithUnit("{roll}"))
if err != nil {
panic(err)
}
}
func rolldice(w http.ResponseWriter, r *http.Request) {
ctx, span := tracer.Start(r.Context(), "roll")
defer span.End()
roll := 1 + rand.Intn(6)
// 将自定义属性添加到span和counter。
rollValueAttr := attribute.Int("roll.value", roll)
span.SetAttributes(rollValueAttr)
rollCnt.Add(ctx, 1, metric.WithAttributes(rollValueAttr))
resp := strconv.Itoa(roll) + "\n"
if _, err := io.WriteString(w, resp); err != nil {
log.Printf("写入失败：%v\n", err)
}
}
请注意，如果您只使用跟踪或度量仪表，可以省略用于仪表化其他类型遥测的代码。
运行应用程序
使用以下命令构建并运行应用程序：
go mod tidy
go run .
在您的Web浏览器中打开http://localhost:8080/rolldice。当您向服务器发送请求时，您将在控制台上看到生成的跟踪中的两个跨度。由仪表库生成的跨度跟踪了对/rolldice路由的请求的生命周期。名为 roll 的跨度是手动创建的，并且是前面提到的跨度的子跨度。
查看示例输出
{
"Name": "roll",
"SpanContext": {
"TraceID": "829fb7ceb787403c96eac3caf285c965",
"SpanID": "8b6b408b6c1a35e5",
"TraceFlags": "01",
"TraceState": "",
"Remote": false
},
"Parent": {
"TraceID": "829fb7ceb787403c96eac3caf285c965",
"SpanID": "612be4bbdf450de6",
"TraceFlags": "01",
"TraceState": "",
"Remote": false
},
"SpanKind": 1,
"StartTime": "2023-09-25T12:42:06.177119576+02:00",
"EndTime": "2023-09-25T12:42:06.177136776+02:00",
"Attributes": [
{
"Key": "roll.value",
"Value": {
"Type": "INT64",
"Value": 6
}
}
],
"Events": null,
"Links": null,
"Status": {
"Code": "Unset",
"Description": ""
},
"DroppedAttributes": 0,
"DroppedEvents": 0,
"DroppedLinks": 0,
"ChildSpanCount": 0,
"Resource": [
{
"Key": "service.name",
"Value": {
"Type": "STRING",
"Value": "dice"
}
},
{
"Key": "service.version",
"Value": {
"Type": "STRING",
"Value": "0.1.0"
}
},
{
"Key": "telemetry.sdk.language",
"Value": {
"Type": "STRING",
"Value": "go"
}
},
{
"Key": "telemetry.sdk.name",
"Value": {
"Type": "STRING",
"Value": "opentelemetry"
}
},
{
"Key": "telemetry.sdk.version",
"Value": {
"Type": "STRING",
"Value": "1.19.0-rc.1"
}
}
],
"InstrumentationLibrary": {
"Name": "rolldice",
"Version": "",
"SchemaURL": ""
}
}
{
"Name": "/",
"SpanContext": {
"TraceID": "829fb7ceb787403c96eac3caf285c965",
"SpanID": "612be4bbdf450de6",
"TraceFlags": "01",
"TraceState": "",
"Remote": false
},
"Parent": {
"TraceID": "00000000000000000000000000000000",
"SpanID": "0000000000000000",
"TraceFlags": "00",
"TraceState": "",
"Remote": false
},
"SpanKind": 2,
"StartTime": "2023-09-25T12:42:06.177071077+02:00",
"EndTime": "2023-09-25T12:42:06.177158076+02:00",
"Attributes": [
{
"Key": "http.method",
"Value": {
"Type": "STRING",
"Value": "GET"
}
},
{
"Key": "http.scheme",
"Value": {
"Type": "STRING",
"Value": "http"
}
},
{
"Key": "http.flavor",
"Value": {
"Type": "STRING",
"Value": "1.1"
}
},
{
"Key": "net.host.name",
"Value": {
"Type": "STRING",
"Value": "localhost"
}
},
{
"Key": "net.host.port",
"Value": {
"Type": "INT64",
"Value": 8080
}
},
{
"Key": "net.sock.peer.addr",
"Value": {
"Type": "STRING",
"Value": "::1"
}
},
{
"Key": "net.sock.peer.port",
"Value": {
"Type": "INT64",
"Value": 49046
}
},
{
"Key": "http.user_agent",
"Value": {
"Type": "STRING",
"Value": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/117.0.0.0 Safari/537.36"
}
},
{
"Key": "http.route",
"Value": {
"Type": "STRING",
"Value": "/rolldice"
}
},
{
"Key": "http.wrote_bytes",
"Value": {
"Type": "INT64",
"Value": 2
}
},
{
"Key": "http.status_code",
"Value": {
"Type": "INT64",
"Value": 200
}
}
],
"Events": null,
"Links": null,
"Status": {
"Code": "Unset",
"Description": ""
},
"DroppedAttributes": 0,
"DroppedEvents": 0,
"DroppedLinks": 0,
"ChildSpanCount": 1,
"Resource": [
{
"Key": "service.name",
"Value": {
"Type": "STRING",
"Value": "dice"
}
},
{
"Key": "service.version",
"Value": {
"Type": "STRING",
"Value": "0.1.0"
}
},
{
"Key": "telemetry.sdk.language",
"Value": {
"Type": "STRING",
"Value": "go"
}
},
{
"Key": "telemetry.sdk.name",
"Value": {
"Type": "STRING",
"Value": "opentelemetry"
}
},
{
"Key": "telemetry.sdk.version",
"Value": {
"Type": "STRING",
"Value": "1.19.0-rc.1"
}
}
],
"InstrumentationLibrary": {
"Name": "go.opentelemetry.io/contrib/instrumentation/net/http/otelhttp",
"Version": "0.44.0",
"SchemaURL": ""
}
}
刷新http://localhost:8080/rolldice页面几次，然后等待一段时间或终止应用程序，你将会在控制台输出中看到指标信息。你会看到dice.rolls指标被输出到控制台，每种骰子点数的计数值都被单独显示，还会有由仪表化库生成的HTTP指标。
查看示例输出
{
"Resource": [
{
"Key": "service.name",
"Value": {
"Type": "STRING",
"Value": "dice"
}
},
{
"Key": "service.version",
"Value": {
"Type": "STRING",
"Value": "0.1.0"
}
},
{
"Key": "telemetry.sdk.language",
"Value": {
"Type": "STRING",
"Value": "go"
}
},
{
"Key": "telemetry.sdk.name",
"Value": {
"Type": "STRING",
"Value": "opentelemetry"
}
},
{
"Key": "telemetry.sdk.version",
"Value": {
"Type": "STRING",
"Value": "1.19.0-rc.1"
}
}
],
"ScopeMetrics": [
{
"Scope": {
"Name": "rolldice",
"Version": "",
"SchemaURL": ""
},
"Metrics": [
{
"Name": "dice.rolls",
"Description": "每个点数的骰子滚动次数",
"Unit": "{roll}",
"Data": {
"DataPoints": [
{
"Attributes": [
{
"Key": "roll.value",
"Value": {
"Type": "INT64",
"Value": 1
}
}
],
"StartTime": "2023-09-25T12:42:04.279204638+02:00",
"Time": "2023-09-25T12:42:15.482694258+02:00",
"Value": 4
},
{
"Attributes": [
{
"Key": "roll.value",
"Value": {
"Type": "INT64",
"Value": 5
}
}
],
"StartTime": "2023-09-25T12:42:04.279204638+02:00",
"Time": "2023-09-25T12:42:15.482694258+02:00",
"Value": 3
},
{
"Attributes": [
{
"Key": "roll.value",
"Value": {
"Type": "INT64",
"Value": 3
}
}
],
"StartTime": "2023-09-25T12:42:04.279204638+02:00",
"Time": "2023-09-25T12:42:15.482694258+02:00",
"Value": 4
},
{
"Attributes": [
{
"Key": "roll.value",
"Value": {
"Type": "INT64",
"Value": 2
}
}
],
"StartTime": "2023-09-25T12:42:04.279204638+02:00",
"Time": "2023-09-25T12:42:15.482694258+02:00",
"Value": 2
},
{
"Attributes": [
{
"Key": "roll.value",
"Value": {
"Type": "INT64",
"Value": 6
}
}
],
"StartTime": "2023-09-25T12:42:04.279204638+02:00",
"Time": "2023-09-25T12:42:15.482694258+02:00",
"Value": 5
},
{
"Attributes": [
{
"Key": "roll.value",
"Value": {
"Type": "INT64",
"Value": 4
}
}
],
"StartTime": "2023-09-25T12:42:04.279204638+02:00",
"Time": "2023-09-25T12:42:15.482694258+02:00",
"Value": 9
}
],
"Temporality": "CumulativeTemporality",
"IsMonotonic": true
}
}
]
},
{
"Scope": {
"Name": "go.opentelemetry.io/contrib/instrumentation/net/http/otelhttp",
"Version": "0.44.0",
"SchemaURL": ""
},
"Metrics": [
{
"Name": "http.server.request_content_length",
"Description": "",
"Unit": "",
"Data": {
"DataPoints": [
{
"Attributes": [
{
"Key": "http.flavor",
"Value": {
"Type": "STRING",
"Value": "1.1"
}
},
{
"Key": "http.method",
"Value": {
"Type": "STRING",
"Value": "GET"
}
},
{
"Key": "http.route",
"Value": {
"Type": "STRING",
"Value": "/rolldice"
}
},
{
"Key": "http.scheme",
"Value": {
"Type": "STRING",
"Value": "http"
}
},
{
"Key": "http.status_code",
"Value": {
"Type": "INT64",
"Value": 200
}
},
{
"Key": "net.host.name",
"Value": {
"Type": "STRING",
"Value": "localhost"
}
},
{
"Key": "net.host.port",
"Value": {
"Type": "INT64",
"Value": 8080
}
}
],
"StartTime": "2023-09-25T12:42:04.279212238+02:00",
"Time": "2023-09-25T12:42:15.482695758+02:00",
"Value": 0
}
],
"Temporality": "CumulativeTemporality",
"IsMonotonic": true
}
},
{
"Name": "http.server.response_content_length",
"Description": "",
"Unit": "",
"Data": {
"DataPoints": [
{
"Attributes": [
{
"Key": "http.flavor",
"Value": {
"Type": "STRING",
"Value": "1.1"
}
},
{
"Key": "http.method",
"Value": {
"Type": "STRING",
"Value": "GET"
}
},
{
"Key": "http.route",
"Value": {
"Type": "STRING",
"Value": "/rolldice"
}
},
{
"Key": "http.scheme",
"Value": {
"Type": "STRING",
"Value": "http"
}
},
{
"Key": "http.status_code",
"Value": {
"Type": "INT64",
"Value": 200
}
},
{
"Key": "net.host.name",
"Value": {
"Type": "STRING",
"Value": "localhost"
}
},
{
"Key": "net.host.port",
"Value": {
"Type": "INT64",
"Value": 8080
}
}
],
"StartTime": "2023-09-25T12:42:04.279214438+02:00",
"Time": "2023-09-25T12:42:15.482696158+02:00",
"Value": 54
}
],
"Temporality": "CumulativeTemporality",
"IsMonotonic": true
}
},
{
"Name": "http.server.duration",
"Description": "",
"Unit": "",
"Data": {
"DataPoints": [
{
"Attributes": [
{
"Key": "http.flavor",
"Value": {
"Type": "STRING",
"Value": "1.1"
}
},
{
"Key": "http.method",
"Value": {
"Type": "STRING",
"Value": "GET"
}
},
{
"Key": "http.route",
"Value": {
"Type": "STRING",
"Value": "/rolldice"
}
},
{
"Key": "http.scheme",
"Value": {
"Type": "STRING",
"Value": "http"
}
},
{
"Key": "http.status_code",
"Value": {
"Type": "INT64",
"Value": 200
}
},
{
"Key": "net.host.name",
"Value": {
"Type": "STRING",
"Value": "localhost"
}
},
{
"Key": "net.host.port",
"Value": {
"Type": "INT64",
"Value": 8080
}
}
],
"StartTime": "2023-09-25T12:42:04.279219438+02:00",
"Time": "2023-09-25T12:42:15.482697158+02:00",
"Count": 27,
"Bounds": [
0, 5, 10, 25, 50, 75, 100, 250, 500, 750, 1000, 2500, 5000,
7500, 10000
],
"BucketCounts": [
0, 27, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0
],
"Min": {},
"Max": {},
"Sum": 2.1752759999999993
}
],
"Temporality": "CumulativeTemporality"
}
}
]
}
]
}
下一步
要了解有关仪表化代码的更多信息，请参考手动仪表化文档。
你还需要配置适当的导出器来将你的遥测数据导出到一个或多个遥测后端。
如果你想探索一个更复杂的示例，请查看OpenTelemetry Demo，其中包括基于Go的结账服务、产品目录服务和会计服务。
最后修改 December 13, 2023: improve glossary translation (46f8201b)