Cwh Laravel Package

Technical Evaluation

Architecture fit

• maxbanton/cwh is a Monolog handler that ships PHP log records directly to AWS CloudWatch Logs via PutLogEvents. It slots into Laravel's existing Monolog-based logging pipeline rather than introducing a new abstraction, so it composes with stack, daily, and other channels.
• Best fit is a Laravel app already hosted on AWS (EC2, ECS, EKS, Lambda) with IAM-based access to CloudWatch and no existing centralized log aggregator. It is a push model; if the platform already captures stdout (e.g., ECS/Fargate → FireLens, Lambda → CloudWatch natively), this handler is largely redundant and adds an SDK dependency.
• It is a logging sink, not an observability platform. It provides no search, alerting, or dashboards beyond what CloudWatch Logs Insights offers.

Integration feasibility

• Low-to-moderate effort: composer require maxbanton/cwh (pulls aws/aws-sdk-php v3), add a channel in config/logging.php using the monolog driver with the handler class and handler_with options (log group, stream, retention, batch size, level, tags), optionally tee via a stack channel.
• Credentials resolve through the AWS SDK default chain: instance profile / task role preferred, env keys as fallback. No custom auth code required.
• Handler needs a pre-existing log group/stream or the create options enabled; retention is set at group level, so provisioning is an infrastructure concern (Terraform/CloudFormation) that should be owned outside the app repo.

Technical risk

• Monolog version compatibility is the primary unknown. Laravel 10/11 ship Monolog 3; this package has historically targeted Monolog 2. Confirm the released version supports Monolog 3 before committing, or budget a small adapter/fork.
• Single-stream sequence-token contention. CloudWatch requires a sequence token per stream; concurrent writers to one stream cause InvalidSequenceTokenException and throttling. Mitigate with per-instance/per-host streams or the handler's stream-sharding options.
• Batch and payload limits. PutLogEvents caps at 10,000 events / 1 MB per call; oversized messages (stack traces) can fail silently if error handling is lenient.
• Failure semantics. Handler exceptions can bubble and break request handling if ignoreExceptions/non-bubbling behavior isn't configured. Logging must never take down the app.
• Maintainer risk. 424 stars, MIT, single-maintainer profile. The underlying logic is thin (~one handler + formatter) and easily forked; treat as low-consequence but pin the version.
• Cost exposure. CloudWatch Logs ingestion (~$0.50/GB) and storage are billed per volume; verbose debug logging in production can quietly become a line item.

Key questions

1. Is CloudWatch Logs the sanctioned centralized logging target, or is there an existing aggregator (Datadog, ELK, Splunk) that should receive this traffic?
2. What is the deployment model (EC2 / ECS / EKS / Lambda / on-prem)? If containers or Lambda, is stdout capture already in place?
3. Which Laravel and Monolog versions are in scope, and does the pinned package release support Monolog 3?
4. What are expected log volumes (events/sec, GB/month) and the resulting CloudWatch cost envelope?
5. What retention and compliance requirements (e.g., PII scrubbing before ingestion) apply?
6. What is the IAM strategy — task/instance role vs. static keys — and who owns provisioning of log groups, retention, and resource policies?

Integration Approach

Stack fit

• Native to Laravel's config/logging.php channel model; adds one channel (typically a stack member alongside daily/stderr). No framework patches or service-provider hacks required, though a custom channel via Log::extend is an option if finer control is needed.
• Dependencies: aws/aws-sdk-php v3 and the package itself. Fits Composer-based PHP 8.x stacks; verify PHP constraint against the runtime.
• Prefer IAM roles over static credentials so config carries no secrets; use config/services.php or environment variables only for local/dev.

Migration path

• Phase 1: add the channel in local/staging with a dedicated log group; validate stream naming, sequence tokens under concurrent workers, and retention.
• Phase 2: introduce as a stack member in production alongside the existing file/stderr channel so CloudWatch receives a copy while the incumbent sink remains authoritative.
• Phase 3: validate in CloudWatch Logs Insights (canary log lines, error rates, latency impact), then retire the duplicate sink once parity is confirmed.
• No data migration is required; this is additive. Historical logs remain wherever they already live.

Compatibility

• Confirm Monolog 2 vs. 3 support against the Laravel version matrix before pinning; this is the gating item.
• AWS SDK v3 only; ensure no conflicting v2 dependencies elsewhere in the app.
• Verify behavior under queue workers (Horizon), Octane (long-lived workers — watch for buffer growth and stream tokens), and scheduled commands, since all write to the same handler instance lifecycle.

Sequencing

1. Confirm logging target decision and Monolog compatibility.
2. Provision log groups, retention, and IAM policy (infra team).
3. Add channel to staging; instrument handler latency and error rates.
4. Canary in production via stack tee; monitor cost and CloudWatch ingest metrics.
5. Promote to sole sink; remove duplicate; document runbook.

Operational Impact

Maintenance

• Small surface area (one handler + formatter, MIT). Pin to an exact version and track upstream releases; the blast radius of the package being abandoned is low because the logic is easily reimplemented (~100 lines against aws/aws-sdk-php).
• Ongoing upkeep is mostly dependency hygiene: AWS SDK major bumps, Monolog upgrades, PHP runtime upgrades.
• Log group lifecycle (retention, deletion, cost) is an infra responsibility, not app code — assign an owner.

Support

• Community-supported only; no vendor SLA. Escalation path is upstream issues + internal fork.
• Recommend an internal fallback plan documented in the runbook: swap to a thin custom Monolog handler or revert to file/stderr logging if the dependency breaks.
• Team needs working knowledge of CloudWatch Logs console and Logs Insights for triage.

Scaling

• Throughput ceiling is CloudWatch's PutLogEvents quota (~5 requests/sec/account/region) plus per-stream sequence-token serialization. Batch size should be tuned; per-host/per-pod streams avoid contention.
• Under high concurrency (many queue workers), a single stream will bottleneck. Design stream naming to shard by instance or service.
• Buffer memory grows with batch size; watch memory in long-lived workers (Octane/Horizon).
• Cost scales linearly with log volume — enforce level discipline (INFO+ in production, DEBUG only on demand) and set retention aggressively.

Failure modes

• Credential/authorization failure → handler throws; app requests fail if exceptions aren't suppressed. Set ignoreExceptions and keep a local fallback channel in the stack.
• CloudWatch throttling or outage → dropped or delayed logs; ensure non-blocking failure and alert on missing ingest.
• Sequence token conflicts → rejected batches; mitigate via stream sharding and retry.
• Oversized payloads → silently dropped events; enforce message truncation.
• Missing log group/stream → ingestion failure; provisioning must precede deploy or use create options.
• Misconfigured retention → unbounded storage cost; enforce at infra level.

Ramp-up

• Low engineering ramp: roughly a day for a developer familiar with Laravel logging; configuration is declarative.
• Higher organizational ramp: IAM policy design, log group provisioning, cost guardrails, and on-call familiarity with CloudWatch — plan a short enablement session and a written runbook.
• Recommend a short spike to validate Monolog 3 compatibility and concurrent-worker behavior before committing to the production rollout.