Octane Exporter Laravel Package

Getting Started

renoki-co/octane-exporter is a Laravel Octane metrics/exporter package: use it when you want Prometheus-style visibility into an Octane application’s HTTP traffic, worker behavior, and runtime health. Release 1.1.0 is primarily a compatibility release: it adds Laravel 9.x and OpenSwoole support. No breaking changes are stated, so existing Laravel 8/Swoole users should treat it as a low-risk upgrade and Laravel 9/OpenSwoole users should now be able to adopt it.

Minimal adoption path:

1. Install with Composer alongside Laravel Octane.
2. Publish/configure the package config if the package exposes one, and confirm the metrics route path, middleware, and enabled metric groups.
3. Register the exporter service provider/listeners as documented by the package.
4. Start the app under Octane, not artisan serve:
   • Swoole: php artisan octane:start --server=swoole
   • OpenSwoole: confirm the OpenSwoole extension is installed for the CLI PHP binary and start Octane with the OpenSwoole server option supported by your Octane version.
5. Scrape the exporter endpoint from Prometheus and verify the response is valid Prometheus text format.

Where to look first:

• config/octane-exporter.php or the package README’s configuration section for route, middleware, and enabled metrics.
• The package service provider to see which Octane events are listened to.
• php artisan route:list to confirm the metrics endpoint is registered.
• Octane server logs and php -m | grep -i openswoole when using OpenSwoole.

First use case: expose request counts/latency and Octane worker health from a Laravel 9 + OpenSwoole service, then alert in Prometheus/Grafana on error rate, latency, and worker availability.

Implementation Patterns

Treat the exporter as an observability sidecar for Octane, not as application business logic.

Common patterns:

• Prometheus scrape endpoint per instance. Run one exporter endpoint per Octane instance and let Prometheus scrape each instance directly. Do not route all scrapes through a single shared application node unless you have deliberately built aggregation.
• Protect the metrics route. Keep the exporter behind internal network policy, a middleware group, basic auth, or a dedicated internal port/route prefix. Metrics endpoints often leak route names, hostnames, worker counts, and traffic volume.
• Separate liveness from metrics. Use Octane/process health checks for restarts and the exporter for trend/alerting data. Do not make Kubernetes liveness depend on a Prometheus scrape response unless the endpoint is intentionally lightweight and reliable.
• Pair with Octane lifecycle events. Use the package’s Octane event integration to observe request handling and worker behavior. If you need custom application metrics, add them through the package’s registry/collector extension points or a separate Prometheus collector rather than modifying vendor code.
• Environment-specific config. Enable the exporter in staging/production, keep it disabled or restricted in local development if route noise or scrape traffic is undesirable.
• Deploy-time verification. After upgrading to 1.1.0, deploy to a Laravel 9/OpenSwoole canary and curl the metrics endpoint before rolling out broadly. Confirm metric names and labels remain stable for dashboards.
• Dashboard/alert integration. Start with a small set: request rate, error rate, latency, worker count/availability, and task/queue behavior if exposed. Add custom metrics only after the default scrape is stable.

For Laravel 9/OpenSwoole specifically:

• Confirm your Octane version supports the OpenSwoole server mode you select.
• Ensure the same PHP binary that runs artisan octane:start has the OpenSwoole extension enabled.
• Re-run route/config caches after upgrading: php artisan optimize:clear or the equivalent for your deployment.
• Keep the exporter version aligned with your Octane server mode in CI; test both Swoole and OpenSwoole if you support both.

Gotchas and Tips

• Octane-only package. Metrics are meaningful only while running under Octane. Testing with php artisan serve or PHP-FPM will not exercise the same worker lifecycle and may produce missing or misleading metrics.
• OpenSwoole extension mismatch. The most common OpenSwoole failure is installing the extension for one PHP binary but running Octane with another. Check php -v, php -m, and the CLI binary used by your process manager.
• Long-lived worker state. Octane workers persist between requests. Verify whether counters are per-worker or aggregated and how reset/restart behavior affects dashboards. After octane:reload or a deploy, expect counters to reset unless the package explicitly persists them.
• Per-instance aggregation. Prometheus should scrape every Octane instance. If you scrape one instance and expect cluster-wide totals, you will undercount or see only one worker/process’s view.
• Config cache quirks. After changing exporter route/config values, clear Laravel’s config and route caches. A cached route or config can make the endpoint appear missing after an upgrade.
• Route protection. Do not expose the metrics endpoint publicly by default. Use middleware, network ACLs, or an internal-only listener. Confirm the route is not accidentally included in a broad public route group.
• Label cardinality. If you add custom metrics, avoid high-cardinality labels such as raw URLs, user IDs, request IDs, or exception messages. Keep labels bounded.
• Scrape cost. Keep the exporter endpoint lightweight. Avoid expensive database queries or external API calls during scrape; cache slow values if necessary.
• Debugging sequence. Use php artisan route:list, curl the endpoint locally from the server, check response Content-Type, inspect Octane logs, and confirm the package’s event listeners are registered. If metrics are empty, first prove Octane requests are flowing through the expected server mode.
• Upgrade note for 1.1.0. This is a compatibility release, not an API overhaul. Re-test the metrics route, OpenSwoole startup, and Prometheus scrape after upgrading; no migration steps are indicated by the release notes.
• Extension points. Prefer the package’s documented registry/collector hooks or Octane event listeners for custom metrics. Avoid forking the package for one metric; wrap custom collection in application code and keep the exporter upgradeable.