otel-demo-architecture

Diagnose observability and topology issues in the OpenTelemetry Demo microservices.

Updated Nov 19, 2025
One-click install
npx skills add https://github.com/blueswen/observability-with-llm --skill otel-demo-architecture
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: otel-demo-architecture
Source: https://github.com/blueswen/observability-with-llm/tree/main/opentelemetry-demo-app-with-llm/workspace/.claude/skills/otel-demo-architecture
Command: npx skills add https://github.com/blueswen/observability-with-llm --skill otel-demo-architecture

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes references (resource) components.

What problem does it solve?

Understanding the intricate architecture and dependencies of a microservices system like the OpenTelemetry Demo is crucial for effective debugging. This Skill provides a comprehensive, AI-ready reference to quickly grasp service interactions, identify bottlenecks, and troubleshoot issues without manually sifting through documentation.

Core Features & Use Cases

  • Service Dependency Mapping: Instantly visualize which services depend on others, their protocols, and resource limits.
  • Critical Path Analysis: Understand key user and telemetry flows to prioritize investigation areas.
  • Observability Stack Details: Get quick access to how metrics, traces, and logs are collected and stored.
  • Use Case: When investigating a performance degradation in the checkout service, use this Skill to quickly identify its upstream and downstream dependencies, check their memory limits, and understand the data flow to pinpoint the potential source of the bottleneck.

Quick Start

Describe the critical path for a user's checkout flow in the OpenTelemetry Demo application.

Frequently Asked Questions about otel-demo-architecture

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I troubleshoot performance issues in a microservices architecture?

Troubleshoot microservices performance by mapping service dependencies, identifying critical paths in user flows, and analyzing metrics, traces, and logs to pinpoint bottlenecks. The OpenTelemetry Demo architecture provides a complete reference for understanding service interactions, communication protocols, and resource constraints across your system.

How do I map service dependencies and understand data flow in microservices?

Map service dependencies by identifying upstream and downstream connections, their protocols, and resource limits. Trace critical user flows like checkout to visualize the complete data path across services, revealing which components affect each other and where bottlenecks originate.

What is the OpenTelemetry Demo architecture and how does observability work across services?

The OpenTelemetry Demo is a microservices application that demonstrates how metrics, traces, and logs are collected, correlated, and stored across distributed services. Understanding its architecture helps you debug failures, detect telemetry gaps, and analyze system topology without manual documentation review.

How do I identify which service is causing a system bottleneck?

Identify bottlenecks by analyzing service dependencies and resource limits, then tracing the critical path through affected services using metrics, traces, and logs. Cross-reference service interactions and memory constraints to isolate which component is constraining system performance.

Can I use observability references to debug communication issues between services?

Yes. Use service dependency references to understand protocols and connections between services, then examine traces and logs to detect communication failures, timeouts, or data flow breaks that cause system failures or performance degradation.

What telemetry gaps should I check for when troubleshooting a distributed system?

Detect telemetry gaps by comparing expected service interactions against collected metrics, traces, and logs. Missing data from critical services or paths indicates incomplete instrumentation that could hide failures or obscure root causes during troubleshooting.