[Feature] Standardized Structured Logging across Polyglot Workers

[ElioNeto]

Context

To build a great developer experience and allow for real-time log monitoring (see #53 — TUI Log Tailing), all processes in a vyx project — the Go Core, Node.js workers, and Python workers — must emit logs in a unified, machine-readable format.

This is a foundational piece of the vyx observability stack. Without it, building tools like the TUI, log aggregation, or alerting on top of vyx is impractical.

The Problem

Today, each runtime uses its own logging convention:

Runtime	Default output	Format
Go Core	zap	JSON (production), text (dev)
Node.js workers	console.log	Unstructured text
Python workers	logging module	Unstructured text

Without a shared schema, it is impossible to:

• Correlate logs across workers by req_id (see [Feature] End-to-End Request Tracing (Correlation IDs) across Go Core and Workers #52)
• Parse and aggregate logs in the TUI (see [Feature] Standardized Structured Logging across Polyglot Workers #53)
• Search or filter logs programmatically

Proposed Solution

Define a standard JSON log schema for vyx and implement it in every worker SDK. The Go Core will capture worker stdout and can route or re-emit structured log entries.

Standard Log Schema

{
  "timestamp": "2026-03-13T21:00:00.000Z",
  "level": "INFO",
  "service": "node:api",
  "req_id": "123e4567-e89b-12d3-a456-426614174000",
  "message": "User validation passed",
  "data": {}
}

Field	Type	Required	Description
timestamp	ISO 8601 string	✅	UTC timestamp
level	DEBUG / INFO / WARN / ERROR	✅	Log severity
service	string	✅	Worker ID as defined in vyx.yaml (e.g. node:api)
req_id	UUID string	✔ optional	Correlation ID from the active request context
message	string	✅	Human-readable log message
data	object	✔ optional	Arbitrary structured metadata

Implementation Plan

Go Core

Already uses zap with JSON in production mode. Needs verification that service and req_id fields are always present in access logs.

Node.js Worker SDK

Provide a vyx-logger utility that wraps output and automatically injects req_id from AsyncLocalStorage (set by the IPC handler on each request).

// Usage in a worker handler:
import { logger } from '@vyx/worker';
logger.info('User validation passed', { userId: 42 });
// Output: {"timestamp":"...","level":"INFO","service":"node:api","req_id":"...","message":"User validation passed","data":{"userId":42}}

Python Worker SDK

Provide a VyxLogger class that uses logging.Formatter with JSON output and reads req_id from the active contextvars.ContextVar.

# Usage in a worker handler:
from vyx import logger
logger.info("User validation passed", extra={"user_id": 42})

Acceptance Criteria

• Standard JSON log schema documented (this issue or LOGGING_SPEC.md)
• Go Core emits structured JSON logs with service and req_id fields on all access log entries
• Node.js worker SDK provides a structured logger that automatically injects req_id from context
• Python worker SDK provides a structured logger that automatically injects req_id from context
• Go worker SDK exposes a context-aware structured logger wrapping zap or slog
• All SDKs emit logs to stdout so the Go Core can capture and route them
• Documentation updated with logging usage examples for each runtime

Dependencies

• Requires: [Feature] End-to-End Request Tracing (Correlation IDs) across Go Core and Workers #52 — End-to-End Request Tracing (Correlation IDs) must be implemented first so req_id is available in worker contexts
• Enables: [Feature] Standardized Structured Logging across Polyglot Workers #53 — TUI Log Tailing (needs structured JSON to parse and display logs)

References

• core/infrastructure/logger/ — existing Go logger infrastructure
• core/application/gateway/dispatcher.go — access log emission
• Spec §6 – Observability