LocalStack lets you run SQS locally in Docker for fast feedback loops, but OpenTelemetry's default AWS SDK instrumentation uses AWSTraceHeader (X-Ray format) for SQS message propagation, which free LocalStack doesn't implement — causing traces to silently break. The fix is to force W3C traceparent propagation by passing TraceContextTextMapPropagator to BotocoreInstrumentor, or switching to Boto3SQSInstrumentor. The post covers full setup: Docker Compose config, queue creation, the AWS_ENDPOINT_URL pattern for environment-agnostic boto3 clients, an end-to-end SQS→Lambda test flow including the ESM vs SDK message attribute format mismatch, LocalStack's non-destructive peek endpoint, and a clear list of common pitfalls.
Table of contents
Why LocalStackSetting Up LocalStackSQS Basics on LocalStackThe AWS_ENDPOINT_URL PatternThe OTel Propagation TrapEnd-to-End Test Pattern: SQS → LambdaThe SQS Peek EndpointCommon PitfallsLocalStack vs Real AWS: When to Trust Local ResultsCleanupReferencesSort: