Observability Overview

Stack

Layer	Tool	What it covers
Logs + traces	BetterStack	All server-side services via OTLP
LLM tracing	Langfuse	Token usage, cost, quality scores per AI call
Instrumentation	OpenTelemetry SDK	Spans, trace context propagation, Pino log hook
Package	`@repo/observability`	Wraps the OTEL SDK for TypeScript apps
Logger	`@repo/utils/logger` (base) / `@repo/observability/logger` (OTEL)	See Logger Usage Reference

OTLP endpoint: https://in-otel.betterstack.com

Services instrumented

Service	Type	Notes
`webapp`	TypeScript (Astro/Node)	Full OTEL via `@repo/observability`; service name `erp-unlocked-webapp`
`internal`	TypeScript (Astro/Node)	`@repo/observability`
`temporal-worker`	Python	`opentelemetry-distro` auto-instrumentation
`ts-temporal-worker`	TypeScript	`@repo/observability`
Cloudflare Workers	TypeScript	`@repo/utils/logger` (lightweight — no OTEL runtime in Workers)

Correlation

Every request gets a UUID v4 Correlation ID injected at the edge. It propagates via:

HTTP header x-correlation-id
Pino log field correlationId
Temporal workflow tags
Langfuse session_id
OTEL span attribute correlation_id

Find a full request trace in BetterStack: filter by correlationId = "<uuid>". See Correlation ID Querying for details.

Logger architecture

Two tiers — pick by consumer, not by preference:

@repo/utils/logger — lightweight Pino logger. Use in all shared packages/ and in any app that doesn’t need OTEL (Cloudflare Workers, static sites).
@repo/observability/logger — OTEL-enhanced. Use only in GCP Cloud Run apps (webapp, internal, temporal-worker, ts-temporal-worker).

Details: Logger Usage Reference · Architecture · Migration Guide

LLM observability

All AI calls go through @repo/ai (Anthropic SDK wrapper) with Langfuse tracing via @with_langfuse(). Tracks: model, tokens in/out, cost, latency, quality score.

Setup: Langfuse + BetterStack integration

Setup guides

BetterStack integration — env vars, dev/prod config, troubleshooting
Logging configuration — OTLP export settings, fallback transports
Observability architecture — how the layers connect
Testing guide — diagnostic endpoint, validation

Required env vars

OTEL_EXPORTER_OTLP_ENDPOINT=https://in-otel.betterstack.com
OTEL_EXPORTER_OTLP_HEADERS=Authorization=Bearer <betterstack-source-token>
OTEL_SERVICE_NAME=erp-unlocked-webapp   # per-service
OTEL_DEPLOYMENT_ENVIRONMENT=production  # or staging