Contrib Aws Laravel Package

Product Decisions This Supports

• Distributed tracing across AWS boundaries — the "async gap." The highest-value use case is Laravel apps that hand work to SQS/SNS and lose the trace when a queue worker picks it up. This package is the enabling piece for propagating context through SendMessage/ReceiveMessage (SQS), Publish (SNS), and Lambda invocations, so a single user action can be followed end-to-end in the trace UI. That's a product decision about whether "time to root cause an order/payment/webhook failure" is a metric worth investing in — not a purely infra one.
• AWS-native interoperability (X-Ray). Teams already standardized on AWS X-Ray for infra-level traces can evaluate this as the bridge that lets application-level PHP spans appear alongside ECS/Lambda/API Gateway segments. This directly informs the build vs. buy decision: buy a thin, spec-compliant middleware vs. hand-rolling AWS SDK middleware and a trace-header propagator (roughly a 1–3 sprint effort to build and maintain, with ongoing SDK-version churn as the hidden cost).
• Consistent instrumentation policy across services. If the platform roadmap includes more than one PHP service talking to AWS, adopting one shared instrumentation path avoids each team inventing its own span naming and attribute conventions — which is what makes cross-service dashboards and SLOs actually comparable.
• Feature prioritization input. Span data from AWS SDK calls tells you which downstream AWS dependencies dominate p95 latency (e.g. a single hot DynamoDB partition, an oversized S3 PUT, SQS visibility-timeout retries). That converts "the app feels slow" into a ranked backlog of integration-level work.
• Roadmap input for reliability/SLO commitments. Queue-based retries and poison messages become visible as error spans with AWS error codes rather than opaque timeouts — a prerequisite if you plan to publish an SLO on background job success rate.
• Vendor-lock-in hedging. Because it's OTel (not an AWS-proprietary SDK hook), the same spans can be exported to any OTLP backend. Supporting it keeps the choice of observability backend a reversible decision.

When to Consider This Package

Consider it when all or most of the following hold:

• The service already runs OpenTelemetry (the open-telemetry/sdk + an exporter, realistically via the open-telemetry/opentelemetry-auto-* autoloading instrumentation, since Laravel has no first-party OTel support).
• AWS SDK usage is on a critical path — SQS/SNS async workflows, DynamoDB/S3 calls in request handling, or Lambda fan-out.
• You need trace continuity through queues, not just request-level spans.
• You have, or are actively building, X-Ray-correlated dashboards, or you require OTLP-compatible trace headers inside AWS payloads.
• Someone on the team can read the package source and pin versions. With near-zero stars and no downstream dependents, treat it as a low-maturity dependency: pin it, wrap it behind your own bootstrap/config, and be prepared to fork or patch.

Look elsewhere / do not adopt when:

• You have no OTel pipeline yet. Bolting this on before you have a collector, exporter, and sampling policy in place produces cost with no queryable value. Sequencing matters: pipeline first, then AWS instrumentation.
• You just need request-level Laravel tracing. The Laravel/HTTP/PDO instrumentations deliver most of the immediate value; AWS-specific spans are an optimization, not a starting point.
• Your team is on a managed APM agent (Datadog, New Relic, Elastic) that already instruments the AWS SDK. Adding a second, uncoordinated instrumentation layer creates duplicate spans and confusing cost. Verify the agent's coverage before introducing this.
• You need vendor-supported SLAs or guaranteed maintenance. "Official OpenTelemetry org" gives governance credibility, but a 0-star/0-dependent package does not give you support commitments. Budget for the possibility that you become the maintainer of your fork.
• The package's PHP/Laravel compatibility lags your stack. Explicitly verify PHP version support, aws/aws-sdk-php major version alignment, and whether AWS SDK v3 middleware registration still works on your versions. Also confirm which AWS services and which propagator are actually implemented — do not assume SQS context injection exists just because the package name is broad.
• Tracing is head-sampled in a way that breaks queue hops. If sampling drops the producing span, the consumer side yields orphan traces; you'll need a tail-sampling or "always sample queue producers" policy first. This is a design prerequisite, not a package feature.

Adoption gate to run before committing: a half-day spike on one non-critical SQS-backed service, confirming (a) spans appear with sane names/attributes, (b) trace IDs match across producer and consumer, (c) export volume and ingest cost are within budget, (d) no material p95 overhead from middleware wrapping. Also confirm license and release cadence and whether an opentelemetry-auto-* variant exists that avoids manual bootstrap wiring.

How to Pitch It (Stakeholders)

For executives (one paragraph): We have a blind spot. When a customer action triggers background work — order processing, notifications, payments, syncs — we currently can't follow that work across our AWS queues, so diagnosing a slow or failed transaction means correlating logs by hand. This is an official OpenTelemetry community package that attaches standard trace context to our AWS SDK calls, so a single request becomes one trace from web request through queue to worker. It's free, open source, vendor-neutral, and small in scope: a low-cost, reversible increment on observability we're already investing in, aimed at reducing mean time to diagnose production issues. The caveat we're managing is maturity — it's early-stage with very little adoption, so we'd pilot it on one non-critical service and pin the version rather than roll it out broadly.

For engineering (the practical framing): This is a thin AWS SDK middleware plus propagator for opentelemetry-php. It wraps aws/aws-sdk-php calls in spans and injects/extracts trace context in message attributes so SQS/SNS consumers continue the trace instead of starting a new one; it also gives us an X-Ray-compatible propagator so application traces line up with AWS-native segments. It is not a framework integration — we still need our existing OTel bootstrap, exporter, and sampling config, and we should confirm SDK version support and which services are covered before we rely on it.

Scope and risk statement to state plainly:

• Effort: ~1–3 days for a pilot spike; ~1 sprint including sampling and collector config, dashboarding, and a runbook. Building this ourselves is 1–3 sprints plus permanent maintenance against AWS SDK changes.
• Risk: low blast radius (instrumentation only, no request-path logic changes), but low maturity (0 stars, 0 dependents, unproven release cadence). Mitigations: pin the version, wrap initialization in our own config, keep an easy kill switch, and accept that we may need to fork.
• Decision requested: approve a timeboxed pilot on one non-critical SQS-backed service, with success measured as "trace continuity across a queue hop verified end-to-end and ingest cost quantified," before any wider rollout.
• What would make us say no: duplicate spans from an existing APM agent, unacceptable ingest cost, or compatibility gaps with our PHP/AWS SDK versions.