OpenTelemetry

Hertz provides openTelemetry capabilities.

OpenTelemetry is an open source observability framework from CNCF that consist of a series of tools, APIs and SDKs, and it enables IT teams to detect, generate, collect, and export remote monitoring data for analysis and understanding of software performance and behavior.

The obs-opentelemetry extension is available in the hertz-contrib, which allows hertz to integrate OpenTelemetry with a simple setup.

Features

Tracing

Tracing provides a full view of the entire lifecycle from the time a request is received to the time it is processed.

What obs-opentelemetry implements:

  • Support server and client hertz http tracing
  • Support automatic transparent transmission of peer service through http headers

Examples:

Server:

package main

import (
	"github.com/cloudwego/hertz/pkg/app/server"
	hertztracing "github.com/hertz-contrib/obs-opentelemetry/tracing"
)

func main() {
	tracer, cfg := hertztracing.NewServerTracer()
	h := server.Default(tracer)
	h.Use(hertztracing.ServerMiddleware(cfg))
	// ...
	h.Spin()
}

Client:

package main

import (
	hertztracing "github.com/hertz-contrib/obs-opentelemetry/tracing"
	"github.com/cloudwego/hertz/pkg/app/client"
)

func main() {
	c, _ := client.NewClient()
	c.Use(hertztracing.ClientMiddleware())
	// ...
}

Code

Tracing Options

函数名描述
WithTextMapPropagatorConfigures propagation.TextMapPropagator
WithCustomResponseHandlerConfigures Custom ResponseHandler
WithClientHttpRouteFormatterConfigure the custom formatting function for the ‘http_route’ dimension of the client-side metric
WithServerHttpRouteFormatterConfigure the custom formatting function for the ‘http_route’ dimension of the server-side metric
WithShouldIgnoreConfigure a conditional function to determine whether the generation of link data should be ignored

Metric

Metric contains a wide variety of methods and implementations.

Metric includes tracing samples and automatically associates metrics with them. Manually linking metrics to tracing is often a tedious and error-prone task, and OpenTelemetry automating it will save Ops a lot of time.

What obs-opentelemetry implements:

  • Support hertz http metrics: [Rate, Errors, Duration]
  • Support service topology map metrics [Service Topology Map]
  • Support go runtime metrics

More

Logging

OpenTelemetry combines a highly structured logging API with a high-speed log processing system. Existing logging APIs can be connected to OpenTelemetry to avoid re-measurement of applications.

What obs-opentelemetry implements:

  • Extend hertz logger based on logrus
  • Implement tracing auto associated logs
import (
    hertzlogrus "github.com/hertz-contrib/obs-opentelemetry/logging/logrus"
)

func main()  {
    hlog.SetLogger(hertzlogrus.NewLogger())
    // ...
}

Code

Provider

  • Out-of-the-box default opentelemetry provider
  • Support setting via environment variables:

Examples:

package main

import (
	"context"

	hertztracing "github.com/hertz-contrib/obs-opentelemetry/tracing"
	"github.com/cloudwego/hertz/pkg/app/server"
	"github.com/hertz-contrib/obs-opentelemetry/provider"
)

func main() {
	serviceName := "echo"

	p := provider.NewOpenTelemetryProvider(
		provider.WithServiceName(serviceName),
		provider.WithExportEndpoint("localhost:4317"),
		provider.WithInsecure(),
	)
	defer p.Shutdown(context.Background())

	tracer, cfg := hertztracing.NewServerTracer()
	h := server.Default(tracer)
	h.Use(hertztracing.ServerMiddleware(cfg))

	// ...
	h.Spin()
}

Code

Provider Options

FunctionDescription
WithServiceNameConfigure the resource properties of service.name
WithDeploymentEnvironmentConfigure the resource properties of deployment.environment
WithServiceNamespaceConfigure the resource properties of service.namespace
WithResourceAttributesConfigure the resource properties
WithResourceConfigure resources (resource.Resource)
WithEnableTracingEnable tracing
WithEnableMetricsEnable metrics
WithTextMapPropagatorConfigure propagation.TextMapPropagator
WithResourceDetectorConfigure resource.Detector
WithHeadersConfigure the gRPC request header for exporting telemetry data
WithInsecureConfigure whether to use secure authentication for exported gRPC clients
WithEnableCompressionConfigure whether to enable gzip transport compression
WithSamplerConfigure Trace sampler
WithSdkTracerProviderConfigure sdktrace.TracerProvider
WithMeterProviderConfigure metric.MeterProvider

Full Examples

For a full usage: example