Zipkin Go

用于Go的Zipkin追踪器库。「Zipkin tracer library for go」

Github stars Tracking Chart

Zipkin Go 库

Zipkin Go 是 Zipkin 的官方 Go 跟踪器实现,由 OpenZipkin 社区支持。

包组织

zipkin-go 的构建考虑到了 OpenZipkin 社区甚至是第三方的互操作性,该库由几个包组成。

主要的跟踪实现可以在这个资源库的根文件夹中找到。不被认为是核心实现的可重用部分或被认为有利于他人使用的部分被放置在这个资源库中自己的包中。

model

这个库实现了 Zipkin V2 Span Model,它可以在 model 包中找到。它包含一个与 Zipkin V2 API 兼容的 Go 数据模型,并能自动处理、解析和(去)序列化为官方 Zipkin V2 收集器使用的所需 JSON 表示。

propagation

Propagation 包 和 B3 子包持有参与跟踪的服务之间 propagating SpanContext(跨度标识符和采样标志)的逻辑。目前 Zipkin B3 传播支持 HTTP 和 GRPC。

middleware

middleware 子包包含官方支持的中间件处理程序和追踪包装器。

http

提供了一个易于使用的 http.Handler 中间件,用于追踪服务器端的请求。这使得人们可以在使用标准库服务器的应用程序中使用这个中间件,以及大多数可用的更高级别的框架。一些框架会有自己的工具和中间件,以更好地映射他们的生态系统。

对于 HTTP 客户端操作,NewTransport 可以返回一个 http.RoundTripper 的实现,它可以包裹标准的 http.Client 的 Transport 或自定义提供的 Transport,并添加每个请求的追踪。由于 HTTP 请求可以有一个或多个重定向,建议总是用 Span 来包围 HTTP 客户端调用,无论是在 *http.Client 调用层面还是在父函数层面。

为了方便起见,我们提供了 NewClient,它返回一个嵌入 *http.Client 的 HTTP 客户端,并在调用 DoWithAppSpan() 方法时在 HTTP 调用周围提供一个应用跨度。

grpc

提供了易于使用的 grpc.StatsHandler 中间件来追踪 gRPC 服务器和客户端请求。

对于一个服务器,在调用 NewServer 时传递 NewServerHandler,例如:

import (
    "google.golang.org/grpc"
    zipkingrpc "github.com/openzipkin/zipkin-go/middleware/grpc"
)

server = grpc.NewServer(grpc.StatsHandler(zipkingrpc.NewServerHandler(tracer)))

对于一个客户端,在调用 Dial 时,传递 NewClientHandler,例如:

import (
    "google.golang.org/grpc"
    zipkingrpc "github.com/openzipkin/zipkin-go/middleware/grpc"
)

conn, err = grpc.Dial(addr, grpc.WithStatsHandler(zipkingrpc.NewClientHandler(tracer)))

reporter

Reporter 包持有各种 Reporter 实现所使用的接口。它被导出到自己的包中,因为第三方可以在自己的库中使用这些 Reporter 包,以导出到 Zipkin 生态系统中。zipkin-go 追踪器也使用该接口来接受第三方 Reporter 实现。

HTTP 报告器

Zipkin 用户最常使用的 Reporter 类型,通过 HTTP 使用 JSON 向 Zipkin 服务器传输 Spans。Reporter 持有一个缓冲区,以异步方式向后端报告。

Kafka 报告器

高性能 Reporter,使用 Kafka Producer 消费 JSON V2 Spans,将 Spans 传送到 Zipkin 服务器。该报告者使用下面的 Sarama 异步生产者

使用方法和例子

HTTP 服务器实例


Main metrics

Overview
Name With Owneropenzipkin/zipkin-go
Primary LanguageGo
Program languageGo (Language Count: 2)
PlatformLinux, Mac, Windows
License:Apache License 2.0
所有者活动
Created At2016-09-27 12:19:53
Pushed At2025-02-06 03:11:42
Last Commit At2025-02-06 14:11:42
Release Count19
Last Release Namev0.4.3 (Posted on )
First Release Namev0.1.0 (Posted on )
用户参与
Stargazers Count614
Watchers Count21
Fork Count116
Commits Count296
Has Issues Enabled
Issues Count75
Issue Open Count6
Pull Requests Count116
Pull Requests Open Count7
Pull Requests Close Count29
项目设置
Has Wiki Enabled
Is Archived
Is Fork
Is Locked
Is Mirror
Is Private

Zipkin Library for Go

GHA
codecov
Go Report Card
GoDoc
Gitter chat
Sourcegraph

Zipkin Go is the official Go Tracer / Tracing implementation for Zipkin,
supported by the OpenZipkin community.

package organization

zipkin-go is built with interoperability in mind within the OpenZipkin
community and even 3rd parties, the library consists of several packages.

The main tracing implementation can be found in the root folder of this
repository. Reusable parts not considered core implementation or deemed
beneficiary for usage by others are placed in their own packages within this
repository.

model

This library implements the Zipkin V2 Span Model which is available in the model
package. It contains a Go data model compatible with the Zipkin V2 API and can
automatically sanitize, parse and (de)serialize to and from the required JSON
representation as used by the official Zipkin V2 Collectors.

propagation

The propagation package and B3 subpackage hold the logic for propagating
SpanContext (span identifiers and sampling flags) between services participating
in traces. Currently Zipkin B3 Propagation is supported for HTTP and GRPC.

middleware

The middleware subpackages contain officially supported middleware handlers and
tracing wrappers.

http

An easy to use http.Handler middleware for tracing server side requests is
provided. This allows one to use this middleware in applications using
standard library servers as well as most available higher level frameworks. Some
frameworks will have their own instrumentation and middleware that maps better
for their ecosystem.

For HTTP client operations NewTransport can return a http.RoundTripper
implementation that can either wrap the standard http.Client's Transport or a
custom provided one and add per request tracing. Since HTTP Requests can have
one or multiple redirects it is advisable to always enclose HTTP Client calls
with a Span either around the *http.Client call level or parent function
level.

For convenience NewClient is provided which returns a HTTP Client which embeds
*http.Client and provides an application span around the HTTP calls when
calling the DoWithAppSpan() method.

grpc

Easy to use grpc.StatsHandler middleware are provided for tracing gRPC server
and client requests.

For a server, pass NewServerHandler when calling NewServer, e.g.,

import (
	"google.golang.org/grpc"
	zipkingrpc "github.com/openzipkin/zipkin-go/middleware/grpc"
)

server = grpc.NewServer(grpc.StatsHandler(zipkingrpc.NewServerHandler(tracer)))

For a client, pass NewClientHandler when calling Dial, e.g.,

import (
	"google.golang.org/grpc"
	zipkingrpc "github.com/openzipkin/zipkin-go/middleware/grpc"
)

conn, err = grpc.Dial(addr, grpc.WithStatsHandler(zipkingrpc.NewClientHandler(tracer)))

reporter

The reporter package holds the interface which the various Reporter
implementations use. It is exported into its own package as it can be used by
3rd parties to use these Reporter packages in their own libraries for exporting
to the Zipkin ecosystem. The zipkin-go tracer also uses the interface to
accept 3rd party Reporter implementations.

HTTP Reporter

Most common Reporter type used by Zipkin users transporting Spans to the Zipkin
server using JSON over HTTP. The reporter holds a buffer and reports to the
backend asynchronously.

Kafka Reporter

High performance Reporter transporting Spans to the Zipkin server using a Kafka
Producer digesting JSON V2 Spans. The reporter uses the
Sarama async producer
underneath.

usage and examples

HTTP Server Example