Hacktoberfest 2026: los issues que los mantenedores marcaron para octubre, abiertos y aptos para principiantes. Explorar issues de Hacktoberfest

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

Abierto
  • ¿Algo no está bien?
#2,603 0 comentarios 1 reacción 0 asignados Ver en GitHub

Los mantenedores suelen responder en 1 día

Nadie ha tomado este issue todavía.

Evaluación

Dificultad
5/5
Tiempo estimado
Más de una semana
Aptitud para principiantes
38/100
Tipo de issue
Nueva funcionalidad
Claridad
Bastante claro
Estado de actividad
Tranquilo
Stack tecnológico
go, php, prometheus
Área
backend, observability

Línea de trabajo

Empieza con frankenphp.stub.php y la ruta existente frankenphp_log()/go_log_attrs; después inspecciona el Metrics interface, PrometheusMetrics, nullMetrics y modules/caddyhttp/metrics.go. Primero acuerda con los maintainers la declaración de métricas y la Cardinality API; se considera terminado cuando la ruta PHP/CGO/Go acordada alimenta el registro existente y el puente OTLP, con el comportamiento durante la vida útil del worker documentado.

Escrito por el modelo de indexación a partir del texto del issue.

Descripción

enhancement
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 #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.
Lenguaje dominante
Go
Estrellas
11.4k
Forks
490
Merge medio
2 d 21 h
PR fusionados (30 d)
29

Preparar el entorno

Primeros pasos

  1. Lee el issue completo y luego la guía de contribución del proyecto.
  2. Comenta en el issue que vas a ocuparte — evita que dos personas hagan lo mismo.
  3. Haz un fork del repositorio y trabaja en una rama.
  4. Abre un pull request que haga referencia al número del issue.

Más de php/frankenphp

Todos los issues de php/frankenphp

Issues similares

Más issues de Go

Recibe los nuevos issues en tu correo

Un resumen breve de issues de GitHub para principiantes.