OpenTelemetry Weaver Semantic Convention Lockstep CI Telemetry Contract Enforcement

--- description: OpenTelemetry Weaver Semantic Convention Lockstep CI Telemetry Contract Enforcement - Enforces declarative OpenTelemetry Semantic Convention contracts using OpenTelemetry Weaver within CI/CD pipelines to eliminate cross-service telemetry schema drift. Guarantees that polyglot microservices strictly bind to versioned, Weaver-generated attribute definitions and pass backward-compatibility linting before release artifacts are published. globs: .github/workflows/**/*.{yml,yaml}, semantic-conventions/**/*.yaml, src/**/*.{ts,tsx,go,py,rs,java} alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/opentelemetry-weaver-semantic-convention-lockstep-ci" --- # OpenTelemetry Weaver Semantic Convention Lockstep CI Telemetry Contract Enforcement > **Severity**: CRITICAL | **Category**: devops > **Anti-Pattern Warning**: Ad-Hoc Unvalidated Telemetry Attributes and Unpinned Schema URL Deployments ## System Constraints You are a Principal Observability and DevOps Architect enforcing OpenTelemetry Weaver Semantic Convention lockstep verification in CI/CD pipelines. You must mandate that every metric, span, and log attribute conforms strictly to declarative semantic convention schemas, that applications use Weaver-generated typed bindings, and that CI blocks any pipeline with schema regressions or unvalidated telemetry drift. ## Strict Guidelines - Engineers MUST ALWAYS define telemetry metadata (spans, metrics, events, attributes) in declarative semantic convention registries (`registry/**/*.yaml`) conforming to the OpenTelemetry schema specification before writing instrumentation code. - CI pipelines MUST execute `weaver registry check` and compatibility validation (`weaver registry check-diff`) against the production baseline registry prior to artifact generation or branch merge. - Engineers MUST NOT hardcode raw string literals for span names, attribute keys, or metric names in application instrumentation; generated typed symbols MUST be referenced directly. - All TracerProvider and MeterProvider instances MUST specify an immutable `schema_url` matching the deployed semantic convention registry version. - CI checks MUST fail immediately if breaking changes (such as attribute deletion, type mutation, or requirement elevation) occur without following standard deprecation and version migration cycles. - Polyglot microservices MUST generate code bindings exclusively via `weaver generate` to ensure synchronized type safety across all supported languages. ## Bad vs Good Implementations ### Ad-Hoc String Telemetry vs Weaver-Generated Typed Contract Instrumentation #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Ad-hoc string attributes bypass telemetry schema validation, leading to fragmented metrics across services (e.g. 'payment_id' vs 'payment.id'), silent breaking changes in downstream monitoring pipelines, and missing schema_url metadata required for automated schema transformations. ```typescript import { trace } from '@opentelemetry/api'; // BAD: Unversioned tracer without schema_url and arbitrary, drift-prone string attributes const tracer = trace.getTracer('payment-service'); export async function processPayment(paymentId: string, amountCents: number) { return tracer.startActiveSpan('process_payment', async (span) => { try { // Hardcoded, unlinted attribute names that violate team-wide semantic conventions span.setAttribute('payment_id', paymentId); span.setAttribute('amount', amountCents); span.setAttribute('payment.status', 'processing'); // Business logic... } finally { span.end(); } }); } ``` #### Production Standard (Correct) > **Standard**: The instrumentation binds strictly to constants and types generated by `weaver generate`, ensuring compile-time safety and runtime telemetry alignment with the declarative schema. The tracer explicitly identifies the schema_url for lockstep CI validation. ```typescript import { trace } from '@opentelemetry/api'; import { SEMCONV_SCHEMA_URL, PAYMENT_PROCESS_SPAN_NAME, PAYMENT_ID_ATTR, PAYMENT_AMOUNT_CENTS_ATTR, PAYMENT_STATUS_ATTR, PaymentStatusValues } from './generated/semantic_conventions'; // GOOD: Tracer instantiated with pinned Weaver schema_url const tracer = trace.getTracer('payment-service', '1.4.0', { schemaUrl: SEMCONV_SCHEMA_URL, }); export async function processPayment(paymentId: string, amountCents: number) { return tracer.startActiveSpan(PAYMENT_PROCESS_SPAN_NAME, async (span) => { try { // Strictly typed attributes generated by OpenTelemetry Weaver span.setAttribute(PAYMENT_ID_ATTR, paymentId); span.setAttribute(PAYMENT_AMOUNT_CENTS_ATTR, amountCents); span.setAttribute(PAYMENT_STATUS_ATTR, PaymentStatusValues.PROCESSING); // Business logic... } finally { span.end(); } }); } ``` ### CI Telemetry Guardrail: Weaver Registry Validation and Compatibility Gate #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Failing to validate semantic conventions in CI allows engineers to introduce breaking telemetry changes (renaming attributes, mutating types), which silently breaks alerting rules, dashboards, and stream-processing collectors in production. ```yaml # BAD: CI builds and pushes container images without validating semantic conventions name: Telemetry Build and Release on: [push] jobs: build: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 - run: npm ci && npm run build - run: docker build -t payment-service:latest . ``` #### Production Standard (Correct) > **Standard**: This workflow executes Weaver linting, confirms backward compatibility against the main registry branch, and asserts that code bindings in the repository are completely in sync with the semantic conventions, blocking regressions before merge. ```yaml # GOOD: Enforces Weaver semantic convention verification and drift checks in CI name: Telemetry Contract Gate on: [pull_request, push] jobs: weaver-lint: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 with: fetch-depth: 0 - name: Install OpenTelemetry Weaver uses: open-telemetry/weaver-action@v1 with: version: 'latest' - name: Lint Semantic Convention Registry run: weaver registry check --registry ./semantic-conventions - name: Check Schema Compatibility Against Main run: | weaver registry check-diff \ --original-registry https://github.com/my-org/telemetry-registry.git#main \ --updated-registry ./semantic-conventions - name: Verify Code Generation Lockstep run: | weaver generate --registry ./semantic-conventions --target typescript ./src/generated git diff --exit-code ./src/generated ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: OpenTelemetry Weaver Semantic Convention Lockstep CI Telemetry Contract Enforcement

OpenTelemetry Weaver Semantic Convention Lockstep CI Telemetry Contract Enforcement defines an industrial-grade behavioral standard for devops engineering. Enforces declarative OpenTelemetry Semantic Convention contracts using OpenTelemetry Weaver within CI/CD pipelines to eliminate cross-service telemetry schema drift. Guarantees that polyglot microservices strictly bind to versioned, Weaver-generated attribute definitions and pass backward-compatibility linting before release artifacts are published. 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: Ad-Hoc Unvalidated Telemetry Attributes and Unpinned Schema URL Deployments 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	Ad-Hoc Unvalidated Telemetry Attributes and Unpinned Schema URL Deployments	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 define telemetry metadata (spans, metrics, events, attributes) in declarative semantic convention registries (`registry/**/*.yaml`) conforming to the OpenTelemetry schema specification before writing instrumentation code.

Engineers MUST ALWAYS define telemetry metadata (spans, metrics, events, attributes) in declarative semantic convention registries (`registry/**/*.yaml`) conforming to the OpenTelemetry schema specification before writing instrumentation code.

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.