• Updated:
  • Featured post

How LLMs get their probabilities for the next token

(este post es una explicación de la teoría. dejo aquí otro post con el detalle práctico de como usar la temperature, top_k y top_p a efectos prácticos)

Explicación más en detalle de cómo obtienen los LLMs las probabilidades para generar el siguiente token

Sampling

En cada posición el modelo tiene una bolsa con miles de tokens posibles. Sampling es el proceso de no coger siempre el token más probable, si no de orientarlo a coger respuestas con determinadas características.

Si el modelo escogiera siempre el token con más probabilidades, obtendríamos respuestas aburridas y repetitivas.

Logits

Para generar el siguiente token, una red neuronal calcula primero los vectores de logits, donde cada logit corresponde a un valor posible. El tamaño de estos vectores de logits es tan grande como el vocabulario completo del modelo.

(representación de vectores de logits)

flowchart LR
	N1["What's your favorite color?"]:::note --> Z
	Z --> A1 --> A
	Z --> B1 --> B
	Z --> C1 --> C
	Z --> D1 --> D
	
	Z["Neural network"]
    A["a"]
    A1["(-0.5)"]
    B["green"]
    B1["(0.7)"]
    C["red"]
    C1["(0.5)"]
    D["the"]
    D1["(-1.2)"]
    
    classDef note fill:none,stroke:none,color:#777;    

Los logits NO representan probabilidades ya que no suman 1 y pueden incluso ser negativos (la probabilidades no pueden). Para convertir logits a probabilidades se usa una Softmax layer

Temperature

La temperatura es una constante que se aplica a los logits antes de la transformación de la Softmax layer. Se usa para ajustar la creatividad del modelo y redistribuir la probabilidad de los valores. Una temperatura más alta hace que el modelo sea más creativo ya que aumenta las posibilidades de elegir tokens menos probables.

xychart-beta
  title "Temperatura vs Probabilidad"
  x-axis "Temperatura (T)" [0.1, 0.2, 0.5, 1, 2, 5]
  y-axis "Probabilidad" 0 --> 1
  line "P(token1)" [0.9999546, 0.9933071, 0.8807971, 0.7310586, 0.6224593, 0.5498340]
  line "P(token2)" [0.0000454, 0.0066929, 0.1192029, 0.2689414, 0.3775407, 0.4501660]

Ejemplos de temperaturas:

  • Low (0.2-0.3): El modelo es cauto y elige las palabras más probables. Output factual y predecible.
  • Medium (0.5-0.7): Un mix de confiabilidad y engagement
  • High (0.9-1.0): Toma riesgos y es impredecible

Read More

Explore logs (KQL)

Investigate application errors with KQL

El primer paso de una investigación debería ser entender el scope del problema: cuantos errores hay, cuando comenzaron y que tipos hay involucrados.

usamos sum() para producir accurate results cuando el sampling de Application Insights está activo

exceptions
| where timestamp > ago(24h)
| summarize exceptionCount = sum(itemCount) by bin(timestamp, 1h), type
| render timechart

Una vez encontramos el error podemos ir a más detalle para encontrar los most common exception types

agrupawr excepciones por exception type y operation name, produciendo una ranked list de las operaciones que generan más errores

exceptions
| where timestamp > ago(24h)
| summarize exceptionCount = sum(itemCount) by type, operation_Name
| top 10 by exceptionCount desc

Correlate failures across services

En una arquitectura multi servicio, una request puede viajar por muchos servicios diferentes, y un fallo en uno de ellos puede seguir la cadena y resultar en fallos en otros servicios.

Con el operation_id linkeamos todos los telemetry items de una single request distribuida. Haciendo un join a través de este operation_id podemos ver la secuencia completa de eventos que llevan a ese fallo

exceptions
| where timestamp > ago(24h)
| join kind=inner (
    requests
    | project requestName = name, requestDuration = duration, operation_Id, requestRoleName = cloud_RoleName
) on operation_Id
| project timestamp, exceptionType = type, exceptionMessage = outerMessage,
    requestName, requestDuration, cloud_RoleName = requestRoleName
| top 20 by timestamp desc
  • La columna cloud_RoleName identifica que servicio ha generado la excepción
  • La columna requestDuration revela donde ha ido lenta la request

Analyze dependency latency and failures

La tabla dependencies captura cada outgoing call como llamadas a BBDD, HTTP APIs, Azure services y otros.

Es la primera tabla que tenemos que mirar para buscar un bottleneck cuando algo es lento.

dependencies
| where timestamp > ago(24h)
| summarize avg(duration), percentiles(duration, 50, 95, 99) by target, type
| order by percentile_duration_95 desc

Percentile calculations dan un overview mas preciso que tener en cuenta solo los avg. Para ello usamos los percentiles 95th y 99th.

identificar dependencias fallidas

dependencies
| where timestamp > ago(24h)
| where success == false
| summarize failureCount = count() by target, resultCode, cloud_RoleName
| order by failureCount desc

Failure and performance views

Application Insights ofrece vistas que complementan a KQL.

La Failures view agrupa operaciones fallidas por tipo y hace display de los tipos fallidos más comunes

La performance view muestra todas las operaciones con su response time y distribuciones y request counts.

Build Dashboards for App telemetry (KQL)

Dashboards vs Workbooks

IMPORTANTE

Los dashboards difieren de los workbooks en su diseño e interaccion. Las dashboards están optimizadas para ser visuales, con tiles que se refrescan y muestran los datos automaticamente. El layout es relativamente estatico. Pones las tiles una vez y el dashboard se muestra sin intervencion humana.

Los workbooks están diseñados para una exploracion interactiva donde ajustas params para ver datos dinámicos.

Elegimos dashboards para ongoing operational monitoring y workbooks para investigación de incidentes y ad-hoc analysis.

IMPORTANTE

Azure dashboards for monitoring

Azure dashboards son una surface visual customizable en el azure portal que combina multiples recursos en una unica view.

En ellos podemos ver metrics chart, log query results, Markdown text blob o recursos de la galeria. Los equipos usan estas dashboards para tener un awareness operacional en el day-to-day monitoring para confirmar pipeline health.

Pin metrics to dashboards

Common metrics:

  • server response time (avg y percentiles)
  • failed requests
  • dependency failures (llamadas fallidas a BBDD, APIs, etc)
  • server request rate
  • availability

Pin log query results to a dashboard

Los charts de metricas están limitados a unas en especifico. Si queremos valores custom podemos hacer joins entre tablas y hacer pin de una SQL query para mostrar sus resultados en una dashboard.

ver que servicios contribuyen a los most failures

requests
| where timestamp > ago(24h)
| where success == false
| summarize failedCount = count() by cloud_RoleName
| render barchart

representar tres lineas con los percentiles

requests
| where timestamp > ago(24h)
| summarize p50 = percentile(duration, 50),
    p95 = percentile(duration, 95),
    p99 = percentile(duration, 99)
    by bin(timestamp, 1h)
| render timechart

Organize and share dashboards

Las dashboards se pueden compartir con team members. Publicarlas las hace disponibles para otros usuarios en tu organizacion mediante RBAC

Best practices

  • Separate concerns into different dashboards
  • Limit tile count
  • Use descriptive tile titles
  • Include markdown tile for context

Workbooks for interactive analysis

IMPORTANTE

Azure Monitor Workbooks son una herramienta interactiva de analisis que combinan rich text, KQL, metricas y parametros en reusable reports.

Los workbooks van más alla de dashboards y soportan user interaction: seleccionar un param value, elegir un time range. Esta interactividad hace que los workbooks sean la eleccion natural para troubleshooting, root cause analysis y cualquier escenario donde el investigador necesite ajustar el scope del analisis.

/IMPORTANTE

El Azure Portal incluye una galeria de prebuilt workbook templates organizadas por categoria para usar como starting points y customizar para tu caso.

Add query steps and visualizations

Los workbooks se construyen añadiendo steps verticalmente, donde cada step renferiza un componente del reporte final. Se cuenta como steps, text bloccks para explicaciones e instrucciones, query steps que ejecutan KQL y muestran resultado, metric steps que muestran metricas de recursos de Azure.

Ejemplo de query que funciona como un step de workbook

requests
| where timestamp > ago({TimeRange})
| summarize totalRequests = count(),
    failedRequests = countif(success == false)
    by cloud_RoleName
| extend successRate = round(100.0 * (totalRequests - failedRequests) / totalRequests, 2)
| project cloud_RoleName, totalRequests, failedRequests, successRate

La sintaxis {TimeRange} referencia un param del workbook.

Use params for interactive filtering

Como hemos visto en el paso anterior podemos hacer los workbooks interactivos, donde cada param aparece como control en el top del workbook.

Los params más comunes son:

  • time range
  • dropdown params (para filtrar por service name, environment, etc)
  • resource pìcker para elegir que Application Insight resource analizamos

Configure conditional visibility and linked content

Conditional visibility y grid link actions añaden depth a los workbooks. En vez de enseñar cada detalle upfront de a una, se pueden diseñar los workbooks para que comiencen con un resumen a alto nivel y revelen detalles solo cuando se seleccione un item especifico.

Esto se hace que se muestre o se esconda basándose en un param value que configuramos.

Grid link actions crean tablas interactivas donde al seleccionar una row hace trigger de downstream actions. Cuando configuramos una grid column como un link, hacer click en esa celda de esa column para abrir detalles end-to-end de transacciones para una request especifica, navegar a otro workbook para un analisis mas a fondo o ejecutar otras acciones.

Set alerts for app failures and anomalies (KQL)

Los dashboards y workbooks dan visibilidad en la salud de la app, pero requieren que haya alguien mirando. La alertas avisan proactivamente a tu equipo de que algo está mal y hay que arreglarlo.

Alert rule structure

Cada Azure Monitor alert rule consiste de 4 coponentes que funcionan juntos para detectar problemas y hacer trigger de respuestas.

  • Scope: recursos que se monitorizan
  • Condition: limite que determina cuando se hace trigger de la alerta
  • Action group: colección de notificaciones o automated actions que se ejecutan cuando se dispara la alerta
  • Severity: 0 (critical), 1 (Error), 2 (Warning), 3 (Informational), 4 (verbose)

Tenemos dos tipos primarios de alertas para telemetria:

  • Metric alerts: evaluan metricas de recursos en intervalos regulares. Se utilizan, por ej. para avisar cuando la CPU excede de un 80% de uso
  • Log search alerts: proveen mas flexibilidad. Se puede definir cualquier KQL query como detection logic, incluyendo joins entre tablas.

Use smart detection for anomaly identification

Azure Monitor tiene smart detection con ML que identifica patrones unusuales en tu app sin necesitar de configuración.

  • Failure anomaly: monitoriza el ratio de requests fallidas y lo compara con valores historicos
  • Performance anomaly: identifica degradacion de tiempo de respuesta, slowdowns con las dependencias o excepciones no normales

Lo mejor es usar el modo smart junto a tus reglas configuradas manualmente.

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

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",
    })
)

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

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

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.

Kusto Query Language (KQL)

KQL and Azure Monitor Logs

Kusto Query Language (KQL) es la primary tool que se usa para hacer retrieve y analizar log data almacenada en Azure Monitor, Log Analytics, y Azure Data Explorer. Sigue un modelo de pipe separdo por el caracter |.

Query scoping determina que tablas y nombres de columnas usamos en las queries.
Cuando abres logs desde un recurso de Application Insights, el query scope hace target de recursos usando Application Insigts table names como requests, exceptions y dependencies. Cuando se abre desde un workspace de Log Analytics usa table names como AppRequests, AppExceptions y AppDependencies.

Explore Application Insights table structure

Tablas más relevantes

  • requests almacena incoming HTTP requests con detalles como duration, response code y success status. Cada row representa una requesta
  • dependencies captura outbound calls desde tu app a BBDD, HTTP endpoints, Azure services y otros micros
  • exceptions ambas handled y unhandled
  • traces app log messages de frameworks como ILogger, log4j
  • customEvents almacena custom business events como document classified
  • customMetrics almacena custom numeric measurements como queue depth o model inference confidence score
  • performanceCounters almacena system-level metrics como CPU usage

Hay columnas que son comunes a todas las tablas:

  • timestamp
  • operation_Id linkea los items de una single distributed trace para poder seguir las requests a través de los servicios
  • cloud_RoleName identifica que servicio genera la telemetría
  • customDimension contiene una bag de propiedades dinamicas para enriquecer la telemetria con tus propios datos

Filter and select data with core operators

KQL tiene todos los filtros comunes como where, ==, etc.

Distintos tenemos:

  • project operator - selecciona columnas especificas a incluir en el output. Reduce la width de tus resultados y centra la atencion en los datos que interesan
  • take operator - devuelve un ser arbitrario de n rows de la tabla. Es util para inspeccionar el estado y calidad de los datos con un muestreo
  • top operators - devuelve las primeras n rows, sorteadas por una columna especifica
requests
| where timestamp > ago(1h)
| where success == false
| project timestamp, name, resultCode, duration, cloud_RoleName
| top 20 by duration desc

Aggregate and summarize data

El filtering visto antes muestra records individuales. Para entender trends y patrones necesitamos aggregation.

El operator summarize agrupa rows y aplica funciones de agregacion para producir summary statistics. Cada combinacion unica de valores en el by produce un output row en los results.

Los operadores comunes que funcionan con summarize son avg(), sum(), etc. Los distintos son:

  • dcount() function - estima el count de distinct values. Util para cosas como how many unique users experienced this error
  • count_distinct() - para small datasets. es mas preciso pero mas intensivo de recursos
  • percentile() function - calcula un specific percentile value. util para obtener por ejemplo latency analisys del p95
  • bin() function - agrupa valores continuos como timestamps en intervalos fijos. Ejemplo bin(timestamp, 1h) redondea cada timestamp a la hora más cercana
requests
| where timestamp > ago(24h)
| summarize requestCount = count(), avgDuration = avg(duration)
    by bin(timestamp, 1h), cloud_RoleName

Visualizar query results with the render operator

El render operator sirve para especificar chart types en la query. Añadir render como final step le dice que saque los resultados como un chart en vez de una tabla. Util para visualizar trends y comparaciones.

requests
| where timestamp > ago(24h)
| summarize requestCount = count() by bin(timestamp, 1h), cloud_RoleName
| render timechart

App Configuration vs Key Vault (what to store)

App Configuration y Key Vault sirven roles complementarios en administrar settings para apps.

Azure App Configuration

Está diseñado para app settings, en pares clave-valor, y que sean no sensibles.

Características

  • labels para diferenciar entornos
  • feature flag management
  • rollbacks
  • dynamic refresh

Esto incluye

  • endpoints
  • feature flags
  • batch sizes
  • rerty counts
  • timeout values
  • display strings

Azure Key Vault

Está diseñado para datos sensibles.

Características

  • Encripta los datos at rest con HSM-backed protection
  • loggea cada op y se puede auditar
  • fuerza expiration policies
  • automated rotation
  • provee soft-delete con purge protection

Esto incluye

  • API keys
  • connection strings
  • passwords
  • keys criptograficas
  • certificados

Ejemplos

Setting type Service Example
Configuracion nonsensitive App Configuration (direct value) OpenAI:Endpoint
Feature toggles App Configuration (feature flag) EnableBatchProcessing
API keys and tokens Key Vault (via App Configuration reference) OpenAI:ApiKey
Connection strings Key Vault (via App Configuration reference) CosmosDB:ConnectionString
Certificates Key Vault (direct access) TLS certificates for HTTPS

Anti-patterns

  • Storing secrets directly in App Configuration: always use Key Vault references for values that grant access to resources
  • Using Key Vault for non-sensitive settings
  • Duplicating settings across both services without references
  • Embedding all configuration in application code