PoC / Nebula (WIP)

nebula is a CLI tool that automatically instruments arbitrary WebAssembly components with OpenTelemetry tracing via the wasi:otel interface, with no changes required to the component's source code.

It works by generating a proxy component that mirrors every import and export of the target component, and injects wasi:otel entry/exit spans around each proxied function call. The original component is left unmodified; the proxy wraps it at the composed-component level.

Background

wasi:otel and static composition

The wasi:otel/tracing interface is the standard mechanism for WebAssembly components to emit OpenTelemetry spans. A component calls on-start to open a span and on-end to close it; both are handled by the host runtime.

A fundamental problem arises with static composition (e.g. components linked with wac): the original wasi:otel@0.2.0-rc.2 proposal exposed only outer-span-context, which always returns the host's outermost span context, not the innermost span currently active across logical component boundaries. When component A starts a span and then calls into component B, B has no way to discover A's span and therefore cannot establish the correct parent-child relationship. The resulting trace loses causality.

The inner-span-context proposal

This project targets a revised wasi:otel proposal, defined in wit/wasi-otel/tracing.wit, that adds:

/// Returns the span context of the current span.
inner-span-context: func() -> span-context;

The host maintains a stack of active span contexts:

• on-start pushes a new context.
• on-end pops it.
• inner-span-context returns the top of the stack: the innermost currently-active span, regardless of which component started it.

This restores correct parent-child tracing across static composition boundaries, which is a prerequisite for automatic instrumentation of composed components to produce meaningful traces.

Usage

Instruments WebAssembly components by generating a proxy wrapper that adds logging and tracing capabilities to all exported interfaces.

Arguments

nebula instrument <INPUTS>... [OPTIONS]

Argument	Description
<INPUTS>...	Path(s) to .wasm component files or a directory containing multiple components.

Options

Flag	Long Flag	Description	Default
-o	--output-dir	The directory where the generated proxy source and WIT files will be written.	./tmp
-h	--help	Print help information.
-V	--version	Print version information.

Example

# Instrument a specific component and output to a custom directory
nebula instrument ./service.wasm -o ./generated_proxy

# Instrument all components in a folder
nebula instrument ./bin/components/

Building

cargo build --release

Requires a Rust toolchain with the version specified in rust-toolchain.toml.

Roadmap

• Generate proxy WIT world
• Generate proxy WIT world bindings
• Generate Rust implementation based on bindings
• Emit proxy Wasm
• Automatically compose input components + proxy (wac)

License

MIT — see LICENSE.