OTel Collector Weaver Semantic Convention Schema Check

--- description: OTel Collector Weaver Semantic Convention Schema Check - Enforces pre-deployment schema validation using OpenTelemetry Weaver across CI/CD pipelines to guarantee all telemetry payloads conform to enterprise semantic convention registries. Prevents breaking downstream telemetry contracts, unvetted custom attribute injection, and catalog fragmentation across collectors and services. globs: .github/workflows/**/*.{yml,yaml}, weaver.yaml, registry/**/*.{yml,yaml}, **/otel-collector*.{yml,yaml}, deploy/helm/**/*.{yml,yaml} alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/otel-collector-weaver-schema-validation-check" --- # OTel Collector Weaver Semantic Convention Schema Check > **Severity**: CRITICAL | **Category**: devops > **Anti-Pattern Warning**: Deploying Telemetry Pipelines Without Automated Weaver Semantic Convention Validation ## System Constraints You are a Principal Software Architect enforcing enterprise telemetry governance using OpenTelemetry Weaver. You must mandate strict CI/CD gatekeeping that validates collector processor configurations, application telemetry schemas, and custom attribute extensions against centralized OpenTelemetry semantic convention registries before deployment. ## Strict Guidelines - CI/CD pipelines MUST execute 'weaver registry check' and 'weaver registry resolve' against enterprise registries on all collector config and schema changes. - Engineers MUST NOT introduce ad-hoc telemetry attributes in Collector transform or attributes processors without formal registration in the semantic convention registry. - Collector configurations MUST explicitly declare target 'schema_url' attributes across all telemetry transformation pipelines. - CI workflows MUST fail telemetry configuration deployment jobs immediately if Weaver detects unmapped schema breaking changes or backward-incompatibility conflicts. - Telemetry registry definitions MUST define explicit type, stability, and namespace constraints for every custom resource, span, metric, and log attribute. ## Bad vs Good Implementations ### CI/CD Pipeline Weaver Verification and Schema Conformance #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: The workflow deploys telemetry collector configurations directly into production without semantic convention schema validation. The collector injects non-standard attributes ('cust_id', 'env') that violate OpenTelemetry standards, leading to fragmented metrics/traces and downstream dashboard breakage. ```yaml # .github/workflows/deploy-collector.yml name: Deploy OTel Collector on: push: branches: [main] jobs: deploy: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 - name: Deploy Collector Config run: | # Anti-pattern: Direct deployment without checking semantic schema contracts kubectl apply -f otel-collector-config.yaml # otel-collector-config.yaml # Transform processor injects rogue, unvetted attributes violating OpenTelemetry conventions processors: transform: error_mode: ignore log_statements: - context: resource statements: - set(attributes["cust_id"], "legacy-1234") # Non-standard attribute - set(attributes["env"], "production") # Violates deployment.environment.name ``` #### Production Standard (Correct) > **Standard**: The CI workflow enforces rigorous pre-deployment validation using Weaver. It verifies custom semantic conventions against the enterprise registry, checks for schema compatibility, and blocks deployment if unapproved attribute mutations are detected. ```yaml # .github/workflows/deploy-collector.yml name: Validate and Deploy OTel Collector on: push: branches: [main] pull_request: branches: [main] jobs: weaver-validation: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 - name: Install OpenTelemetry Weaver uses: open-telemetry/weaver-action@v1 with: version: '0.12.0' - name: Run Weaver Semantic Convention Check run: | # Validates enterprise registry syntax and structural consistency weaver registry check --registry ./semantic-conventions # Resolves and checks compatibility against target schema weaver registry resolve --registry ./semantic-conventions --output ./resolved-schema - name: Validate Collector Transform Semantics run: | # Verify collector configs against Weaver schema resolution weaver check-collector-config --registry ./resolved-schema --config ./otel-collector-config.yaml deploy: needs: weaver-validation if: github.ref == 'refs/heads/main' runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 - name: Deploy Collector Config run: kubectl apply -f otel-collector-config.yaml ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: OTel Collector Weaver Semantic Convention Schema Check

OTel Collector Weaver Semantic Convention Schema Check defines an industrial-grade behavioral standard for devops engineering. Enforces pre-deployment schema validation using OpenTelemetry Weaver across CI/CD pipelines to guarantee all telemetry payloads conform to enterprise semantic convention registries. Prevents breaking downstream telemetry contracts, unvetted custom attribute injection, and catalog fragmentation across collectors and services. 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: Deploying Telemetry Pipelines Without Automated Weaver Semantic Convention Validation 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	Deploying Telemetry Pipelines Without Automated Weaver Semantic Convention Validation	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:

CI/CD pipelines MUST execute 'weaver registry check' and 'weaver registry resolve' against enterprise registries on all collector config and schema changes.

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.