feat(observability): add OpenTelemetry building blocks (OtelMetrics / OtelLogger / OtelTracer)

[gcacace]

Problem

The observability blocks (Metrics, Logger, Tracer) are AWS-native and minimal — CloudWatch EMF, stdout JSON, and the X-Ray SDK. They give up OpenTelemetry's vendor-neutral, richly-typed telemetry model (typed metric instruments, span links/events, context propagation, semantic-convention resource attributes) and the ability to send telemetry to any OTLP backend. There was no first-class way to run OpenTelemetry on a Blocks app.

Issue #, if available: N/A

Changes

Adds a new OpenTelemetry observability block family that coexists with the existing blocks (and is recommended for new apps). The blocks initialize an in-process OTel SDK that exports OTLP/HTTP to a standalone opentelemetry-lambda collector layer, which SigV4-signs and forwards to CloudWatch's native OTLP endpoints (or any OTLP backend via an override). The shared handler force-flushes before returning, and the collector's decouple processor holds the invocation open until export completes.

New packages:

• @aws-blocks/otel-common — support library: in-process SDK bootstrap + per-invocation flushOtel(), the collector-config renderer, the idempotent CDK shared-infra helper, and zero-arg provider accessors (getOtelMeterProvider / Tracer / Logger) for OTel-compatible libraries.
• @aws-blocks/bb-otel-metrics (OtelMetrics) — emit() + typed OTel instruments (counter/histogram/upDownCounter/observableGauge) + rawMeter.
• @aws-blocks/bb-otel-logger (OtelLogger) — debug/info/warn/error + child → OTel LogRecords; rawLogger.
• @aws-blocks/bb-otel-tracer (OtelTracer) — startSegment → active span (kind/links/events, W3C inject/extract); rawTracer.

Supporting changes:

• OTel-correct API & semantics — service identity uses semconv resource attributes (serviceName/serviceNamespace/serviceVersion), not a CloudWatch "namespace"; service.name defaults to the Lambda function name → BLOCKS_STACK_NAME → block fullId. AWS Lambda resource attributes (faas.*, cloud.*, aws.log.group.names) are auto-detected in-process (the collector layer omits resourcedetection — see OTel contrib #17584). Metric units are UCUM; no emitBatch/MetricDatum (OTel batches at export).
• @aws-blocks/bb-dashboard — renders PromQL chart widgets for OtelMetrics (OTLP metrics are PromQL-queryable, with no namespace); classic Metrics dashboards are unaffected.
• @aws-blocks/core — flushes in-process OTel telemetry after each invocation (no-op unless an OTel block is in use).
• Umbrella exports, vendorize map, root README catalog, and docs reframed to recommend the OTel blocks over the AWS-native ones.

⚠️ Notable: the collector layer is region-pinned (default opentelemetry-collector-amd64-0_15_0, account 184161586896); traces require CloudWatch Transaction Search enabled in the account/region; the OTLP logs endpoint requires a pre-existing log group + stream (the CDK construct creates a dedicated /aws/otel/<fullId>).

Validation

• Unit tests added across all packages: otel-common (34 — collector-config rendering, SDK/resource building + Lambda detection, idempotent CDK infra, provider accessors), bb-otel-metrics (14), bb-otel-logger (9), bb-otel-tracer (9), plus bb-dashboard PromQL widget tests. Umbrella conditional-exports (23) and vendorize-map (24) gates pass; full build:packages is clean.
• Deployed AWS validation (throwaway resources in a sandbox account, since torn down): confirmed end-to-end that the architecture works — all three signals land in CloudWatch with zero export errors, and verified via the CloudWatch PromQL API that metrics carry the expected @resource.faas.* / @resource.service.* labels. This is also how the architecture pivot was discovered (the ADOT layer drops async exports on the sandbox freeze; the standalone collector layer + decouple + force-flush works).
• Local dev: the mock runtime exercises the same OTel SDK with console exporters (metrics/logs → stdout) and a file span exporter (traces → .bb-data/<fullId>/traces.json).

Checklist

• PR description included
• Tests are changed or added
• Relevant documentation is changed or added (and PR referenced)

---

By submitting this pull request, I confirm that my contribution is made under the terms of the Apache 2.0 license.

[svidgen]

This requires some thought. Having Otel prefixed blocks be the "recommended" way to do observability is odd when we have bare-named Logger, Metrics, and Tracing blocks. 🤔

Can the existing observability blocks be extended or switched out gracefully under the hood? Are there any cost, performance, or stability considerations?

[soberm]

After taking a look, I'm leaning toward keeping these as separate blocks instead of building OTel into the existing blocks. For Logger and Tracer it's probably easy since the method surfaces already line up, so a backend: 'aws-native' | 'otel' switch would mostly just work. The problem is that the OTel path pulls in the whole in-process SDK, protobufjs, the OTLP exporters and the collector-layer CDK wiring. Every consumer is impacted by the bundle and cold-start implications even if they never use OTel.

However, Metrics is what bothers me most. Some of it could be shimmed, e.g., dimensions maps cleanly to OTel attributes, and we could fold namespace into the service.namespace resource attribute so its value survives as a PromQL filter. But that doesn't reproduce CloudWatch-namespace behavior: existing namespace-keyed alarms and dashboards just won't find OTel metrics. Since this is still preview it's not a blocker but still worth mentioning. And the rest doesn't map at all: emitBatch has no equivalent, units flip from CloudWatch's enum to UCUM strings, and timestamp/resolution disappear. Reusing the existing block there would mean either faking stuff that doesn't map or breaking callers, which feels worse than just keeping it separate.

Regarding making OTel the recommended default, I think that some consumers won't care about OTel at all. If they just want lightweight, zero-overhead observability, the AWS-native blocks (plain EMF to stdout, no collector layer, no extra bundle size) are probably better. Given the cold-start, bundle size (~7x), and per-invocation flush costs that come with OTel, I'm not sure we should be steering people toward it by default. I'd rather present them as equal options: pick OTel if you need vendor-neutral export or third-party backends, stick with AWS-native if you just want simple and cheap.