kotel

README

KrakenD OpenTelemetry (krakend-otel)

OpenTelemetry building blocks to instrument KrakenD and Lura based API Gateways.

Apache License 2.0

Documentation:

• OpenTelemetry configuration
• OpenTelemetry layers, traces, and metrics

Example

For a quick look at the observability the library can provide, check the example documentation.

Configuration from Lura's ServiceConfig

In order to configure the open telemetry stack to instrument the API Gateway, a new entry must be added to the ExtraConfig root propertry of ServiceConfig using the telemetry/opentelemetry key, with the krakend-otel's configuration.

See the configuration of the component.

In a visual way, this is the relation between the exporters configuration, and how we select as metric_providers or trace_providers:

Layers, Traces and Metrics

The most up to date documentation about the different supported layers, and the produced metrics and traces is available in the Understanding OpenTelemetry layers and metrics documentation.

We can differentiate the processing of a request in KrakenD in 3 main stages (each one including or wrapping the inner stage):

• global: this part that comes before the Lura's framework starts working with the request. In the case of KrakenD CE, this stage is implemented using gin. See the Data exposed in the global layer and its configuration options

• proxy: this is the Lura's framework part where it deals with one of the API Gateway exposed endpoints, and includes spawning the required requests to the backends, as well as the manipulation at the endpoint level before and after the requests are performed. See the Data exposed in the proxy layer and its configuration options

• backend: this is the Lura's framework part where it deals with each single backend request (including the manipulation at that request level). See the Data exposed in the backend layer and its configuration options

Additional information

• Check the example documentation
• Some notes about current implementation

Documentation

Overview

Package kotel adds opentelemetry instrumentation to a KrakenD instance (or some other [Lura](https://github.com/luraproject/lura) based softawre)

In the KrakenD project, we can differentiate 3 main stages in the process of handling a request:

• the "router" stage: the part where the router plugins are run, and is the part from receiving the request, up to the point where the request enters the Lura's pipeline.
• the "proxy" stage: is for the processing endpoint part, up to the point
• the "backend" stage: is the part for each one of the backends that will be used for a given endpoint.

Index

• func Register(ctx context.Context, l logging.Logger, srvCfg lconfig.ServiceConfig) (func(), error)
• func RegisterGlobalInstance(ctx context.Context, l logging.Logger, me map[string]exporter.MetricReader, ...) (func(), error)
• func RegisterWithConfig(ctx context.Context, l logging.Logger, cfg *config.ConfigData) (func(), error)

Functions

func Register

func Register(ctx context.Context, l logging.Logger, srvCfg lconfig.ServiceConfig) (func(), error)

Register uses the ServiceConfig to instantiate the configured exporters. It also sets the global exporter instances, the global propagation method, and the global KrakenD otel state, so it can be used from anywhere.

func RegisterGlobalInstance

func RegisterGlobalInstance(ctx context.Context, l logging.Logger,
	me map[string]exporter.MetricReader, te map[string]exporter.SpanExporter,
	metricReportingPeriod int, traceSampleRate float64, serviceName string, serviceVersion string,
) (func(), error)

RegisterGlobalInstance creates the instance that will be used to report metrics and traces

func RegisterWithConfig

func RegisterWithConfig(ctx context.Context, l logging.Logger, cfg *config.ConfigData) (func(), error)

RegisterWithConfig instantiates the configured exporters from an already parsed config: sets the global exporter instances, the global propagation method, and the global KrakenD otel state, so it can be used from anywhere.