loggily 0.3.0 → 0.4.0

package/README.md

@@ -1,25 +1,29 @@
-# loggily
+# Loggily
 
 **Clarity without the clutter.**
 
+One library. One namespace tree. One output pipeline. For logs (structured JSON or console), debug(), and tracing spans. Near-zero overhead from disabled log levels. Pure TypeScript. ~3KB. Zero dependencies.
+
 [![Tests](https://github.com/beorn/loggily/actions/workflows/test.yml/badge.svg)](https://github.com/beorn/loggily/actions/workflows/test.yml)
-[![TypeScript](https://img.shields.io/badge/TypeScript-5.0+-blue.svg)](https://www.typescriptlang.org/)
+[![TypeScript](https://img.shields.io/badge/TypeScript-5.2+-blue.svg)](https://www.typescriptlang.org/)
 [![MIT License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
 
-Debug logging, structured logs, and distributed tracing — integrated into one **~3KB** library with a single API. Zero dependencies.
-
-Most projects wire together three separate tools that don't talk to each other: **debug** for conditional output, **pino/winston** for production logs, **OpenTelemetry** for tracing. loggily integrates all three into one unified system — same namespace tree, same output pipeline, same `?.` zero-overhead pattern. Every logger is a potential span: call `.span()` and it becomes one, with automatic timing, parent-child tracking, and trace IDs. Nothing to sync, nothing to configure separately.
-
-In development, you get colorized console output with timestamps, level colors, and clickable source lines — loggily uses native `console` methods so stack traces stay intact in DevTools. In production, the same code emits structured JSON. No config change needed.
-
-Read **[The Journey](docs/guide.md)** for the full story.
+> Early release (0.x) -- API may evolve before 1.0.
 
 ## Install
 
 ```bash
-bun add loggily    # or: npm install loggily
+npm install loggily
 ```
 
+| Requirement   | Version                                           |
+| ------------- | ------------------------------------------------- |
+| Node.js       | 18+                                               |
+| Bun           | 1.0+                                              |
+| TypeScript    | 5.2+ (for `using`; `.end()` works on any version) |
+| Module format | ESM-only                                          |
+| Browser       | Supported via conditional export                  |
+
 ## Quick Start
 
 ```typescript
@@ -27,55 +31,96 @@ import { createLogger } from "loggily"
 
 const log = createLogger("myapp")
 
-// ?. skips the entire call — including argument evaluation — when the level is disabled (near-zero cost)
+// ?. skips the entire call — including argument evaluation — when the level is disabled
 log.info?.("server started", { port: 3000 })
 log.debug?.("cache hit", { key: "user:42" })
 log.error?.(new Error("connection lost"))
+```
+
+Output in development (colorized with timestamps and clickable source lines):
+
+```
+14:32:15 INFO myapp server started {port: 3000}
+14:32:15 DEBUG myapp cache hit {key: "user:42"}
+14:32:15 ERROR myapp connection lost
+```
+
+Set `NODE_ENV=production` or `LOG_FORMAT=json` and the same code emits structured JSON:
+
+```json
+{ "time": "2024-01-15T14:32:15.123Z", "level": "info", "name": "myapp", "msg": "server started", "port": 3000 }
+```
 
-// Spans time operations automatically
+### Spans
+
+Time operations with lightweight spans. Uses TC39 [Explicit Resource Management](https://github.com/tc39/proposal-explicit-resource-management) (`using` requires TypeScript 5.2+ and runtime support). For other environments, call `.end()` manually:
+
+```typescript
+// With `using` (TS 5.2+, Bun 1.0+, Node 22+)
 {
   using span = log.span("db:query", { table: "users" })
   const users = await db.query("SELECT * FROM users")
   span.spanData.count = users.length
 }
 // Output: SPAN myapp:db:query (45ms) {count: 100, table: "users"}
+
+// Without `using` — works on any runtime
+const span = log.span("db:query", { table: "users" })
+try {
+  const users = await db.query("SELECT * FROM users")
+  span.spanData.count = users.length
+} finally {
+  span.end()
+}
 ```
 
-## Why Another Logger?
+## Why Loggily?
+
+One API for debug-style namespace logging, structured JSON output, and lightweight spans. Many projects end up with separate tools for these -- **debug** for conditional output, **pino/winston** for production logs, a tracing SDK for timings -- with separate configs, formats, and APIs. Loggily integrates all three into one namespace tree, one output pipeline, one `?.` pattern.
+
+### Near-zero cost for disabled logs
 
-Beyond the integration story above, most loggers also waste work when logging is disabled. Even with a noop function, arguments are still evaluated:
+Most loggers waste work when logging is disabled. Even with a noop function, arguments are still evaluated:
 
 ```typescript
 // Traditional — args are ALWAYS evaluated, even when debug is off
 log.debug(`state: ${JSON.stringify(computeExpensiveState())}`)
 ```
 
-loggily uses optional chaining to skip the entire call — including argument evaluation:
+Loggily uses optional chaining to skip the entire call — including argument evaluation:
 
 ```typescript
-// loggily — args are NOT evaluated when disabled
+// Loggily — args are NOT evaluated when disabled
 log.debug?.(`state: ${JSON.stringify(computeExpensiveState())}`)
 ```
 
 For trivial arguments the difference is negligible. But for real-world logging — string interpolation, JSON serialization, state snapshots — optional chaining is typically **10x+ faster** because it skips the work entirely. The more expensive your arguments, the bigger the win.
 
+> **Note**: The big performance advantage is specifically for disabled logging with expensive arguments, not universal logger throughput. Pino is optimized for high-throughput enabled JSON logging; Loggily's biggest advantage is skipping work when logs are disabled. See [benchmarks](https://beorn.codes/loggily/guide/benchmarks) for detailed numbers per scenario.
+
 ## Features
 
 - **Namespace hierarchy** — organize logs with `:` separators. `log.logger("db")` creates `myapp:db`. Children inherit parent context.
-- **Spans** — time any operation with `using span = log.span("name")`. Automatic duration, parent-child tracking, and trace IDs. _(Uses TC39 [Explicit Resource Management](https://github.com/tc39/proposal-explicit-resource-management); call `span.end()` manually if your runtime doesn't support `using` yet.)_
+- **Lightweight spans and trace IDs** — time any operation with `using span = log.span("name")`. Automatic duration, parent-child tracking, and trace IDs. For full OpenTelemetry interoperability with exporters and propagation, use OpenTelemetry.
 - **Lazy messages** — `log.debug?.(() => expensiveString())` skips the function entirely when disabled.
 - **Child context** — `log.child({ requestId })` adds structured fields to every message in the chain.
 - **Dev & production** — colorized console with timestamps, level colors, and clickable source lines in development. Structured JSON in production. Switches automatically via `NODE_ENV` — same code, zero config.
 - **File writer** — `addWriter()` + `createFileWriter()` for buffered file output with auto-flush.
 - **Worker threads** — forward logs from workers to the main thread with full type safety (`loggily/worker`).
-- **Drop-in debug replacement** — reads `DEBUG=myapp:*` just like the debug package. Swap your imports in minutes.
+- **debug-compatible namespace filtering** — reads `DEBUG=myapp:*` just like the debug package. Easy migration from debug — see the [migration guide](https://beorn.codes/loggily/guide/migration-from-debug).
+
+## When Not to Use Loggily
+
+- **Max-throughput transport pipelines** — use [Pino](https://getpino.io/) for worker-thread transports, custom serializers, and log rotation.
+- **Vendor/exporter interop** — use [OpenTelemetry](https://opentelemetry.io/) for distributed tracing with propagation, semantic conventions, and backend integrations.
+- **Tiny dev-only namespace logs** — use [debug](https://github.com/debug-js/debug) if all you need is conditional dev output with zero ceremony.
 
 ## Documentation
 
-- **[The Journey](docs/guide.md)** — progressive guide from first log to full observability
+- **[Get Started](https://beorn.codes/loggily/guide/journey)** — progressive guide from first log to full observability
 - **[Full docs site](https://beorn.codes/loggily/)** — guides, API reference, migration guides
-- [Comparison](docs/comparison.md) — vs Pino, Winston, Bunyan, debug
-- [Migration from debug](docs/migration-from-debug.md) — step-by-step migration guide
+- [Comparison](https://beorn.codes/loggily/guide/comparison) — vs Pino, Winston, Bunyan, debug
+- [Migration from debug](https://beorn.codes/loggily/guide/migration-from-debug) — step-by-step migration guide
 
 ## Environment Variables
 
@@ -101,7 +146,7 @@ For trivial arguments the difference is negligible. But for real-world logging
 | `setLogLevel()` / `setLogFormat()` / `enableSpans()`                   | Runtime configuration                                         |
 | `createWorkerLogger()` / `createWorkerLogHandler()`                    | Worker thread support (`loggily/worker`)                      |
 
-See the [full API reference](docs/api-reference.md) for all functions and options.
+See the [full API reference](https://beorn.codes/loggily/api/) for all functions and options.
 
 ## License
 

package/package.json

@@ -1,27 +1,37 @@
 {
   "name": "loggily",
-  "version": "0.3.0",
-  "description": "Structured logging with spans. ~3KB, zero-overhead disabled logging via optional chaining.",
+  "version": "0.4.0",
+  "description": "TypeScript logger with debug-style namespaces, structured JSON output, and lightweight spans. Disabled logs skip argument evaluation via optional chaining.",
   "keywords": [
+    "browser",
+    "bun",
+    "debug",
+    "json-logger",
     "logger",
     "logging",
+    "namespace",
+    "node",
+    "observability",
     "optional-chaining",
     "spans",
-    "structured",
+    "structured-logging",
     "tracing",
-    "typescript",
-    "zero-overhead"
+    "typescript"
   ],
-  "homepage": "https://beorn.codes/decant/",
+  "homepage": "https://beorn.codes/loggily/",
   "bugs": {
-    "url": "https://github.com/beorn/decant/issues"
+    "url": "https://github.com/beorn/loggily/issues"
   },
   "license": "MIT",
   "author": "Beorn",
   "repository": {
     "type": "git",
-    "url": "https://github.com/beorn/decant.git"
+    "url": "https://github.com/beorn/loggily.git"
   },
+  "files": [
+    "src",
+    "dist"
+  ],
   "type": "module",
   "module": "src/index.ts",
   "types": "./dist/index.d.ts",
@@ -48,13 +58,16 @@
       "default": "./src/tracing.ts"
     }
   },
+  "publishConfig": {
+    "access": "public"
+  },
   "scripts": {
     "build": "tsc",
     "typecheck": "tsc --noEmit",
     "test": "bunx --bun vitest run",
-    "docs:dev": "vitepress dev docs/site",
-    "docs:build": "vitepress build docs/site",
-    "docs:preview": "vitepress preview docs/site"
+    "docs:dev": "vitepress dev docs",
+    "docs:build": "vitepress build docs",
+    "docs:preview": "vitepress preview docs"
   },
   "devDependencies": {
     "@types/node": "^25.3.3",

package/src/context.ts

@@ -41,6 +41,13 @@ export interface SpanContext {
 let storage: AsyncLocalStorage<SpanContext> | null = null
 let contextEnabled = false
 
+/**
+ * Map from spanId → the SpanContext that was active when the span was entered.
+ * Used to restore the exact previous context on exit, avoiding corruption
+ * from non-LIFO end() ordering.
+ */
+const previousContexts = new Map<string, SpanContext | null>()
+
 // ============ API ============
 
 /**
@@ -99,30 +106,38 @@ export function getCurrentSpan(): SpanContext | null {
  * spans with `using` — since `using` doesn't wrap user code in a callback,
  * `enterWith()` is the right primitive.
  *
+ * Captures the full previous SpanContext snapshot so it can be restored
+ * exactly on exit, even with non-LIFO end() ordering.
+ *
  * @internal
  */
 export function enterSpanContext(spanId: string, traceId: string, parentId: string | null): void {
   if (!contextEnabled || !storage) return
+
+  // Capture the full previous context before overwriting
+  const previous = storage.getStore() ?? null
+  previousContexts.set(spanId, previous)
+
   storage.enterWith({ spanId, traceId, parentId })
 }
 
 /**
- * Restore the parent span context (called when a span ends).
- * Re-enters the parent's context, or clears the context if there is no parent.
+ * Restore the previous span context (called when a span ends).
+ * Restores the exact SpanContext snapshot captured at enter time,
+ * preventing corruption from non-LIFO end() ordering.
  *
  * @internal
  */
-export function exitSpanContext(parentId: string | null, parentTraceId: string | null): void {
+export function exitSpanContext(spanId: string): void {
   if (!contextEnabled || !storage) return
-  if (parentId && parentTraceId) {
-    // Restore parent context — note: we don't have the parent's parentId
-    // but that's fine since this context is only used for auto-tagging and
-    // auto-parenting new child spans (which will read spanId and traceId).
-    storage.enterWith({ spanId: parentId, traceId: parentTraceId, parentId: null })
+
+  const previous = previousContexts.get(spanId)
+  previousContexts.delete(spanId)
+
+  if (previous) {
+    storage.enterWith(previous)
   } else {
-    // No parent — exit the context entirely
-    // enterWith(undefined as any) is not ideal, but there's no "exitWith"
-    // We use a sentinel to indicate "no active span"
+    // No previous context — exit entirely
     storage.enterWith(undefined as unknown as SpanContext)
   }
 }

package/src/core.ts

@@ -179,26 +179,39 @@ if (traceEnv && traceEnv !== "1" && traceEnv !== "true") {
 
 // Debug namespace filter (DEBUG=myapp or DEBUG=myapp,-myapp:noisy or DEBUG=*)
 // Supports negative patterns with `-` prefix (like the `debug` npm package)
-const debugEnv = getEnv("DEBUG")
-let debugIncludes: Set<string> | null = null
-let debugExcludes: Set<string> | null = null
-if (debugEnv) {
-  const parts = debugEnv.split(",").map((s) => s.trim())
-  const includes: string[] = []
-  const excludes: string[] = []
-  for (const part of parts) {
+
+/** Parse a comma-separated namespace filter into include/exclude sets */
+function parseNamespaceFilter(input: string[]): {
+  includes: Set<string> | null
+  excludes: Set<string> | null
+} {
+  const includeList: string[] = []
+  const excludeList: string[] = []
+  for (const part of input) {
     if (part.startsWith("-")) {
-      excludes.push(part.slice(1))
+      excludeList.push(part.slice(1))
     } else {
-      includes.push(part)
+      includeList.push(part)
     }
   }
-  if (includes.length > 0) {
-    debugIncludes = new Set(includes.some((p) => p === "*" || p === "1" || p === "true") ? ["*"] : includes)
+  return {
+    includes: includeList.length > 0 ? new Set(includeList) : null,
+    excludes: excludeList.length > 0 ? new Set(excludeList) : null,
   }
-  if (excludes.length > 0) {
-    debugExcludes = new Set(excludes)
+}
+
+const debugEnv = getEnv("DEBUG")
+let debugIncludes: Set<string> | null = null
+let debugExcludes: Set<string> | null = null
+if (debugEnv) {
+  const parts = debugEnv.split(",").map((s) => s.trim())
+  const parsed = parseNamespaceFilter(parts)
+  debugIncludes = parsed.includes
+  // Normalize wildcard variants
+  if (debugIncludes && [...debugIncludes].some((p) => p === "*" || p === "1" || p === "true")) {
+    debugIncludes = new Set(["*"])
   }
+  debugExcludes = parsed.excludes
   // Auto-lower log level to at least debug when DEBUG is set
   if (LOG_LEVEL_PRIORITY[currentLogLevel] > LOG_LEVEL_PRIORITY.debug) {
     currentLogLevel = "debug"
@@ -261,17 +274,9 @@ export function setDebugFilter(namespaces: string[] | null): void {
     debugIncludes = null
     debugExcludes = null
   } else {
-    const includes: string[] = []
-    const excludes: string[] = []
-    for (const ns of namespaces) {
-      if (ns.startsWith("-")) {
-        excludes.push(ns.slice(1))
-      } else {
-        includes.push(ns)
-      }
-    }
-    debugIncludes = includes.length > 0 ? new Set(includes) : null
-    debugExcludes = excludes.length > 0 ? new Set(excludes) : null
+    const parsed = parseNamespaceFilter(namespaces)
+    debugIncludes = parsed.includes
+    debugExcludes = parsed.excludes
     if (LOG_LEVEL_PRIORITY[currentLogLevel] > LOG_LEVEL_PRIORITY.debug) {
       currentLogLevel = "debug"
     }
@@ -334,8 +339,8 @@ let _getContextParent: (() => { spanId: string; traceId: string } | null) | null
 /** Hook to enter a span context (sets AsyncLocalStorage for the current async scope) */
 let _enterContext: ((spanId: string, traceId: string, parentId: string | null) => void) | null = null
 
-/** Hook to exit a span context (restores parent or clears) */
-let _exitContext: ((parentId: string | null, parentTraceId: string | null) => void) | null = null
+/** Hook to exit a span context (restores previous context snapshot) */
+let _exitContext: ((spanId: string) => void) | null = null
 
 /**
  * Register context propagation hooks (called by context.ts).
@@ -345,7 +350,7 @@ export function _setContextHooks(hooks: {
   getContextTags: () => Record<string, string>
   getContextParent: () => { spanId: string; traceId: string } | null
   enterContext: (spanId: string, traceId: string, parentId: string | null) => void
-  exitContext: (parentId: string | null, parentTraceId: string | null) => void
+  exitContext: (spanId: string) => void
 }): void {
   _getContextTags = hooks.getContextTags
   _getContextParent = hooks.getContextParent
@@ -376,6 +381,24 @@ function shouldTraceNamespace(namespace: string): boolean {
   return matchesNamespaceSet(namespace, traceFilter)
 }
 
+/**
+ * Safe JSON.stringify that handles bigint, circular refs, symbols, and Error objects.
+ * Prevents crashes from non-serializable values in log data.
+ */
+function safeStringify(value: unknown): string {
+  const seen = new WeakSet()
+  return JSON.stringify(value, (_key, val) => {
+    if (typeof val === "bigint") return val.toString()
+    if (typeof val === "symbol") return val.toString()
+    if (val instanceof Error) return { message: val.message, stack: val.stack, name: val.name }
+    if (typeof val === "object" && val !== null) {
+      if (seen.has(val)) return "[Circular]"
+      seen.add(val)
+    }
+    return val
+  })
+}
+
 function formatConsole(namespace: string, level: string, message: string, data?: Record<string, unknown>): string {
   const time = pc.dim(new Date().toISOString().split("T")[1]?.split(".")[0] || "")
 
@@ -405,7 +428,7 @@ function formatConsole(namespace: string, level: string, message: string, data?:
   let output = `${time} ${levelStr} ${ns} ${message}`
 
   if (data && Object.keys(data).length > 0) {
-    output += ` ${pc.dim(JSON.stringify(data))}`
+    output += ` ${pc.dim(safeStringify(data))}`
   }
 
   return output
@@ -419,14 +442,7 @@ function formatJSON(namespace: string, level: string, message: string, data?: Re
     msg: message,
     ...data,
   }
-  const seen = new WeakSet()
-  return JSON.stringify(entry, (_key, value) => {
-    if (typeof value === "object" && value !== null) {
-      if (seen.has(value)) return "[Circular]"
-      seen.add(value)
-    }
-    return value
-  })
+  return safeStringify(entry)
 }
 
 function matchesNamespaceSet(namespace: string, set: Set<string>): boolean {
@@ -502,7 +518,7 @@ function writeLog(
   }
 }
 
-function writeSpan(namespace: string, duration: number, attrs: Record<string, unknown>): void {
+export function writeSpan(namespace: string, duration: number, attrs: Record<string, unknown>): void {
   if (!shouldTraceNamespace(namespace)) return
   if (!shouldDebugNamespace(namespace)) return
 
@@ -515,6 +531,40 @@ function writeSpan(namespace: string, duration: number, attrs: Record<string, un
   if (!suppressConsole) writeStderr(formatted)
 }
 
+// ============ Shared SpanData Proxy ============
+
+interface SpanDataFields {
+  id: string
+  traceId: string
+  parentId: string | null
+  startTime: number
+  endTime: number | null
+  duration: number | null
+}
+
+/**
+ * Create a proxy that exposes span metadata as readonly and custom attributes as writable.
+ * Shared between core logger spans and worker logger spans.
+ */
+export function createSpanDataProxy(getFields: () => SpanDataFields, attrs: Record<string, unknown>): SpanData {
+  const READONLY_KEYS = new Set(["id", "traceId", "parentId", "startTime", "endTime", "duration"])
+  return new Proxy(attrs, {
+    get(_target, prop) {
+      if (READONLY_KEYS.has(prop as string)) {
+        return getFields()[prop as keyof SpanDataFields]
+      }
+      return attrs[prop as string]
+    },
+    set(_target, prop, value) {
+      if (READONLY_KEYS.has(prop as string)) {
+        return false
+      }
+      attrs[prop as string] = value
+      return true
+    },
+  }) as SpanData
+}
+
 // ============ Implementation ============
 
 interface MutableSpanData {
@@ -556,38 +606,17 @@ function createLoggerImpl(
 
     get spanData(): SpanData | null {
       if (!spanMeta) return null
-      // Return proxy that allows attribute assignment
-      return new Proxy(spanMeta.attrs, {
-        get(_target, prop) {
-          if (prop === "id") return spanMeta.id
-          if (prop === "traceId") return spanMeta.traceId
-          if (prop === "parentId") return spanMeta.parentId
-          if (prop === "startTime") return spanMeta.startTime
-          if (prop === "endTime") return spanMeta.endTime
-          if (prop === "duration") {
-            if (spanMeta.endTime !== null) {
-              return spanMeta.endTime - spanMeta.startTime
-            }
-            return Date.now() - spanMeta.startTime
-          }
-          return spanMeta.attrs[prop as string]
-        },
-        set(_target, prop, value) {
-          // Allow setting custom attributes
-          if (
-            prop !== "id" &&
-            prop !== "traceId" &&
-            prop !== "parentId" &&
-            prop !== "startTime" &&
-            prop !== "endTime" &&
-            prop !== "duration"
-          ) {
-            spanMeta.attrs[prop as string] = value
-            return true
-          }
-          return false
-        },
-      }) as SpanData
+      return createSpanDataProxy(
+        () => ({
+          id: spanMeta.id,
+          traceId: spanMeta.traceId,
+          parentId: spanMeta.parentId,
+          startTime: spanMeta.startTime,
+          endTime: spanMeta.endTime,
+          duration: spanMeta.endTime !== null ? spanMeta.endTime - spanMeta.startTime : Date.now() - spanMeta.startTime,
+        }),
+        spanMeta.attrs,
+      )
     },
 
     trace: (msg, data) => log("trace", msg, data),
@@ -655,8 +684,25 @@ function createLoggerImpl(
         newSpanData.endTime = Date.now()
         newSpanData.duration = newSpanData.endTime - newSpanData.startTime
 
-        // Exit span context (restore parent or clear)
-        _exitContext?.(resolvedParentId, resolvedParentId ? finalTraceId : null)
+        // Collect span data if collection is active
+        if (collectSpans) {
+          collectedSpans.push(
+            createSpanDataProxy(
+              () => ({
+                id: newSpanData.id,
+                traceId: newSpanData.traceId,
+                parentId: newSpanData.parentId,
+                startTime: newSpanData.startTime,
+                endTime: newSpanData.endTime,
+                duration: newSpanData.duration,
+              }),
+              { ...newSpanData.attrs },
+            ),
+          )
+        }
+
+        // Exit span context (restore previous context snapshot)
+        _exitContext?.(newSpanId)
 
         // Only emit span if sampled
         if (sampled) {

package/src/file-writer.ts

@@ -60,8 +60,8 @@ export function createFileWriter(filePath: string, options: FileWriterOptions =
   function flush(): void {
     if (buffer.length === 0 || fd === null) return
     const data = buffer
-    buffer = ""
     writeSync(fd, data)
+    buffer = ""
   }
 
   // Set up periodic flush
@@ -93,12 +93,18 @@ export function createFileWriter(filePath: string, options: FileWriterOptions =
         clearInterval(timer)
         timer = null
       }
-      flush()
-      if (fd !== null) {
-        closeSync(fd)
-        fd = null
+      try {
+        flush()
+      } catch {
+        // Swallow flush errors during close — data loss is unavoidable
+        // at this point, but we must still release the fd and exit handler.
+      } finally {
+        if (fd !== null) {
+          closeSync(fd)
+          fd = null
+        }
+        process.removeListener("exit", exitHandler)
       }
-      process.removeListener("exit", exitHandler)
     },
   }
 }

package/src/index.browser.ts

@@ -51,7 +51,15 @@ export {
 } from "./core.js"
 
 // Tracing utilities (runtime-agnostic, work in browser)
-export { setIdFormat, getIdFormat, type IdFormat, traceparent, setSampleRate, getSampleRate } from "./tracing.js"
+export {
+  setIdFormat,
+  getIdFormat,
+  type IdFormat,
+  traceparent,
+  type TraceparentOptions,
+  setSampleRate,
+  getSampleRate,
+} from "./tracing.js"
 
 // File writer types (exported for type compatibility, but the function throws)
 export type { FileWriterOptions, FileWriter } from "./file-writer.js"

package/src/index.ts

@@ -7,4 +7,12 @@
 
 export * from "./core.js"
 export { createFileWriter, type FileWriter, type FileWriterOptions } from "./file-writer.js"
-export { setIdFormat, getIdFormat, type IdFormat, traceparent, setSampleRate, getSampleRate } from "./tracing.js"
+export {
+  setIdFormat,
+  getIdFormat,
+  type IdFormat,
+  traceparent,
+  type TraceparentOptions,
+  setSampleRate,
+  getSampleRate,
+} from "./tracing.js"

package/src/tracing.ts

@@ -64,6 +64,12 @@ export function resetIdCounters(): void {
 
 // ============ W3C Traceparent ============
 
+/** Options for traceparent header formatting */
+export interface TraceparentOptions {
+  /** Whether this span is sampled. Defaults to true for backwards compatibility. */
+  sampled?: boolean
+}
+
 /**
  * Format a W3C traceparent header from span data.
  *
@@ -71,11 +77,12 @@ export function resetIdCounters(): void {
  * - version: "00" (current W3C spec version)
  * - trace-id: 32 hex chars (128 bits)
  * - span-id: 16 hex chars (64 bits)
- * - trace-flags: "01" (sampled)
+ * - trace-flags: "01" (sampled) or "00" (not sampled)
  *
  * Works with both simple and W3C ID formats. Simple IDs are zero-padded to spec length.
  *
  * @param spanData - Span data with id and traceId
+ * @param options - Optional settings (sampled flag). Defaults to sampled=true.
  * @returns W3C traceparent header string
  *
  * @example
@@ -86,10 +93,11 @@ export function resetIdCounters(): void {
  * fetch(url, { headers: { traceparent: header } })
  * ```
  */
-export function traceparent(spanData: SpanData): string {
+export function traceparent(spanData: SpanData, options?: TraceparentOptions): string {
   const traceId = padHex(spanData.traceId, 32)
   const spanId = padHex(spanData.id, 16)
-  return `00-${traceId}-${spanId}-01`
+  const flags = (options?.sampled ?? true) ? "01" : "00"
+  return `00-${traceId}-${spanId}-${flags}`
 }
 
 /** Pad or hash an ID to the specified hex length */