o11y-dev-opentelemetry-skill

OpenTelemetry Skill: A Cognitive Architecture for AI-Assisted Observability Engineering

Overview

The opentelemetry-skill is an AI assistant skill designed to help with OpenTelemetry configuration and observability engineering tasks. This skill employs progressive disclosure to optimize context usage and deliver production-ready OpenTelemetry configurations.

This repository contains the source code for the OpenTelemetry Skill tile released by Tessl.

• Published versions: https://tessl.io/registry/o11y-dev/opentelemetry-skill
• Source code: https://github.com/o11y-dev/opentelemetry-skill

Key Features

Comprehensive Coverage: Specialized reference docs covering collector architecture, security, sampling, AI agents, and compatibility

Production Focus: Emphasizes stability, security, and cost optimization patterns

AI Agent Support: Configuration guidance for monitoring AI coding agents alongside traditional applications

Progressive Loading: Context-aware reference loading prevents information overload

Continuous Updates: Automated upstream monitoring tracks OpenTelemetry releases and AI agent repositories

📋 Table of Contents

• Key Features
• What Makes This Different?
• Core Features
• Skill Structure
• Installation
• Architecture
• Architecture Patterns
• Usage Examples
• Reference Documentation
• Contrib Components & Example Configs
• Testing & Validation
• Contributing
• Known Limitations
• Roadmap
• Compatibility
• License
• Related Projects

What Makes This Different?

Unlike loading the entire OpenTelemetry documentation into an AI's context (which leads to hallucinations and information overload), this skill acts as a cognitive router:

1. System 2 Thinking: Forces the AI to analyze critical observability signals (throughput, cardinality, resiliency) before generating code
2. Progressive Disclosure: Loads detailed reference materials only when specific topics are triggered
3. Production-First: Prioritizes stability, security, and cost optimization over feature completeness
4. Convention Enforcement: Ensures semantic conventions, proper processor ordering, and architectural best practices
5. AI Agent Support: Includes guidance for observing AI coding agents in production environments

Core Features

• 🧠 Cognitive Architecture: Meta-knowledge layer that teaches AI how to think about observability
• 📊 Cardinality Management: Built-in guards against metric explosion and cost overruns
• 🏗️ Deployment Patterns: Platform-specific setup guides for Kubernetes, ECS, Docker, and standalone VMs
• 🎯 Multi-Platform Support: DaemonSet vs Gateway vs Sidecar decision matrices for Kubernetes; EC2 daemon and Fargate patterns for ECS; Docker Compose patterns
• 🔒 Security by Default: PII redaction, TLS/mTLS configuration, and authentication patterns with platform-specific guidance
• 🔄 OTTL Transformations: Comprehensive OpenTelemetry Transformation Language guidance with patterns and best practices
• 📈 Scaling Strategies: Load balancing with sticky sessions for tail sampling, resource management for high-throughput collectors
• 🎯 Sampling Intelligence: Head vs tail sampling with statistical trade-off analysis
• 🔍 Meta-Monitoring: Self-observability patterns for collector health
• 🤖 AI Agent Observability: Configuration guides for monitoring AI coding agents including Claude Code, Gemini CLI, GitHub Copilot, Codex, Qwen Code, Pi Agent, and more via OpenTelemetry
• ✅ Test & Validation Framework: TDD-based testing methodology and 20+ comprehensive evaluation scenarios to ensure skill effectiveness

Skill Structure

SKILL.md acts as the cognitive router — a compact instruction set that tells the AI how to reason about observability before generating any output. docs/index.md is the tile's on-demand documentation entrypoint for Tessl, and references/ contains the deep-dive documents that the skill links to when specific topics are triggered.