The highest tagged major version is
README
¶
echo-otel-metrics
this is an opentelemetry metrics middleware for echo http framework.
it addd a custom opentelemetry metrics middleware otelmetric to echo framework, and setup a prometheus exporter endpoint at /metrics.
this otelmetric middleware can work as a replacement for
https://github.com/labstack/echo-contrib/tree/master/echoprometheus
or the legacy
https://github.com/labstack/echo-contrib/tree/master/prometheus
as of this module get v0.3.0 (otel metric v1.16.0), the metrics component is stable now, so this middleware is stable too.
but the metrics name diffs.
counter
requests_ratio_total
compatible mode: requests_total
histogram
request_duration_milliseconds{_bucket, _sum, _count}
compatible mode: request_duration_seconds{_bucket, _sum, _count}
request_size_bytes{_bucket, _sum, _count}
response_size_bytes{_bucket, _sum, _count}
echo's middleware result:
request_duration_seconds_bucket{code="200",host="example.com",method="GET",url="/",le="0.005"}
but this one result:
request_duration_milliseconds_bucket{code="200",method="GET",otel_scope_name="echo",otel_scope_version="",url="/",le="5"}
and otel metric exporter also add an target_info gauge looks like:
target_info{service_name="otelmetric-demo",telemetry_sdk_language="go",telemetry_sdk_name="opentelemetry",telemetry_sdk_version="1.16.0"} 1
The echoprometheus middleware registers the following metrics by default:
- Counter
requests_total - Histogram
request_duration_seconds - Histogram
response_size_bytes - Histogram
request_size_bytes
histogram will have _bucket, _sum, _count suffix.
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/prometheus/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 Prometheus exporter.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type MiddlewareConfig ¶ added in v0.3.7
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,Subsystem and Name components with "_")
// Optional
Namespace string
// Subsystem is components of the fully-qualified name of the Metric (created by joining Namespace,Subsystem and Name components with "_")
// Defaults to: "echo"
Subsystem string
ServiceVersion string
// run as [echo prometheus middleware](https://github.com/labstack/echo-contrib/blob/master/echoprometheus) compatible mode
CompatibleMode bool
MetricsPath string
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 Prometheus ¶
type Prometheus struct {
*MiddlewareConfig
// contains filtered or unexported fields
}
Prometheus contains the metrics gathered by the instance and its path
func NewPrometheus ¶
func NewPrometheus(config MiddlewareConfig) *Prometheus
NewPrometheus generates a new set of metrics with a certain subsystem name
func (*Prometheus) ExporterHandler ¶ added in v0.3.7
func (p *Prometheus) ExporterHandler() echo.HandlerFunc
func (*Prometheus) HandlerFunc ¶
func (p *Prometheus) HandlerFunc(next echo.HandlerFunc) echo.HandlerFunc
HandlerFunc defines handler function for middleware
func (*Prometheus) SetMetricsExporterRoute ¶ added in v0.3.7
func (p *Prometheus) SetMetricsExporterRoute(e *echo.Echo)
SetMetricsExporterRoute set metrics paths
func (*Prometheus) Setup ¶ added in v0.3.7
func (p *Prometheus) Setup(e *echo.Echo)
Setup adds the middleware to the Echo engine.
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