--- title: "What is Agent Observability? Why and When It Matters" date: "2026-09-04" slug: "what-is-agent-observability" author: "Dany Paredes" canonical: "https://danywalls.com/what-is-agent-observability" description: "A practical guide to Agent Observability, OpenTelemetry, spans, 3-layer tracing architecture, and why debugging AI requires a new approach." --- Let's be honest: adding AI to frontend and fullstack apps is very easy today. You make a few API calls, write some prompts, and boom, you have a smart feature in your app. The real challenge starts when that feature goes to production. 😅 When normal code fails, it usually crashes. You open your browser console or your server logs, check the stack trace, find the exact line with the bug, fix it, and deploy. AI features do not work like that. AI is **non-deterministic**. You can send the exact same input twice and get two completely different answers. When an AI feature fails, it rarely crashes. Most of the time, the server returns a `200 OK`. The real problem is finding out *why* the answer is wrong. Think about all the moving parts in a modern AI app: - The system prompt and user prompt - The context injected from RAG (vector database) - The external data from APIs or Model Context Protocol (MCP) servers - The model itself (and its temperature) - The tools and function calls When the final response is incorrect, which part failed? Was the prompt confusing? Did RAG bring the wrong document? Did a tool return empty data? Or did the model hallucinate? Because there are so many connected pieces, finding the problem feels like guessing. To stop guessing and start debugging with confidence, we need **Agent Observability**. In this article, we will cover: - Why traditional monitoring tools are not enough for AI apps. - The three basic concepts you need to know: Spans, Traces, and OpenTelemetry. - The 3-layer architecture behind modern AI observability platforms. - When you actually need observability in your projects. - What I've learned is actually essential to understand right now. Now, let's explore why our existing APM tools fall short when applied to LLMs. --- ## Why Traditional Monitoring Fails 🛑 As developers, we already know tools like Datadog, Sentry, or New Relic. These Application Performance Monitoring (APM) tools are great for tracking server speed, memory usage, and 500 errors. However, AI introduces a new kind of problem: **Semantic Failures**. Let's look at a simple example. You build an AI agent to book flights for users. A user asks: *"Book a flight to Paris for next Friday."* The agent runs, calls your backend, and answers: *"Done! I booked your flight to Texas."* From your server's point of view, everything went smoothly: - The API returned `200 OK`. - The response time was fast. - No exceptions were thrown in your logs. Your monitoring dashboard is completely green. But for the user, your app failed completely. Traditional logs like `console.log("Processing user request")` are not enough here. You cannot see the full thought process of the agent. You need to inspect every step between the user prompt and the final response. To understand how to inspect these intermediate steps, let's look at the foundational building blocks of AI telemetry. --- ## The Core Concepts You Need to Understand 🧠 To debug AI applications properly, we borrow concepts from distributed tracing. If you have worked with microservices, this will feel very familiar. ### 1. Spans: The Single Steps A **span** represents a single piece of work. In an AI application, one span could be: - A call to an LLM (like OpenAI, Gemini, or Claude). - A tool execution (for example, calling an internal API like `getFlights()`). - An MCP server request (such as querying database context or file systems). - A database query (like fetching vector embeddings for RAG). A span does not just record how long the action took. For an AI step, a span captures: - The exact prompt sent to the model. - The raw text or JSON response received. - Model parameters (like temperature, model version, and top_p). - Token usage (input tokens, output tokens, and estimated cost). ### 2. Traces: The Complete Journey A **trace** connects all the spans together for a single user request. It creates a visual timeline of everything that happened. For example, when a user asks: *"Summarize my last invoice,"* the trace shows: 1. **Root Span:** The incoming user request. 2. **Child Span 1 (Tool Call):** The agent decides to call `fetchInvoice(id)`. 3. **Child Span 2 (Database):** Fetching the invoice details from PostgreSQL. 4. **Child Span 3 (LLM Call):** Sending the prompt plus the invoice data to the model to generate the summary. If the summary is wrong, you do not have to guess. You open the trace and check: - Did `fetchInvoice()` return the correct invoice? - Was the invoice text truncated before sending it to the model? - Did the model ignore the system prompt instructions? The trace shows you the exact step where things went wrong. ### 3. OpenTelemetry: The Open Standard Here is my biggest recommendation: **do not build a custom logging library for your AI apps.** The tech industry is adopting **OpenTelemetry (OTel)** as the standard for observability. OpenTelemetry defines common naming conventions (called Semantic Conventions) for AI. For example, standard GenAI attributes include: - `gen_ai.request.model` - `gen_ai.usage.input_tokens` - `gen_ai.usage.output_tokens` - `gen_ai.system` (e.g., openai, anthropic, gemini) When you use OpenTelemetry, your code is not tied to a single vendor. You can send your traces to open-source tools or platforms like Datadog, Honeycomb, LangSmith, Phoenix, or enterprise solutions like Progress Observability Platform without changing your application code. Now that we know what spans and traces are, let's look at how modern production observability platforms are structured. --- ## How AI Observability Platforms Work in Production 🏗️ When you examine enterprise-grade architectures (such as the [Progress/Telerik AI Observability Platform](https://www.telerik.com/ai-observability-platform/documentation/introduction)), modern AI monitoring is built around a clean **3-layer architecture**: ``` [ Your Application / Agent ] │ (TypeScript, Python, .NET SDKs with OpenTelemetry) ▼ [ Purpose-Built Collector ] │ (Validates API keys, enriches spans, calculates costs, masks PII) ▼ [ Observability & Analytics Platform ] │ (Dashboards, Cost Tracking, LLM-as-a-Judge Evals & Alerts) ``` ### Layer 1: Application SDKs (Instrumentation) Lightweight libraries added to your application. They automatically intercept calls to LLM providers (OpenAI, Anthropic, Bedrock), agent frameworks, and MCP tools, creating OpenTelemetry spans with zero boilerplate. ### Layer 2: The Collector (Data Enrichment & Guardrails) A dedicated telemetry collector receives trace data from your SDKs. It performs critical background work: - **Cost calculation:** Maps token counts to exact provider pricing in real time. - **PII masking:** Sanitizes sensitive customer data before it is stored. - **Tagging & attribution:** Attaches user IDs, session IDs, and experiment tags. ### Layer 3: Evaluation & Dashboard Platform A web platform where developers and product teams: - Inspect end-to-end execution timelines of complex agent workflows. - Run **LLM-as-a-Judge** automated evaluations on live production outputs. - Set up cost budgets and anomaly alerts. Understanding this architecture helps us decide when our projects actually justify setting up tracing. --- ## When Do You Actually Need Agent Observability? ⏱️ If you only have a simple feature that sends one static prompt to an API and prints the response, basic logging might be enough for now. You definitely need agent observability when: 1. **Your AI uses tools and MCP servers:** As soon as your agent can run code, query APIs, or interact with external systems (like [one-click MCP installations](/create-one-click-mcp-installation-links-cursor-vscode)), you must trace every action to understand why it took that path. 2. **You use RAG (Retrieval-Augmented Generation):** When answers depend on external documents, you need to see exactly what context was injected into the prompt. 3. **You build multi-step chains or multi-agent workflows:** When an agent coordinates with other agents (or utilizes [specialized Agent Skills](/improving-projects-with-agent-skills-react-best-practices)), debugging without traces is almost impossible. 4. **Security & Guardrails matter:** If your app handles user inputs that could be vulnerable to [prompt injection attacks](/prompt-injection-agentic-apps-4-layers-defense), tracing is essential for auditing threats. Next, let's explore the practical metrics and skills you should focus on today. --- ## What I've Learned is Actually Essential (For Now) 💼 Let's be real: the AI ecosystem changes at crazy speed. New models drop every week, new frameworks appear every month, and trying to know everything is impossible. As frontend or fullstack developers, we do not need to become machine learning researchers. But based on what I have learned while building and breaking things in production (and transitioning [from AI chat demos to real products](/what-i-learned-from-ai-chat-demos-to-real-ai-products)), here are the practical concepts that actually matter: ### 1. Token Usage and Cost Tracking Every single call to an AI model costs money. This includes the system prompt, the user input, the tool payloads, and the generated answer. I learned quickly that a silent loop in an agent can burn your budget very fast. In production, tracking token consumption per user and per feature is step zero. *Further reading: [OpenAI Tokenizer & Understanding Tokens](https://platform.openai.com/tokenizer) and [OpenTelemetry GenAI Semantic Conventions](https://opentelemetry.io/docs/specs/semconv/gen-ai/).* ### 2. Latency Breakdown (TTFT vs Processing Time) In frontend development, when a user complains that "the AI is slow", you need to know why: - **TTFT (Time To First Token):** How many milliseconds pass before the model starts streaming the response to the user. - **Tool and DB Latency:** Did your backend spend 3 seconds querying a vector database before the model even started thinking? Knowing this difference helps us design much better UI feedback, such as loaders, skeletons, and streaming text. *Further reading: [Measuring and Optimizing LLM Latency](https://www.anyscale.com/blog/measuring-and-optimizing-llm-latency).* ### 3. Context Quality Over Context Size In RAG systems, more data is not always better. Dumping huge documents into the prompt often confuses the model, increases token costs, and leads to hallucinations. Observability lets you inspect the exact chunks of text retrieved by RAG to confirm they are actually relevant. *Further reading: [RAG Architecture and Retrieval Concepts](https://python.langchain.com/docs/concepts/rag/).* ### 4. Evals: Testing When Outputs Always Change We cannot write traditional unit tests like `expect(result).toBe("Welcome")` because AI responses vary. What I learned to use are **evals**. These are automated checks or "LLM-as-a-judge" evaluation tasks that score responses on criteria like accuracy, helpfulness, and tone over time. *Further reading: [Progress AI Observability Documentation](https://www.telerik.com/ai-observability-platform/documentation/introduction), [Your Guide to AI Evals by Hamel Husain](https://hamel.dev/blog/posts/evals/) and [OpenAI Evals Framework](https://github.com/openai/evals).* ### 5. Guardrails and Sensitive Data (PII) Before sending data to external LLM providers, you must know what is leaving your app. With observability and guardrails in place, you can track and mask Personally Identifiable Information (PII) like emails or credit cards, and catch prompt injection attacks before they reach your backend tools. Check out my deep-dive on [4 layers of defense against prompt injection](/prompt-injection-agentic-apps-4-layers-defense) for a complete breakdown. --- ## Recap 🛠️ Building AI apps is exciting, but managing non-deterministic systems is a big shift for all of us. When an AI feature returns the wrong output, standard error logs and stack traces will not help. By using spans, traces, OpenTelemetry, and a solid 3-layer observability architecture, you can inspect the black box and see every prompt, context injection, and tool call clearly. This observability is what turns an experimental AI prototype into a reliable product you can trust in production. If you are exploring AI development and developer tools, check out my [AI Series](/series/ai) and [Observability Series](/series/observability) for more hands-on guides! _Photo by [Josh Williams](https://unsplash.com/@joshwi?utm_source=unsplashx&utm_medium=referral) on [Unsplash](https://unsplash.com/?utm_source=unsplashx&utm_medium=referral)_