✨ add wasm coverage and trace context

docs/.vitepress/config.mts

@@ -121,6 +121,7 @@ function buildExtendSidebar(): DefaultTheme.SidebarItem[] {
     { text: 'Sink Composition', link: '/extend/composition' },
     { text: 'Text Formatting', link: '/extend/formatting' },
     { text: 'Target Boundaries', link: '/extend/targets' },
+    { text: 'Trace Context', link: '/extend/observability' },
   ]
 }
 
@@ -141,6 +142,7 @@ function buildChineseExtendSidebar(): DefaultTheme.SidebarItem[] {
     { text: 'Sink 组合', link: '/zh/extend/composition' },
     { text: '文本格式与样式', link: '/zh/extend/formatting' },
     { text: '目标平台边界', link: '/zh/extend/targets' },
+    { text: 'Trace Context', link: '/zh/extend/observability' },
   ]
 }
 

docs/README-en.md

@@ -44,7 +44,7 @@ Continue with the [Examples guide](./examples/index.md): console fields, file ro
 
 ## Support Status
 
-- Current local verification covers `native`, `js`, `wasm`, and `wasm-gc` for the main `src` package and `src-async`
+- CI checks and tests `native`, `wasm`, `js`, and `wasm-gc` for the main `src` package and `src-async`
 - `llvm` is still treated as experimental in the current release context and was not locally re-verified in the current environment
 - The source packages still declare `wasm` support alongside `native`, `llvm`, `js`, and `wasm-gc`; see [`target-verification.md`](./api/target-verification.md) for the current release-facing verification boundary
 - File output is a native capability; check `native_files_supported()` in cross-target code
@@ -58,6 +58,7 @@ Continue with the [Examples guide](./examples/index.md): console fields, file ro
 - Config-based builders: `build_logger(...)` and `build_async_logger(...)`
 - Composition helpers: queue, filter, patch, fanout, split, callback
 - Separate async package under `src-async`
+- Trace-context binding through standard `trace_id`, `span_id`, `trace_flags`, and `trace_state` fields
 
 ## Documentation
 

docs/api/async-logger-with-trace-context.md

@@ -0,0 +1,21 @@
+---
+name: async-logger-with-trace-context
+group: api
+category: async
+update-time: 20260719
+description: Bind TraceContext fields before records enter an AsyncLogger queue.
+key-word:
+    - async
+    - trace
+    - context
+---
+
+## Async-logger-with-trace-context
+
+```moonbit
+let contextual = logger.with_trace_context(
+  @bitlogger.trace_context("trace-1", "span-1"),
+)
+```
+
+The helper stores the mapped fields on the returned async logger and preserves its queue, lifecycle, target, and threshold state. Context is added before records are enqueued.

docs/api/index.md

@@ -31,6 +31,7 @@ BitLogger API navigation.
 - [logger-with-timestamp.md](./logger-with-timestamp.md)
 - [logger-with-context-fields.md](./logger-with-context-fields.md)
 - [logger-bind.md](./logger-bind.md)
+- [logger-with-trace-context.md](./logger-with-trace-context.md)
 - [logger-with-filter.md](./logger-with-filter.md)
 - [logger-with-patch.md](./logger-with-patch.md)
 - [logger-with-queue.md](./logger-with-queue.md)
@@ -99,6 +100,10 @@ BitLogger API navigation.
 - [fields.md](./fields.md)
 - [text-formatter-config-type.md](./text-formatter-config-type.md)
 
+## Observability
+
+- [trace-context.md](./trace-context.md)
+
 ## Record and level
 
 - [record.md](./record.md)
@@ -266,6 +271,7 @@ BitLogger API navigation.
 - [async-logger-with-min-level.md](./async-logger-with-min-level.md)
 - [async-logger-with-timestamp.md](./async-logger-with-timestamp.md)
 - [async-logger-with-context-fields.md](./async-logger-with-context-fields.md)
+- [async-logger-with-trace-context.md](./async-logger-with-trace-context.md)
 - [async-logger-with-filter.md](./async-logger-with-filter.md)
 - [async-logger-with-patch.md](./async-logger-with-patch.md)
 
@@ -322,6 +328,7 @@ BitLogger API navigation.
 - [library-logger-child.md](./library-logger-child.md)
 - [library-logger-with-context-fields.md](./library-logger-with-context-fields.md)
 - [library-logger-bind.md](./library-logger-bind.md)
+- [library-logger-with-trace-context.md](./library-logger-with-trace-context.md)
 - [library-logger-is-enabled.md](./library-logger-is-enabled.md)
 - [library-logger-log.md](./library-logger-log.md)
 - [library-logger-info.md](./library-logger-info.md)
@@ -341,6 +348,7 @@ BitLogger API navigation.
 - [library-async-logger-child.md](./library-async-logger-child.md)
 - [library-async-logger-with-context-fields.md](./library-async-logger-with-context-fields.md)
 - [library-async-logger-bind.md](./library-async-logger-bind.md)
+- [library-async-logger-with-trace-context.md](./library-async-logger-with-trace-context.md)
 - [library-async-logger-is-enabled.md](./library-async-logger-is-enabled.md)
 - [library-async-logger-log.md](./library-async-logger-log.md)
 - [library-async-logger-info.md](./library-async-logger-info.md)

docs/api/library-async-logger-with-trace-context.md

@@ -0,0 +1,15 @@
+---
+name: library-async-logger-with-trace-context
+group: api
+category: facade
+update-time: 20260719
+description: Bind TraceContext fields through the restricted LibraryAsyncLogger facade.
+key-word:
+    - library
+    - async
+    - trace
+---
+
+## Library-async-logger-with-trace-context
+
+`LibraryAsyncLogger::with_trace_context(...)` returns a derived library facade with `trace_id`, `span_id`, `trace_flags`, and optional `trace_state` attached to each later record. It does not start a worker or change lifecycle state.

docs/api/library-logger-with-trace-context.md

@@ -0,0 +1,20 @@
+---
+name: library-logger-with-trace-context
+group: api
+category: facade
+update-time: 20260719
+description: Bind TraceContext fields through the restricted LibraryLogger facade.
+key-word:
+    - library
+    - trace
+    - context
+---
+
+## Library-logger-with-trace-context
+
+```moonbit
+let logger = LibraryLogger::new(console_sink())
+  .with_trace_context(trace_context("trace-1", "span-1"))
+```
+
+The derived facade preserves its library-facing API while wrapping the sink with context fields. Use `to_logger()` only when broader composition is required.

docs/api/logger-with-trace-context.md

@@ -0,0 +1,22 @@
+---
+name: logger-with-trace-context
+group: api
+category: logger
+update-time: 20260719
+description: Bind a TraceContext to every record from a synchronous Logger.
+key-word:
+    - logger
+    - trace
+    - context
+---
+
+## Logger-with-trace-context
+
+```moonbit
+pub fn[S] Logger::with_trace_context(
+  self : Logger[S],
+  context : TraceContext,
+) -> Logger[ContextSink[S]]
+```
+
+Returns a derived logger that prepends the context fields to every record. The original logger is unchanged. This is equivalent to `with_context_fields(context.as_fields())`, while making trace intent explicit.

docs/api/trace-context.md

@@ -0,0 +1,25 @@
+---
+name: trace-context
+group: api
+category: observability
+update-time: 20260719
+description: Represent and bind distributed trace metadata using stable structured-log fields.
+key-word:
+    - trace
+    - context
+    - observability
+---
+
+## Trace-context
+
+`TraceContext` carries the standard log fields used to correlate records with distributed traces: `trace_id`, `span_id`, `trace_flags`, and optional `trace_state`.
+
+```moonbit
+let context = trace_context(
+  "4bf92f3577b34da6a3ce929d0e0e4736",
+  "00f067aa0ba902b7",
+  trace_state="vendor=value",
+)
+```
+
+Use `context.as_fields()` when integrating with a custom carrier, or pass the value to a logger's `with_trace_context(...)` helper. BitLogger does not parse HTTP headers or export OTLP data; an application-owned tracing library remains responsible for propagation and sampling.

docs/extend/index.md

@@ -10,5 +10,6 @@ Start from an [Example flow](../examples/index.md), then add one extension at a
 | Send records to multiple destinations or route by level | [Sink composition](./composition.md) | More explicit construction than presets. |
 | Control terminal appearance | [Text formatting](./formatting.md) | Formatting affects presentation, not record structure. |
 | Share code across native and web targets | [Target boundaries](./targets.md) | File and async runtime behavior differ by backend. |
+| Correlate logs with distributed requests | [Trace context](./observability.md) | Propagation and export stay application-owned. |
 
 For exact function signatures, follow each page's links into the [API reference](../api/index.md).

docs/extend/observability.md

@@ -0,0 +1,18 @@
+# Trace Context
+
+BitLogger keeps trace interoperability in its structured record model rather than owning HTTP propagation or a telemetry transport. Use the tracing library already selected by the application to extract a request context, then bind its identifiers to the logger.
+
+```moonbit
+let request_logger = logger.with_trace_context(
+  @log.trace_context(
+    trace_id,
+    span_id,
+    trace_flags="01",
+    trace_state=trace_state,
+  ),
+)
+```
+
+Every record from `request_logger` receives `trace_id`, `span_id`, `trace_flags`, and, when supplied, `trace_state`. The base logger is unchanged, so a child request cannot leak identifiers into unrelated work.
+
+Use `context.as_fields()` for a custom logger facade. BitLogger intentionally does not parse `traceparent` headers, create spans, make sampling decisions, or export OTLP data; those concerns remain with the application tracing implementation.

docs/zh/extend/index.md

@@ -10,5 +10,6 @@
 | 同时发送到多个位置或按 level 路由 | [Sink 组合](./composition.md) | 比 preset 更需要显式构造。 |
 | 调整终端可读性 | [文本格式](./formatting.md) | 格式只改变呈现，不改变记录结构。 |
 | 在 native 与 web 目标之间共享代码 | [目标平台边界](./targets.md) | 文件与异步运行时行为因后端而异。 |
+| 将日志关联到分布式请求 | [Trace context](./observability.md) | 传播与导出仍由应用负责。 |
 
 需要精确函数签名时，沿页面链接进入[英文 API 参考](../../api/index.md)。

docs/zh/extend/observability.md

@@ -0,0 +1,13 @@
+# Trace Context
+
+BitLogger 通过结构化字段承载 trace 上下文，不负责 HTTP 传播或遥测传输。应用应继续使用已选定的 tracing 库提取请求上下文，再把标识绑定到 logger。
+
+```moonbit
+let request_logger = logger.with_trace_context(
+  @log.trace_context(trace_id, span_id, trace_flags="01"),
+)
+```
+
+派生 logger 的每条记录都会带有 `trace_id`、`span_id`、`trace_flags`，以及传入时的 `trace_state`。原 logger 不会被修改，避免请求上下文泄漏到无关任务。
+
+`context.as_fields()` 可用于自定义 facade。`traceparent` 解析、span 创建、采样与 OTLP 导出仍由应用选用的 tracing 实现负责。