tracing

README

opentelemetry

适用 opentelemetry 规范的链路追踪仓库，开发这个仓库的目的是：简化项目中对接链路追踪的代码，并统一搜集行为。 当然这个库比较偏私人定制（参考下面描述的工作内容），因此不具备通用库的特性，因此不推荐直接引用，但是对想要使用 opentelemetry 和二次开发的开发者有参考价值。

本仓库的工作内容：

• 在遵守 opentelemetry 的使用规范上对外提供链路追踪API，避免仓库直接引用 opentelemetry, 减轻使用者负担。
• 允许使用 sentry, otlp 和 jaeger 等后端服务，同时减少使用配置（使用默认配置和内置配置；从环境变量读取）。
• 开发 sentry span-exporter（这部分参考 sentry-exporter ）另外增加了部分改动，这部分会持续维护。
• 对于服务端的常用场景提供了中间件，例如：HTTP（gin）, gRPC，HTTP Client (resty)。

TODO:

• sdk 可用
• 采集堆栈信息
• 跟前端链路打通
• 中间件完成与优化
• 处理代码中 TODO 和 FIXME
• 记录请求和响应（可选）
• 补充测试用例
• 改造 sentryexporter（TraceExporter）记录 StackTrace信息或者给官方提交 PR

Examples

Deploy OpenTelemetry Collector

https://opentelemetry.io/docs/collector/getting-started/

k8s

kubectl apply -f ./.deploy/k8s-otelcol.yaml

Supplement

1. How build you custom collector

For more details, please check out the .build folder.

## install build
go install go.opentelemetry.io/collector/cmd/builder@latest

## write build config
cat > ~/.otelcol-builder.yaml <<EOF
exporters:
  - gomod: "github.com/open-telemetry/opentelemetry-collector-contrib/exporter/alibabacloudlogserviceexporter v0.37.0"
EOF

## execute build command

builder --output-path=.
# or builder --config ~/.otelcol-builder.yaml

2. Architecture of opentelemetry

Reference

• https://github.com/open-telemetry/opentelemetry-collector/tree/main/cmd/builder
• https://github.com/open-telemetry/opentelemetry-collector-contrib/issues/6218

Documentation

Index

• Constants
• Variables
• func MustSetup(opts ...SetupOption) func()
• func SetPropagator(p TraceContextPropagator)
• func Setup(opts ...SetupOption) (shutdown func(), err error)
• func SetupDefault() (shutdown func(), err error)
• type Code
• type SetupOption
  • func WithEnv(env string) SetupOption
  • func WithHostname(hostname string) SetupOption
  • func WithNamespace(namespace string) SetupOption
  • func WithOtlpExporter(endpoint string) SetupOption
  • func WithPodIP(podIP string) SetupOption
  • func WithSampleRate(fraction float64) SetupOption
  • func WithServerName(name string) SetupOption
  • func WithServerVersion(version string) SetupOption
• type Span
  • func SpanFromContext(ctx context.Context) Span
  • func StartSpan(ctx context.Context, operation string, opts ...SpanStartOption) (context.Context, Span)
• type SpanEventOption
  • func WithStackTrace() SpanEventOption
• type SpanStartOption
  • func WithSpanKind(kind spanKind) SpanStartOption
• type TraceContext
  • func SpanContextFromContext(ctx context.Context) *TraceContext
  • func TraceContextFromContext(ctx context.Context) *TraceContext
  • func (tc *TraceContext) IsRemote() bool
  • func (tc *TraceContext) IsValid() bool
  • func (tc *TraceContext) Sampled() bool
• type TraceContextCarrier
  • func NewMapCarrier() TraceContextCarrier
• type TraceContextPropagator
  • func GetPropagator() TraceContextPropagator

Examples

• SetupDefault
• SpanContextFromContext
• SpanFromContext
• StartSpan
• TraceContextFromContext

Constants

const (
	// SpanKindUnspecified is an unspecified SpanKind and is not a valid
	// SpanKind. SpanKindUnspecified should be replaced with SpanKindInternal
	// if it is received.
	SpanKindUnspecified spanKind = 0
	// SpanKindInternal is a SpanKind for a Span that represents an internal
	// operation within an application.
	SpanKindInternal spanKind = 1
	// SpanKindServer is a SpanKind for a Span that represents the operation
	// of handling a request from a client.
	SpanKindServer spanKind = 2
	// SpanKindClient is a SpanKind for a Span that represents the operation
	// of client making a request to a server.
	SpanKindClient spanKind = 3
	// SpanKindProducer is a SpanKind for a Span that represents the operation
	// of a producer sending a message to a message broker. Unlike
	// SpanKindClient and SpanKindServer, there is often no direct
	// relationship between this kind of Span and a SpanKindConsumer kind. A
	// SpanKindProducer Span will end once the message is accepted by the
	// message broker which might not overlap with the processing of that
	// message.
	SpanKindProducer spanKind = 4
	// SpanKindConsumer is a SpanKind for a Span that represents the operation
	// of a consumer receiving a message from a message broker. Like
	// SpanKindProducer Spans, there is often no direct relationship between
	// this Span and the Span that produced the message.
	SpanKindConsumer spanKind = 5
)

const (
	OTLP exporterEnum = "OTLP"
)

Variables

var (
	ErrUnknownExporter   = errors.New("unknown exporterEnum type")
	ErrOtlpEndpointEmpty = errors.New("otlp endpoint could not be empty")
	ErrServerNameEmpty   = errors.New("server name could not be empty")
)

Functions

func MustSetup

func MustSetup(opts ...SetupOption) func()

MustSetup same as Setup but panic if setup encounter any error.

func SetPropagator

func SetPropagator(p TraceContextPropagator)

SetPropagator sets the trace context propagator. if it never called, the default propagator will be used.

func Setup

func Setup(opts ...SetupOption) (shutdown func(), err error)

Setup would only execute once if it is called multiple times. Of course, if setup failed, it would return an error and allows the caller to retry. After setup, open telemetry's sdk has been initialized with TracerProvider and Propagator across processes.

func SetupDefault

func SetupDefault() (shutdown func(), err error)

SetupDefault setup default tracing, using:

OLTP exporter with default endpoint: localhost:4317 or OTEL_COLLECTOR_ENDPOINT; serverName from environment variable: APP_ID, APP_NAME; version from environment variable: APP_VERSION; env from environment variable: RUN_ENV, DEPLOY_ENV; namespace from environment variable: NAMESPACE; sampleRate set 0.2, means 20% of traces will be sampled, or you can set OTEL_SAMPLE_RATE=[0..1.0];

Example

package main

import (
	tracing "github.com/yeqown/opentelemetry-quake"
)

func main() {
	name := "default_or_from_env"
	version := "1.0.0"
	env := "prod"
	ns := "my_namespace"
	otelCollectorEndpoint := "localhost:4317"

	shutdown, err := tracing.Setup(
		tracing.WithServerName(name),
		tracing.WithServerVersion(version),
		tracing.WithEnv(env),
		tracing.WithNamespace(ns),
		tracing.WithOtlpExporter(otelCollectorEndpoint),
		tracing.WithSampleRate(0.2),
	)
	_, _ = shutdown, err
}

Types

type Code

type Code = codes.Code

const (
	// Unset is the default status code.
	Unset Code = 0
	// Error indicates the operation contains an error.
	Error Code = 1
	// OK indicates operation has been validated by an Application developers
	// or Operator to have completed successfully, or contain no error.
	OK Code = 2
)

type SetupOption

type SetupOption interface {
	// contains filtered or unexported methods
}

func WithEnv

func WithEnv(env string) SetupOption

func WithHostname

func WithHostname(hostname string) SetupOption

func WithNamespace

func WithNamespace(namespace string) SetupOption

func WithOtlpExporter

func WithOtlpExporter(endpoint string) SetupOption

func WithPodIP

func WithPodIP(podIP string) SetupOption

func WithSampleRate

func WithSampleRate(fraction float64) SetupOption

func WithServerName

func WithServerName(name string) SetupOption

func WithServerVersion

func WithServerVersion(version string) SetupOption

type Span

type Span interface {
	// SpanContext returns the SpanContext of the span, including the
	// trace ID, span ID, and whether the span is a root span.
	SpanContext() *TraceContext

	// RecordError records a span event capture an error. And it always
	// records stacktrace.
	RecordError(err error, opts ...SpanEventOption)

	// SetTag sets a key value pair on the span. to be used for
	// compatibility with OpenTracing.
	SetTag(key string, value string)

	// SetAttributes sets a key value pair on the span.
	SetAttributes(attributes ...attribute.KeyValue)

	// LogFields sets a key value pair on the span.
	LogFields(event string, attributes ...attribute.KeyValue)

	// SetStatus sets the status of the span. OK, Error, etc.
	SetStatus(code Code, message string)

	// Finish ends the span. same as span.End()
	Finish()

	// End ends the span. same to Finish
	End()
}

Span is a specification for internal tracing client to use.

func SpanFromContext

func SpanFromContext(ctx context.Context) Span

SpanFromContext is alias of otel.SpanFromContext() to avoid importing otel library in you project code.

Example

package main

import (
	"context"
	"fmt"

	tracing "github.com/yeqown/opentelemetry-quake"
)

func main() {
	ctx, sp := tracing.StartSpan(context.Background(), "example")
	defer sp.End()

	internalCall := func(ctx context.Context) {
		// launch a RPC call
		sp2 := tracing.SpanFromContext(ctx)
		sp2.RecordError(fmt.Errorf("encounter an error in internalCall"))
	}

	// pass ctx to another internal call or remote call.
	internalCall(ctx)
}

func StartSpan

func StartSpan(ctx context.Context, operation string, opts ...SpanStartOption) (context.Context, Span)

StartSpan is alias of otel.Tracer("tracerName").Start() to avoid importing otel library in you project code.

Example

package main

import (
	"context"

	tracing "github.com/yeqown/opentelemetry-quake"
)

func main() {
	ctx, sp := tracing.StartSpan(context.Background(), "example")
	defer sp.End()

	remoteCall := func(ctx context.Context) {
		// launch a RPC call
	}

	// pass ctx to another internal call or remote call.
	remoteCall(ctx)
}

type SpanEventOption

type SpanEventOption interface {
	// contains filtered or unexported methods
}

func WithStackTrace

func WithStackTrace() SpanEventOption

type SpanStartOption

type SpanStartOption interface {
	// contains filtered or unexported methods
}

func WithSpanKind

func WithSpanKind(kind spanKind) SpanStartOption

type TraceContext

type TraceContext struct {
	TraceID, SpanID, ParentSpanID string
	// contains filtered or unexported fields
}

TraceContext span 的上下文信息，包含 span 的 traceID 和 spanID.

func SpanContextFromContext

func SpanContextFromContext(ctx context.Context) *TraceContext

Example

package main

import (
	"context"
	"fmt"

	tracing "github.com/yeqown/opentelemetry-quake"
)

func main() {
	ctx, sp := tracing.StartSpan(context.Background(), "example")
	defer sp.End()

	remoteCall := func(ctx context.Context) {
		// launch a RPC call
		sc := tracing.SpanContextFromContext(ctx)
		fmt.Println(sc.TraceID)
	}

	// pass ctx to another internal call or remote call.
	remoteCall(ctx)
}

func TraceContextFromContext

func TraceContextFromContext(ctx context.Context) *TraceContext

TraceContextFromContext 从 ctx 中尝试获取 TraceContext 方便日志记录

Example

package main

import (
	"context"
	"fmt"

	tracing "github.com/yeqown/opentelemetry-quake"
)

func main() {
	ctx, sp := tracing.StartSpan(context.Background(), "example")
	defer sp.End()

	remoteCall := func(ctx context.Context) {
		// launch a RPC call
		tc := tracing.TraceContextFromContext(ctx)
		fmt.Println(tc.TraceID)
	}

	// pass ctx to another internal call or remote call.
	remoteCall(ctx)
}

func (*TraceContext) IsRemote

func (tc *TraceContext) IsRemote() bool

func (*TraceContext) IsValid

func (tc *TraceContext) IsValid() bool

func (*TraceContext) Sampled

func (tc *TraceContext) Sampled() bool

type TraceContextCarrier

type TraceContextCarrier interface {
	Get(key string) string
	Set(key, value string)
}

TraceContextCarrier is the type of the carrier to be used for propagating the trace context across processes.

func NewMapCarrier

func NewMapCarrier() TraceContextCarrier

NewMapCarrier returns a new TraceContextCarrier that wraps a map[string]string.

type TraceContextPropagator

type TraceContextPropagator interface {
	Inject(ctx context.Context, carrier TraceContextCarrier)
	Extract(ctx context.Context, carrier TraceContextCarrier) context.Context
}

TraceContextPropagator is the type of the propagator to be used for propagating the trace context across processes.

func GetPropagator

func GetPropagator() TraceContextPropagator

GetPropagator returns the trace context propagator.