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.
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
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.
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
1and 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.
Byinstead ofMiBy) unless there is good technical reason to not do so.- When instruments are measuring durations, seconds (i.e.
s) SHOULD be used.
Metric name 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 ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
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 ¶ added in v2.0.1
type OtelMetrics struct {
*MiddlewareConfig
// contains filtered or unexported fields
}
OtelMetrics contains the metrics gathered by the instance and its path
func New ¶ added in v2.0.1
func New(config MiddlewareConfig) *OtelMetrics
New generates a new set of metrics with a certain subsystem name
func (*OtelMetrics) NewHandler ¶ added in v2.0.3
func (p *OtelMetrics) NewHandler() echo.HandlerFunc
func (*OtelMetrics) NewMiddleware ¶ added in v2.0.3
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
Source Files