Weave Code
Agent Laravel Laravel Package
stackmonitor/agent-laravel
StackMonitor Agent for Laravel: a lightweight package that connects your Laravel application to StackMonitor for monitoring and insights. Easy to install and configure, it reports runtime data from your app so you can keep an eye on performance and health in one place.
StackMonitor Agent for Laravel connects your Laravel application to the StackMonitor platform, providing a simple way to surface runtime health and application events with minimal setup. It is designed for quick installation and low-configuration integration, so you can add monitoring without restructuring your codebase.
- Auto-discovered service provider for zero-friction setup
- Publishable configuration to control agent behavior
- Framework-native integration with Laravel’s bootstrap and config systems
- Lightweight footprint suitable for development and production environments
Frequently asked questions about Agent Laravel
- How do I install stackmonitor/agent-laravel in a Laravel application?
- Install it with Composer using composer require stackmonitor/agent-laravel, then configure the agent credentials and endpoint through the package's environment variables. If you need to override defaults, publish the package configuration file; otherwise the default posture is largely no-config. The agent is additive and does not require database migrations or new infrastructure. Test the install in staging first so you can confirm the report payload and scan timing against a representative repository.
- Which Laravel versions does stackmonitor/agent-laravel support?
- The package's composer.json require constraints are the source of truth for supported Laravel and PHP versions. It is a standard Composer-based Laravel package, so it fits normal framework upgrade workflows without adding migrations or external services. Check the release notes before upgrading a major Laravel version, and run the agent in staging to verify payload compatibility with your dashboard.
- What data does StackMonitor Agent send by default?
- By default the agent sends runtime metrics, errors, and health signals to the StackMonitor dashboard. It also builds a php_code section containing metadata only: file counts, sizes, and a path, size, and mtime fingerprint. Source code is not uploaded unless you explicitly opt in. Review the fingerprint fields against your data-handling policy because paths and package inventory can reveal project structure.
- Does stackmonitor/agent-laravel upload my Laravel source code?
- No, not by default. Source content egress is strictly opt-in through STACKMONITOR_AGENT_FILE_CONTENTS=true, and the feature is hard-gated on ext-zip. When enabled, the agent creates ZIPs scoped to package folders and *.php files, with caps of 5000 files and 8MB, and it does not follow symlinked folders inside a package. Because app code can contain secrets or proprietary logic, treat enabling this as a security and legal decision, not just an environment toggle.
- What does STACKMONITOR_AGENT_FILE_CONTENTS=true do, and what happens if ext-zip is missing?
- It enables the optional ZIP content-upload path so StackMonitor can receive PHP file contents in addition to metadata. The feature requires ext-zip, so confirm that the extension is present in your base images and CI runners before enabling it. The release notes hard-gate the capability on ext-zip but do not clearly state whether a missing extension fails loudly or silently disables uploads. Test the exact PHP image you deploy so you know the behavior before turning the flag on in production.
- How much performance overhead does the StackMonitor Laravel agent add?
- The release notes describe a small, bounded increase in report-generation time, with a target of about 2 seconds per report and a deferred 20-second retry path for slow packages. A 10-minute cache mitigates steady-state scanning cost. Large repositories, monorepos, or network-attached storage such as NFS or EFS can still make the first scan slower. Validate cold-start timing on a representative checkout before rolling the agent out broadly.
- Do I need to upgrade the StackMonitor dashboard before upgrading the Laravel agent?
- Yes. This release explicitly requires a dashboard-first deployment because the dashboard must understand the php_code.contents field. Upgrade the dashboard to a version that supports the new payload before upgrading agents, or hold agent upgrades until that dashboard version is deployed. Confirm the minimum supported agent and dashboard pairing in the release notes, and verify old dashboards tolerate unknown fields if you cannot upgrade in lockstep.
- How do I disable source code uploads or php_code scanning in stackmonitor/agent-laravel?
- Keep STACKMONITOR_AGENT_FILE_CONTENTS unset or set to false to prevent ZIP content uploads; that is the default and the safest posture. Metadata scanning starts automatically for app/ and for composer.lock packages that are not resolvable on packagist.org, with dev packages excluded. If you need to reduce metadata collection as well, review the published package configuration for available scan controls rather than relying only on file caps. Own the environment flag at platform or security level so individual application teams do not drift.
- Is stackmonitor/agent-laravel read-only, and does it require database migrations?
- Yes, the agent is designed as a read-only telemetry collector: it reads application files and composer.lock, then sends reports to StackMonitor. It does not introduce database migrations, queues, or new storage services. It may use a local cache for scan results, including the documented 10-minute cache. That keeps the integration low-touch, but you should still review filesystem permissions and outbound network access in your environment.
- How should I test stackmonitor/agent-laravel in staging before production?
- Upgrade the dashboard first, then install the agent with STACKMONITOR_AGENT_FILE_CONTENTS left unset so only metadata leaves the host. Use a staging repository that resembles production, including symlinked vendor directories or monorepo layouts, and check report payload shape and scan timing. After that, test the opt-in ZIP path separately and confirm the 5000-file and 8MB caps, memory behavior, and any ext-zip behavior in your base image. Monitor report latency on cold starts, especially if storage is network-attached.
Weaver
How can I help you explore Laravel packages today?