How to install plone.observability

This guide shows you how to add plone.observability to a Plone instance and wire its WSGI filters into the pipeline.

The package ships three WSGI filters:

healthserver

Starts the health probe server.

observability

Populates the request metrics (plone_requests_total, plone_request_duration_seconds_*).

opentelemetry

Emits the OpenTelemetry root request span. Add it only if you use the tracing extra.

Without the filters the package is loaded but inert: the health server never starts and request metrics stay empty.

Add the dependency

Add plone.observability to your project dependencies.

[project]
dependencies = [
    "plone.observability",
]

Then include its ZCML.

<include package="plone.observability" />

Wire the filters

Choose the approach that matches how your zope.ini is produced.

If your zope.ini is generated by cookiecutter-zope-instance (3.1.0 or newer), do not edit zope.ini by hand. Declare the filters through wsgi_filters in your instance.yaml:

default_context:
    wsgi_filters:
        healthserver:
            use: "egg:plone.observability#healthserver"
        observability:
            use: "egg:plone.observability#observability"
        opentelemetry:
            use: "egg:plone.observability#opentelemetry"

Regenerating renders the [filter:*] sections and wires them into [pipeline:main]. Each entry also accepts options for extra key: value lines and position (outer, the default, or inner). Drop the opentelemetry entry if you do not use the tracing extra.

Add the filters to the pipeline and declare them as PasteDeploy filters:

[pipeline:main]
pipeline =
    healthserver
    egg:plone.observability#observability
    Zope

[filter:healthserver]
use = egg:plone.observability#healthserver

[filter:observability]
use = egg:plone.observability#observability

Verify

Start the instance and check the health port.

$ curl http://localhost:8081/live
{"status": "ok", "checks": {"process": {"ok": true, "message": "process alive"}}}

Then open the metrics endpoint.

$ curl http://localhost:8080/@@metrics
# HELP plone_uptime_seconds Process uptime
# TYPE plone_uptime_seconds gauge
plone_uptime_seconds{scope="instance"} 42.0

See also