Expose application metrics from PHP into Caddy's metrics registry (frankenphp_metric_*)

[Caligone]

Describe your feature request

Is your feature request related to a problem? Please describe.

FrankenPHP exposes server-side metrics (frankenphp_busy_workers, frankenphp_queue_depth, …) through Caddy's Prometheus registry. That registry feeds both outputs Caddy supports: the /metrics endpoint for Prometheus scraping, and the OpenTelemetry exporter enabled by metrics { otlp }. The pipeline is already configured, scraped and exported.

Application metrics cannot use it. There is no way for a PHP script to emit a counter or a gauge into that registry. frankenphp_log() is the only bridge to Caddy's observability, and a log is not a metric: no type, no aggregation, no labels.

So publishing something like "messages enqueued per second" requires a second, parallel pipeline: an OpenTelemetry SDK or a vendor client, with its own credentials, transport and flush timing, while a working pipeline runs in the same process. We currently maintain two exporters and two auth mechanisms for what is a single stream of metrics out of a single container, and the application metrics land in a different place from the server metrics that explain them.

Describe the solution you'd like

A userland API mirroring frankenphp_log(), writing into the registry Caddy already exposes:

frankenphp_metric_counter('app_messages_enqueued', 5, ['queue' => 'events']);
frankenphp_metric_gauge('app_pending_jobs', 42);
frankenphp_metric_histogram('app_job_duration_seconds', 0.235, ['type' => 'export']);

They would appear alongside the built-in metrics on /metrics:

# TYPE app_messages_enqueued counter
app_messages_enqueued{queue="events"} 5

and, for users who enabled metrics { otlp }, be exported over OpenTelemetry as part of the same batch, with no extra configuration. That second output costs nothing to implement: modules/caddyhttp/metrics.go wires the OTel exporter to the same registry through otelprom.NewMetricProducer(otelprom.WithGatherer(reg)), so anything registered there is picked up by the Prometheus-to-OpenTelemetry bridge. Counters map to monotonic sums, gauges to gauges, histograms to histograms; the export path itself does not need to change.

This matters beyond convenience: application and server metrics reach the backend through one exporter, sharing the same resource attributes and the same collection interval, which is what makes them comparable on the same dashboard.

Implementation-wise this follows the frankenphp_log() path almost exactly:

• PHP side: three functions in frankenphp.stub.php, taking string $name, float $value, array $labels = [].
• CGO bridge: //export go_metric_counter / go_metric_gauge / go_metric_histogram, receiving (threadIndex C.uintptr_t, name *C.zend_string, value C.double, cLabels *C.zval). GoString() for the name and GoMap[string]() for the labels, exactly as go_log_attrs does today. Returning a non-nil *C.char raises a PHP exception, which covers unknown metric names and label mismatches.
• Go side: three methods on the existing Metrics interface, implemented by PrometheusMetrics, which already holds the prometheus.Registerer. Userland series would live in *prometheus.CounterVec / GaugeVec / HistogramVec keyed by name, guarded by the same RWMutex introduced in fix(metrics): replace mutex with read-write mutex #2450. nullMetrics gets no-op implementations, so metrics stay free when disabled.
• Worker lifetime: CounterVec values persist across worker restarts since the registry belongs to the Caddy app, not the thread. That is what you want for counters, and worth stating explicitly in the docs.

The open question, and probably the reason this doesn't exist yet, is cardinality: userland code can blow up a Prometheus registry with unbounded label values. Options, strictest first:

1. Metrics declared in the Caddyfile before use, unknown names rejected at the CGO boundary:

   frankenphp {
       metric app_messages_enqueued counter {
           labels queue
       }
   }

   This also lets CounterVec be created once at provision time with a fixed label set, which is the cheapest and safest option.
2. Runtime registration with a configurable max_series cap; further series rejected and logged.
3. Reserved-prefix ban plus a cap.

We'd lean towards 1 but have no strong opinion beyond "there must be a bound", and would rather follow what maintainers consider idiomatic. Happy to implement if there's agreement on the API shape; this issue is meant to settle that first.

Describe alternatives you've considered

• The OpenTelemetry PHP SDK, or a vendor SDK, inside the application (current approach): works, but means a second exporter and auth path running next to Caddy's, its own resource attributes and export interval, and application metrics that cannot be correlated with the FrankenPHP metrics explaining them. Two OTLP exporters in one container is also awkward to configure, since both read the same OTEL_* environment variables.
• Scraping /metrics from another process: extra moving part, and only relays FrankenPHP's own metrics, not application counters.
• A Caddy module: requires a custom build, and metric names and types must be known at compile time.
• frankenphp_log() plus backend-side extraction: acceptable for counters, poor for gauges and histograms, and moves aggregation to the backend.