Posts Tagged - opentelemetry

OpenTelemetry

Observability for distributed Apps

La observabilidad es la capacidad de entender el estado interno del sistema que estamos examinando, a través de examinar sus outputs externos

Cuando tienes microservicios que se interconectan, la observabilidad es esencial para poder identificar issues como latencia, request fallidas o performance degradada.

Se basa en tres pilares que se complementan entre ellos.

  • Metrics: medidas numericas agregadas a lo largo del tiempo (request counts, error rates). Te dicen que hay algo que ha cambiado.
  • Distributed tracing: Capturar el full path de una request a medida que se va moviendo por diferentes servicios. Te dicen donde ocurre el problema.
  • Logs: detallados con un timestamp. Te dan los detalles de por qué ha cambiado.

OpenTelemetry como standard

OpenTelemetry es un framework de observabilidad vendor-neutral, open-source. Provee de un set unificado de APIs, SDKs, herramientas para generar, recolectar y exportar telemetría.

  • APIs: define la interfazs para crear y administrar datos de telemetria
  • SDKs: implementan las APIs y ofrecen config options para procesar y exportar telemertia
  • Instrumentation libraries: Capturan automaticamente telemetria de frameworks y libraries. Ejemplo: Una HTTP instrumentation library que captura incoming y outgoing HTTP request details de manera automatica
  • Exportes: Serializan y transmiten la telemetria recogida a backend analysis tools.

Al ser vendor-netrual puedes enviar la misma telemetry data a Azure Monitor, Proemetheus, Grafana…

Understand traces, spans, and context propagation

Una traza representa un registro del viaje de una request a través de un sistema distribuido. Cada traza consiste en una o más operaciones individuales. Todas las operaciones juntas forman la secuencia completa para gestionar una request.

Un span es una named, timed operation dentro de una traza. Cada span captura información sobre una unidad específica de trabajo como una HTTP request, database query o llamada a una API externa. Cad span contiene:

  • trace ID
  • span ID
  • parent span ID: span ID de la parent operation que ha iniciado este span (los span root no tienen parents)
  • name
  • start and end timestamp
  • attributes: pares clave-valor
  • status: succeded/failed

La jerarquía de spans define la estructura de una traza. El root span representa el entry point al sistema (ej: una incoming HTTP request a una API gateway). Child spans representan downstream operations triggered por esa root request.

Cuando la API gateway, siguien el ejemplo, llama a un embedding service, esa llamada crea un child span. Si ese embedding service llama al vector search service, se crea orto child span bajo el embedding span. Estas relaciones forman un tree que representa visualmente todo el trabajo realizado originado desde la request original.

Context propagation es el mecanismo que carries trace y span IDs across service boudnaries. Sin context propagation, cada serviico crearia trazas sin ninguna manera de correlacionarlas.
OpenTelemetry usa el W3C TraceContext standard para progragar contexto a través de HTTP headers. Cuando un servicio llama a otro incluye un header traceparent que contiene el traceID del span que lo llama

Read More

Add OpenTelemetry SDK

Choose instrumentation approach

Azure Monitor soporta 2 primary instromentation approaches

Autoinstrumentation

Permite telemetry collection a través de config sin tener que modificar app code.

Funciona muy bien para los entornos soportados como Azure Functions o Azure Virtual Machines, pero ofrece control limitado sobre la telemetria que se recolecta, o sobre como se enriquece de datos.

Manual instrumentation

Meter el SDK en tu app code. Este approach te da full control sobre la recoleccion de telemetria, pero puede ser demasiado para situaciones simples.

Install Azure Monitor OpenTelemetry Distro

El Azure Monitor OpenTelemetry Distro es el approach recomendado para SDKs. Es una distribucion de OpenTelemetry que hace bundle del OpenTelemetry SDK con Azure Monitor exporters y librerias, en un único package.

Se distribuye como un único pip package que incluye todo

pip install azure-monitor-opentelemetry

Lo invocamos con configure_azure_monitor() en el startup. Esta llamada inicializa el tracer provider, el meter provider, el logger provider y los configura todos para exportar en Application Insights.

# Code fragment - focus on minimal OpenTelemetry setup with Azure Monitor
from azure.monitor.opentelemetry import configure_azure_monitor

configure_azure_monitor()

Understand automatic data collection

El Azure Monitor OpenTelemetry Distro automaticamente recoge telemetria de common frameworks y libraries sin tener que escribir codigo.

Esta recoleccion automatica incluye

  • requests library outgoing HTTP calls
  • urllib outgoing HTTP calls
  • Flask / Django / FastAPI: incoming HTTP requests
  • psycoph2: PostgreSQL database queries
  • Azure SDK: llamadas hechas a Azure a través del SDK
  • logging

Configure the connection string

Environment var

Usar la environment var APPLICATIONINSIGHTS_CONNECTION_STRING. Esto mantiene la config fuera del codigo

export APPLICATIONINSIGHTS_CONNECTION_STRING="InstrumentationKey=00000000-0000-0000-0000-000000000000;IngestionEndpoint=https://eastus-0.in.applicationinsights.azure.com/"

Code-based conf

Pasar la connection string directamente a configure_azure_monitor()

# Code fragment - focus on code-based connection string configuration
from azure.monitor.opentelemetry import configure_azure_monitor

configure_azure_monitor(
    connection_string="InstrumentationKey=00000000-0000-0000-0000-000000000000;IngestionEndpoint=https://eastus-0.in.applicationinsights.azure.com/"
)

Set the cloud role name

Cuando multiples servicios mandan telemetria al mismo Application Insights, cada servicio necesita un cloud role name distinto para aparecer como un nodo separado en el Application Map. Si no lo ponemos, todos los servicios aparecen como un single node.

El cloud role name deriva de service.name y service.namespace OpenTelemetry resource attributes. Juntos combinados forma el cloud role name.

como configurarlo

# Code fragment - focus on setting cloud role name via resource attributes
from azure.monitor.opentelemetry import configure_azure_monitor
from opentelemetry.sdk.resources import Resource

configure_azure_monitor(
    resource=Resource.create({
        "service.name": "embedding-service",
        "service.namespace": "rag-pipeline",
        "service.instance.id": "embedding-instance-1",
    })
)

Read More

Export telemetry to Azure Monitor (OpenTelemetry)

Understand telemetry export to Application Insights

La pipe de export de telemetria mueve tus datos desde tu app a Application Insights siguiendo una serie de pasos.

El OpenTelemetry SDK recoge telemetria de instrumentation libraries y custom spans. El Azure Monitor exporter serializa los datos que envia al Application Insights ingestion endpoint identificado por tu connection string. Este proceso ocurre entero dentro de los limites de tu app.

La Azure Monitor OpenTelemetry Distro usa direct export by default. Esto significa que la app envia la telemetria directamente al ingestion endpoint del Application Insights, sin un intermediario.
Este approach simplifica el deployment ya que no hay infraestructura adicional.
La alternativa es usar OpenTelemetry Collector, un proceso separado que recibe telemetria de apps, la procesa y la reenvia a uno o más backends. El Collector añade complejidad operacional pero ofrece más capacidades como sampling centralizado, data transformation y multi-backend routing.

Cuando la telemetría llega a Application Insights, se mapea en diferentes tablas:

  • Server spans (SpanKind.SERVER y SpanKind.CONSUMER) aparecen en la tabla requests
  • Client, internal, producer spans (SpanKind.CLIENT, SpanKind.INTERNAL, SpanKind.PRODUCER) aparecen en la tabla dependencies
  • Log records emitidos a través de python’s logging module u OpenTelemetry logging API aparecen en la tabla traces
  • Exceptions aparecen en la tabla exceptions
  • Custom metrics aparecen en la tabla customMetrics

Configure sampling to control telemetry volume

Sampling reduce el volumen de telemetria que se envia a Application Insights, recogiendo solo un porcentaje de las trazas. Esto es esencial para apps con un gran volumen de requests y controlar los costes de ingestion.

Estrategias de sampling para traces:

  • Fixed-percentage sampling: Recoge una fixed fraction de todas las trazas. Especificas un ratio entre 0.0 y 1.0 donde 0.1 significa el 10% de las trazas
  • Rage-limited sampling: Pone un cap al number de trazas recolectadas por segundo. Especificas 1.5 donde es aprox. una traza y media cada segundo

Podemos configurar fixed-percentage sampling en codigo usando sampling_ratio param, o rate-limited sampling usando traces_per_second

# Code fragment - focus on configuring sampling via configure_azure_monitor()
from azure.monitor.opentelemetry import configure_azure_monitor

# Fixed-percentage sampling: sample approximately 10% of traces
configure_azure_monitor(
    sampling_ratio=0.1,
)

# Rate-limited sampling: sample approximately 1.5 traces per second
# configure_azure_monitor(
#     traces_per_second=1.5,
# )

Enable offline storage and automatic retries

El Azuer Monitor exporter cachea la telemetria de manera local cuando la app pierde conexion y lo reintenta durante 48 horas.

Se puede hacer override del default storage directory si necesitas la cache en un directorio especifico

# Code fragment - focus on configuring offline storage directory
from azure.monitor.opentelemetry import configure_azure_monitor

configure_azure_monitor(
    storage_directory="/var/telemetry/rag-pipeline",
)

Verify telemetry data flow

Tras el initial setup es importante verificar que la telemetria esta llegando al Application Insights. Los datos pueden no aparecer inmediatamente ya que se hacen en batches.

Para real-time verification durante development, tenemos Live Metricos que ofrece un dashboard para hacer displays con un delay minimo.

Podemos ejecutar KQL queries en Application Insights Logs para verificar que los trace data están disponibles

devuelve las 20 requests mas recientes de la ultima hora, mostrando operation name, duration, success status y cloud role name del servicio

requests
| where timestamp > ago(1h)
| project timestamp, name, duration, success, cloud_RoleName
| order by timestamp desc
| take 20

Read More

Debug distributed flows with trace data (OpenTelemetry)

Recoger y exportar telemetría solo es util si puedes usar esos datos para encontrar y arreglar problemas

El Application Map provee de una topología visual de todos tus servicios dentro de tu aplicación distribuida, mostrando la manera en que se conectan y donde hay fallos o problemas de latencia.

Cada nodo de un mapa representa un cloud role, identificado por el resource attribute service.name configurado durante el setup.

Los limites entre nodos representan llamadas de un servicio a otro.

El Application Map muestra key metrics en cada nodo y edge, incluyendo avg response time, request count o failure rate.

Puedes usar este mapa para reducir rápidamente el área de tu investigación.

Use end-to-end transaction details

La transaction view end-to-end muestra un waterfall chart de todos los spans en una single trace, mostrando timing, duration y dependencias de cada operación.

Esta view es la primary tool para entender que pasa durante una specific request e identificar donde se ocupa el tiempo.

El waterfall chart muestra el root span en el top, representando el entry point de la request. Child spans se muestran bajo sus parent spans.

Write KQL queries to analyze trace data

El application insights almacena telemtria en las tablas de Log Analytics, a las que podemos hacer queries usando Kusto Query Language (KQL).

Las trazas se almacenan en 4 tablas primarias

  • tabla requests contiene server spans y consumer spans
  • tabla dependencies contiene client, internal y producer spans
  • tabla traces contiene log records
  • tabla exceptions contiene excepciones grabadas

Todas las tablas comparten una columna operation_id, la cual corresponden con el OpenTelemetry trace ID para poder correlacionar items que pertenecen a la misma traza distribuida

find slow requests and summarize by service

requests
| where duration > 3000
| summarize count(), avg(duration) by cloud_RoleName
| order by avg_duration desc

You can join request with their dependencies

this query connects each slow request with its downstream dependency calls

requests
| where duration > 5000
| join kind=inner (dependencies) on operation_Id
| project timestamp, requestName = name, requestDuration = duration,
    dependencyName = name1, dependencyDuration = duration1,
    dependencyTarget = target
| order by requestDuration desc

You can query custom attributes stored in customDimensions

analyzes embedding generation performance by model, showing avg and 95th-percentile durations alongside avg token counts

dependencies
| where name == "GenerateEmbedding"
| extend tokenCount = toint(customDimensions["embedding.token_count"]),
    model = tostring(customDimensions["embedding.model"])
| summarize avg(duration), percentile(duration, 95),
    avg(tokenCount) by model
| order by avg_duration desc

Read More

Configure spans and traces (OpenTelemetry)

Create custom spans with a tracer

Custom spans te permiten representar business-specific operations en tu trace data. En una RAG pipe pueden ser operaciones como generate embedding, search vector index o assemble prompt.
Estos spans aparecen en Application Insights como end-to-end transactions junto a todos los spans recogidos automaticamente.

En python usamos opentelemetry.trace como entry point para crear spans. Se llama trace.get_tracer("name") para obtener un tracer para tu servicio o componente.

create a tracer and start a custom span

# Code fragment - focus on creating a custom tracer and span
from azure.monitor.opentelemetry import configure_azure_monitor
from opentelemetry import trace

configure_azure_monitor()

# Equivalent to creating an instrumentation source — use once per service/component
tracer = trace.get_tracer("embedding-service")

# start_as_current_span is a context manager — the span ends automatically when the block exits
with tracer.start_as_current_span("GenerateEmbedding") as span:
    span.set_attribute("embedding.model", "text-embedding-ada-002")
    span.set_attribute("embedding.token_count", token_count)
    # Embedding generation logic
    embedding = generate_embedding(input_text)

Add attributes to spans

Span attributes enriquecen tus trace data con información contextual que ayuda a filtrar, buscar y analizar trazas.

Resources attributes - describen el servicio en si mismo y aplican a toda la telemetria de ese servicio. Configuras los atributos una unica vez durante el startup.
Span attributes - describen una operacion especifica y aplican solo al span individual. Configuras span attributes dentro del scope de un span activo para capturar detalles particulares de esa operacion.

# Code fragment - focus on adding meaningful attributes to a span
with tracer.start_as_current_span("SearchVectorIndex") as span:
    span.set_attribute("search.index_name", "product-docs")
    span.set_attribute("search.query_vector_dimension", 1536)
    span.set_attribute("search.top_k", 10)
    results = search_index(embedding)
    span.set_attribute("search.result_count", len(results))
    span.set_attribute("search.similarity_threshold", 0.78)

Cuando exportamos estos atributos a Application Insights, aparecen dentro de la columna customDimensions.

Control span kinds and status

El span kind indica el tipo de operacion que representa un span. Application Insights usa estos valores para clasificar spans como requests o dependencias.

Tipos de spans

  • SpanKind.SERVER incoming request gerstionada por el servicio
  • SpanKind.CLIENT outgoing call a un servicio o recurso externo
  • SpanKind.INTERNAL operacion interna dentro del servicio que no cruza process boundaries
  • SpanKind.PRODUCER iniciar una async op (enviar un mensaje a una queue)
  • SpanKind.CONSUMER consume una async op (recibir un mensaje de una queue)
# Code fragment - focus on setting span kind for an outgoing LLM API call
from opentelemetry.trace import SpanKind

with tracer.start_as_current_span("CallLlmApi", kind=SpanKind.CLIENT) as span:
    span.set_attribute("llm.provider", "azure-openai")
    span.set_attribute("llm.model", "gpt-4o")
    # LLM API call logic
    response = call_llm(prompt)
    span.set_attribute("llm.response_tokens", response.usage.completion_tokens)
# Code fragment - focus on recording errors and exceptions on a span
from opentelemetry.trace import Status, StatusCode

with tracer.start_as_current_span("GenerateEmbedding") as span:
    try:
        embedding = generate_embedding(input_text)
        span.set_status(Status(StatusCode.OK))
    except Exception as ex:
        span.record_exception(ex)
        span.set_status(Status(StatusCode.ERROR, "Embedding generation failed"))
        raise

Model nested operations in a trace

Nested spans crean una jerarquia parent-child que representa el flow logico de una request a traves de tu app.

En python se nestea poniendo start_as_current_span uno dentro de otro. Cuando un span comienza mientras otro span está activo, OpenTelemetry marca el activo como padre del nuevo.

nested spans model a simplified RAG pipe request flow

# Code fragment - focus on nested spans modeling a RAG pipeline request flow
from azure.monitor.opentelemetry import configure_azure_monitor
from opentelemetry import trace
from opentelemetry.trace import SpanKind

configure_azure_monitor()
tracer = trace.get_tracer("llm-orchestrator")

def process_query(query: str) -> str:
    with tracer.start_as_current_span("ProcessQuery", kind=SpanKind.SERVER) as root_span:
        root_span.set_attribute("query.length", len(query))

        # Child span: Generate embedding
        with tracer.start_as_current_span("GenerateEmbedding") as embed_span:
            embed_span.set_attribute("embedding.model", "text-embedding-ada-002")
            embedding = embedding_service.generate(query)
            embed_span.set_attribute("embedding.dimensions", len(embedding))

        # Child span: Search vector index
        with tracer.start_as_current_span("SearchVectorIndex") as search_span:
            search_span.set_attribute("search.top_k", 5)
            results = vector_search.search(embedding, top_k=5)
            search_span.set_attribute("search.result_count", len(results))

        # Child span: Call LLM
        with tracer.start_as_current_span("CallLlm", kind=SpanKind.CLIENT) as llm_span:
            prompt = build_prompt(query, results)
            llm_span.set_attribute("llm.prompt_tokens", count_tokens(prompt))
            response = llm_client.get_completion(prompt)
            llm_span.set_attribute("llm.response_tokens", response.usage.completion_tokens)
            return response.content

Cuando ves esto a través de Application Insights end-to-end transaction view, lo ves como un waterfall chart.
ProcessQUery aparece como el root span, con GenerateEmbedding, SearchVectorIndex y CallLLM como child spans nesteados.

Read More