Skip to content

CONCEPT Cited by 1 source

Isomorphic observability API

Definition

An isomorphic observability API is an instrumentation interface that is runtime-neutral — written once, deployed unchanged on both the server (Node.js) and the browser — backed by runtime-specific SDK implementations that share the same public API surface.

Why it matters for isomorphic applications

A modern web application often runs the same component code on both sides of the network:

  • Rendered first on the server (SSR) — Node.js path.
  • Hydrated / re-rendered in the browser after load — browser path.
  • Client-side fetches produce more renders in the browser.

Without an isomorphic API, instrumentation has to be written twice — once per runtime. With one, a single traceAs("fetch_products") call compiles and runs on both sides.

Zalando's three-package shape

Zalando's structure (Source: sources/2024-07-28-zalando-opentelemetry-for-javascript-observability-at-zalando):

@zalando/observability-api           # shared types + API
@zalando/observability-sdk-node      # Node runtime adapter
@zalando/observability-sdk-browser   # browser runtime adapter

The -api package holds the TypeScript types and abstract interfaces both runtime SDKs implement. Applications take direct dependency on the shared API package and pick up the appropriate SDK at bundle / deploy time. The post explicitly credits one early Node.js SDK contributor with extracting types and APIs into the independent package — making it "especially useful while instrumenting isomorphic applications".

This is the basis for using one instrumentation codebase in the Rendering Engine on both the server and in the browser.

Key design questions

An isomorphic API must be:

  • Runtime-agnostic in signatures — no leaking of AsyncLocalStorage, DOM events, or Node-only types into the shared surface.
  • Behaviour-stable across runtimes — traceAs() on the server and on the browser should produce comparable spans (trace-context propagation across the SSR→hydration boundary is a separate design concern not covered here).
  • Consistent on attribute semantics — a span attribute like http.status_code must mean the same thing on both ends.
Last updated · 501 distilled / 1,218 read