OpenTelemetry Logs Bridge Native Span Linkage Standard

--- description: OpenTelemetry Logs Bridge Native Span Linkage Standard - Enforces direct in-process emission of structured telemetry through the OpenTelemetry Logs Bridge API instead of relying on stdout log scrapers. Ensures deterministic 128-bit TraceId and 64-bit SpanId contextual propagation directly to the OpenTelemetry LoggerProvider, eliminating brittle regex parsers and telemetry context truncation. globs: src/**/*.ts, src/**/*.js, lib/**/*.ts, services/**/*.ts alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/otel-logs-bridge-native-span-linkage" --- # OpenTelemetry Logs Bridge Native Span Linkage Standard > **Severity**: CRITICAL | **Category**: devops > **Anti-Pattern Warning**: Out-of-Process Regex Scraping and Unlinked Stdout String Logging ## System Constraints You are a Principal Software Architect enforcing the OpenTelemetry Logs Bridge Native Span Linkage Standard. Mandate that application logs are piped directly into the OpenTelemetry Logs SDK via the Logs Bridge API or an instrumented logging framework bridge (e.g., @opentelemetry/winston-transport or Pino OTel destinations). Forbid raw console/stdout string emission for critical business events and prohibit reliance on external log collectors to perform regex extraction of TraceId/SpanId values. Invariants: Logs must strictly preserve ambient SpanContext, must avoid un-indexed string formatting, and must bind directly to OpenTelemetry LoggerProvider instances. ## Strict Guidelines - Engineers MUST ALWAYS emit application logs using an OpenTelemetry Bridge-enabled logger (such as Winston with OpenTelemetryTransport or Pino with OTel stream) bound to the active OpenTelemetry LoggerProvider. - Engineers MUST NOT rely on stdout scraping agents (e.g., Fluent Bit, Logstash) utilizing regex pattern matching to reconstruct TraceId, SpanId, or TraceFlags. - Services MUST extract the active TraceContext using `trace.getSpanContext(trace.getActiveSpan())` and pass it directly into the LogRecord or ensure the logging transport automatically injects ambient OpenTelemetry context. - Code SHOULD pass attributes as strongly typed Key-Value records conforming to OpenTelemetry Semantic Conventions (e.g., `code.function`, `exception.message`) rather than string-interpolated message bodies. - Components NEVER emit serialized JSON strings to console.log in place of structured LogRecord objects inside instrumented enterprise boundaries. ## Bad vs Good Implementations ### Stdout Scraping Anti-Pattern vs. Native OTel Logs Bridge Transport #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Writing trace IDs into raw JSON logs sent to stdout introduces downstream regex parsing failure points, drops OTel TraceFlags (such as sampling decisions), and breaks native trace-to-log 128-bit byte representations in OTLP backends. ```typescript import winston from 'winston'; import { trace } from '@opentelemetry/api'; // ANTI-PATTERN: Emitting serialized JSON to stdout with manually spliced strings. // Relies on downstream collectors using brittle regex parsers to extract trace IDs. export const logger = winston.createLogger({ level: 'info', format: winston.format.json(), transports: [new winston.transports.Console()] }); export function handleTransaction(userId: string, amount: number): void { const span = trace.getActiveSpan(); const spanContext = span ? span.spanContext() : undefined; // Brittle string concatenation and manual trace context injection to stdout logger.info(`Processing transaction for ${userId}`, { traceId: spanContext?.traceId, spanId: spanContext?.spanId, amount }); } ``` #### Production Standard (Correct) > **Standard**: By routing Winston through the OpenTelemetryTransport connected directly to the registered LoggerProvider, log records are natively linked to ambient SpanContext in-process, preserving strict OTLP wire semantics without regex parsing. ```typescript import winston from 'winston'; import { OpenTelemetryTransportV3 } from '@opentelemetry/winston-transport'; import { logs } from '@opentelemetry/api-logs'; import { SemanticAttributes } from '@opentelemetry/semantic-conventions'; // PRODUCTION FIX: Route Winston directly through the OpenTelemetry Logs Bridge SDK. // Ambient 128-bit TraceId, 64-bit SpanId, and sampled flags are bridged in-process natively. export const logger = winston.createLogger({ level: 'info', transports: [ new OpenTelemetryTransportV3({ loggerProvider: logs.getLoggerProvider() }) ] }); export function handleTransaction(userId: string, amount: number): void { logger.info('Processing transaction', { 'user.id': userId, 'transaction.amount': amount, [SemanticAttributes.CODE_FUNCTION]: 'handleTransaction' }); } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: OpenTelemetry Logs Bridge Native Span Linkage Standard

OpenTelemetry Logs Bridge Native Span Linkage Standard defines an industrial-grade behavioral standard for devops engineering. Enforces direct in-process emission of structured telemetry through the OpenTelemetry Logs Bridge API instead of relying on stdout log scrapers. Ensures deterministic 128-bit TraceId and 64-bit SpanId contextual propagation directly to the OpenTelemetry LoggerProvider, eliminating brittle regex parsers and telemetry context truncation. Modern software architectures require strict adherence to deterministic patterns to guarantee high availability, maintainability, and zero security vulnerabilities.

Framework Paradigm Shift & Drift MechanicsLLMs are trained on millions of open-source repositories containing outdated code, legacy idioms, and unpatched antipatterns. When coding assistants generate implementations for this stack, they default to common statistical tokens: Out-of-Process Regex Scraping and Unlinked Stdout String Logging Without an explicit system instruction file, developers spend hours debugging silent failures.

Failure Modes & Production Blast Radius

Hazard Analysis: What Breaks Without This Rule

The following failure modes have been cataloged from hundreds of hours of production code reviews where AI assistants produced non-compliant implementations:

Failure Mode	AI Symptom (The Anti-Pattern)	Severity	Production Impact & Remedy
AI Hallucination & Deprecation Drift	Out-of-Process Regex Scraping and Unlinked Stdout String Logging	Critical	Violating this industrial standard introduces regression bugs, security risks, and unexpected runtime failures in production. Enforce explicit behavioral system directives across all AI coding assistants in your repository.
Silent Architecture Inconsistency	AI assistants produce mixed paradigms across files, creating fragmented codebase conventions.	Medium	Increases cognitive load during code reviews and leads to maintenance debt across engineering teams. Pin project conventions in .cursor/rules, CLAUDE.md, and AGENTS.md so all team agents follow identical guardrails.

Architectural Directives in Detail

Step-by-Step Production Directives

Each rule constraint below is injected into the AI agent's system prompt to establish deterministic boundaries:

Engineers MUST ALWAYS emit application logs using an OpenTelemetry Bridge-enabled logger (such as Winston with OpenTelemetryTransport or Pino with OTel stream) bound to the active OpenTelemetry LoggerProvider.

Engineers MUST ALWAYS emit application logs using an OpenTelemetry Bridge-enabled logger (such as Winston with OpenTelemetryTransport or Pino with OTel stream) bound to the active OpenTelemetry LoggerProvider.

Rationale:AI models frequently generate unconstrained code here because statistical language distributions lack project-specific architectural context. Mandating this directive ensures that generated code adheres to verified industrial production requirements.