Introduction

Note: This middleware is only available with Kipchak Enterprise.

The OpenTelemetry middleware gives every request a server span, the root of everything the request does: the spans the OpenTelemetry driver records for HTTP, Doctrine, Valkey and Kafka calls, your own spans, and the log lines written while it runs.

Named after the route: GET /v1/orders/{id} rather than one name per order, with http.route set.
Continues the caller's trace: a request that arrives with a W3C traceparent header joins its caller's trace, so a trace follows a call from one Kipchak API into the next.
Request metrics: http.server.request.duration by method, route and status.
Exports after the response: it registers the driver's export with $app->onTerminate(), so exports happen after each response has been sent.

Installation

The middleware needs the OpenTelemetry driver; install and configure both as the driver's page describes. Initialise the middleware last in middlewares/middlewares.php, so that it runs first and its span covers every other middleware:

use Kipchak\Middleware\OpenTelemetry\OpenTelemetry;

Error::initialise($app);
// ... other middleware
OpenTelemetry::initialise($app);

The worker loop in html/index.php must call $app->terminate() after each request, as the starter project does from version 3.19.

Configuration

The middleware's settings are the server section of config/kipchak.opentelemetry.php:

'server' => [
    'ignore_paths' => ['/health', '/metrics', '/internal/*'],
    'response_header' => 'X-Trace-Id',
    'request_headers' => ['X-Request-Id'],
],

Setting	Default	Meaning
`enabled`	true	false turns the server span off; exports still run after each response.
`ignore_paths`	none	Paths that get no span, such as health checks. A trailing `*` matches any path that starts with what comes before it.
`response_header`	null	Returns the trace ID in this response header, so a client can quote it in a support request.
`request_headers`	none	Request headers recorded on the span, as `http.request.header.<name>`.

The server span

Attribute	Example
`http.request.method`	`GET`
`http.route`	`/v1/orders/{id}`
`url.path`, `url.scheme`	`/v1/orders/7`, `https`
`server.address`, `server.port`	`api.example.com`, `443`
`client.address`	`203.0.113.9`
`user_agent.original`	`checkout/2.0`
`http.response.status_code`	`200`

A 5xx response, or an exception that escapes every other middleware, marks the span as an error; a 4xx is the client's error and does not. A request that matches no route keeps the method as its name. Routes written as request handler classes are named like any other route.

The span is the current span while the request is handled, so OpenTelemetry::traceId() returns its trace ID in a controller, and log lines carry it.

Git Repository

The source code for this middleware is available on 1x.ax at https://1x.ax/mamluk/enterprise/kipchak/middlewares/opentelemetry.