echootelmetrics

README

echo-otel-metrics

this is an opentelemetry metrics middleware for echo http framework.

it addd a custom opentelemetry metrics middleware echootelmetrics to echo framework, and setup a prometheus exporter endpoint at /metrics.

from v2 version, this middleware follows the Semantic Conventions for HTTP Metrics spec.

and the metrics names are NOT compatible with echo official prometheus middleware any more.

• HTTP Server
  • Metric: http.server.request.duration
  • Metric: http.server.active_requests
  • Metric: http.server.request.size
  • Metric: http.server.response.size
• HTTP Client
  • Metric: http.client.request.duration
  • Metric: http.client.request.size
  • Metric: http.client.response.size

https://github.com/open-telemetry/semantic-conventions/blob/main/docs/http/http-metrics.md

usage

import (
    "github.com/ttys3/echo-otel-metrics/v2"
)

	prom := echootelmetrics.New(echootelmetrics.MiddlewareConfig{
		Subsystem:      serviceName,
		Skipper:        URLSkipper,
		ServiceVersion: "v0.1.0",
	})
	e := echo.New()
	// Enable metrics middleware
	e.Use(prom.NewMiddleware()
	e.GET("/metrics", prom.NewHandler())

warning

status https://opentelemetry.io/docs/instrumentation/go/

the Metrics component for OpenTelemetry Go is Stable now!

see https://github.com/open-telemetry/opentelemetry-go/releases/tag/v1.16.0

prometheus related

Unit 1

https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/compatibility/prometheus_and_openmetrics.md#metric-metadata-1

The Unit of an OTLP metric point SHOULD be converted to the equivalent unit in Prometheus when possible. This includes:

• Special case: Converting "1" to "ratio".

https://github.com/open-telemetry/opentelemetry-collector-contrib/issues/10554 Metrics about offset should use an empty unit. Unit 1 must be used only for fractions and ratios.

https://github.com/open-telemetry/opentelemetry-specification/blob/ce360a26894271fa9a2b0c846a78d97d277e4183/specification/metrics/semantic_conventions/README.md#instrument-units

Instrument Units

Units should follow the Unified Code for Units of Measure.

• Instruments for utilization metrics (that measure the fraction out of a total) are dimensionless and SHOULD use the default unit 1 (the unity).
• All non-units that use curly braces to annotate a quantity need to match the grammatical number of the quantity it represent. For example if measuring the number of individual requests to a process the unit would be {request}, not {requests}.
• Instruments that measure an integer count of something SHOULD only use annotations with curly braces to give additional meaning without the leading default unit (1). For example, use {packet}, {error}, {fault}, etc.
• Instrument units other than 1 and those that use annotations SHOULD be specified using the UCUM case sensitive ("c/s") variant. For example, "Cel" for the unit with full name "degree Celsius".
• Instruments SHOULD use non-prefixed units (i.e. By instead of MiBy) unless there is good technical reason to not do so.
• When instruments are measuring durations, seconds (i.e. s) SHOULD be used.

https://github.com/open-telemetry/opentelemetry-collector-contrib/blob/8f394d4ffea8d5f06a9019245746ff253be106fd/pkg/translator/prometheus/normalize_name.go#L155-L162

Metric name normalization

https://github.com/open-telemetry/opentelemetry-collector-contrib/blob/8f394d4ffea8d5f06a9019245746ff253be106fd/pkg/translator/prometheus/README.md#full-normalization

https://github.com/open-telemetry/opentelemetry-collector-contrib/blob/main/pkg/translator/prometheus/README.md#full-normalization

docs

the implementation ref to https://github.com/labstack/echo-contrib/blob/master/echoprometheus/prometheus.go

https://uptrace.dev/opentelemetry/go-metrics.html

https://uptrace.dev/opentelemetry/prometheus-metrics.html#sending-go-metrics-to-prometheus

https://opentelemetry.io/docs/reference/specification/metrics/sdk/

https://echo.labstack.com/cookbook/hello-world/

semconv

https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/resource/semantic_conventions/README.md#document-conventions https://github.com/open-telemetry/opentelemetry-go/blob/main/semconv/v1.12.0/resource.go

Documentation

Overview

Package otelmetric provides middleware to add opentelemetry metrics and OtelMetrics exporter.

Index

• type MiddlewareConfig
• type OtelMetrics
  • func New(config MiddlewareConfig) *OtelMetrics
  • func (p *OtelMetrics) NewHandler() echo.HandlerFunc
  • func (p *OtelMetrics) NewMiddleware() echo.MiddlewareFunc
• type RequestCounterLabelMappingFunc

Types

type MiddlewareConfig

type MiddlewareConfig struct {
	// Skipper defines a function to skip middleware.
	Skipper middleware.Skipper

	// Namespace is components of the fully-qualified name of the Metric (created by joining Namespace and Name components with "_")
	// Optional
	Namespace string

	ServiceVersion string

	MetricsPath string

	ScopeInfo bool

	RequestCounterURLLabelMappingFunc  RequestCounterLabelMappingFunc
	RequestCounterHostLabelMappingFunc RequestCounterLabelMappingFunc

	// Registry is the prometheus registry that will be used as the default Registerer and
	// Gatherer if these are not specified.
	Registry *realprometheus.Registry

	// Registerer sets the prometheus.Registerer instance the middleware will register these metrics with.
	// Defaults to: prometheus.DefaultRegisterer
	Registerer realprometheus.Registerer

	// Gatherer is the prometheus gatherer to gather metrics with.
	// If not specified the Registry will be used as default.
	Gatherer realprometheus.Gatherer
}

MiddlewareConfig contains the configuration for creating prometheus middleware collecting several default metrics.

type OtelMetrics

type OtelMetrics struct {
	*MiddlewareConfig
	// contains filtered or unexported fields
}

OtelMetrics contains the metrics gathered by the instance and its path

func New

func New(config MiddlewareConfig) *OtelMetrics

New generates a new set of metrics with a certain subsystem name

func (*OtelMetrics) NewHandler

func (p *OtelMetrics) NewHandler() echo.HandlerFunc

func (*OtelMetrics) NewMiddleware

func (p *OtelMetrics) NewMiddleware() echo.MiddlewareFunc

NewMiddleware defines handler function for middleware

type RequestCounterLabelMappingFunc

type RequestCounterLabelMappingFunc func(c echo.Context) string

RequestCounterLabelMappingFunc is a function which can be supplied to the middleware to control the cardinality of the request counter's "url" label, which might be required in some contexts. For instance, if for a "/customer/:name" route you don't want to generate a time series for every possible customer name, you could use this function:

func(c echo.Context) string {
	url := c.Request.URL.Path
	for _, p := range c.Params {
		if p.Key == "name" {
			url = strings.Replace(url, p.Value, ":name", 1)
			break
		}
	}
	return url
}

which would map "/customer/alice" and "/customer/bob" to their template "/customer/:name". It can also be applied for the "Host" label