OpenTelemetry en .NET desde cero: tu primera traza distribuida en 30 minutos

Levantar el visor de trazas

docker run --rm -it -p 18888:18888 -p 4317:18889 \
  mcr.microsoft.com/dotnet/aspire-dashboard:latest
 
# El panel queda en http://localhost:18888
# La consola imprime la URL con el token de acceso: úsala tal cual

docker run -d --name jaeger \
  -e COLLECTOR_OTLP_ENABLED=true \
  -p 16686:16686 -p 4317:4317 -p 4318:4318 \
  jaegertracing/all-in-one:latest
 
# El panel queda en http://localhost:16686

Por qué primero esto

Los dos escuchan OTLP en el puerto 4317, que es el estándar. Si empiezas al revés —instrumentando sin destino— vas a pasar veinte minutos dudando si el problema es tu código o la conexión. Con el visor arriba, cualquier error posterior tiene una sola causa posible.

Instalar los paquetes

dotnet add package OpenTelemetry.Extensions.Hosting
dotnet add package OpenTelemetry.Exporter.OpenTelemetryProtocol
dotnet add package OpenTelemetry.Instrumentation.AspNetCore
dotnet add package OpenTelemetry.Instrumentation.Http
dotnet add package OpenTelemetry.Instrumentation.Runtime
 
# Si usas SQL Server, Azure SQL o cualquier cliente ADO.NET:
dotnet add package OpenTelemetry.Instrumentation.SqlClient --prerelease

Sobre el --prerelease

La instrumentación de SqlClient ha vivido en versiones preliminares bastante más tiempo que las demás. Es estable en la práctica y se usa ampliamente en producción, pero revisa la versión disponible el día que lo instales y fíjala en el archivo del proyecto en lugar de dejarla flotando.

Configurar en Program.cs

using OpenTelemetry.Metrics;
using OpenTelemetry.Resources;
using OpenTelemetry.Trace;
 
var builder = WebApplication.CreateBuilder(args);
 
builder.Services.AddOpenTelemetry()
    .ConfigureResource(r => r
        .AddService(serviceName: "api-pedidos", serviceVersion: "1.0.0")
        .AddAttributes(new Dictionary<string, object>
        {
            ["deployment.environment"] = builder.Environment.EnvironmentName
        }))
 
    .WithTracing(t => t
        .AddAspNetCoreInstrumentation(o =>
        {
            o.RecordException = true;
            // no ensuciar con los sondeos de salud
            o.Filter = ctx => !ctx.Request.Path.StartsWithSegments("/health");
        })
        .AddHttpClientInstrumentation()
        .AddSqlClientInstrumentation()
        .AddOtlpExporter())
 
    .WithMetrics(m => m
        .AddAspNetCoreInstrumentation()
        .AddHttpClientInstrumentation()
        .AddRuntimeInstrumentation()
        .AddOtlpExporter());
 
var app = builder.Build();

Qué hace cada línea

AddService es el nombre con el que tu aplicación va a aparecer en el tablero: ponle el nombre real del servicio, no «MiApi». El atributo deployment.environment te permite después separar producción de pruebas en el mismo destino, y agradecerás tenerlo desde el día uno.

Ver tu primera traza

dotnet run
 
# En otra terminal, genera tráfico:
curl http://localhost:5000/api/pedidos
curl http://localhost:5000/api/pedidos/42

Si no aparece nada

Tres causas cubren prácticamente todos los casos. Uno: el contenedor no está corriendo o el puerto 4317 está ocupado —verifica con docker ps—. Dos: estás en Linux o WSL y la aplicación corre dentro de otro contenedor, así que localhost no apunta al visor; usa el nombre del servicio o host.docker.internal. Tres: el exportador manda por lotes cada pocos segundos, así que espera unos instantes antes de concluir que falló.

Completar el recorrido

// En Program.cs
builder.Services.AddHttpClient("pagos", c =>
{
    c.BaseAddress = new Uri("https://api.proveedor-pagos.mx/");
});
 
// En el servicio que lo usa
public class ServicioPagos(IHttpClientFactory factory)
{
    public async Task<bool> CobrarAsync(decimal monto)
    {
        var http = factory.CreateClient("pagos");
        var r = await http.PostAsJsonAsync("v1/cargos", new { monto });
        return r.IsSuccessStatusCode;
    }
}

El momento en que hace clic

Genera una petición que toque base de datos y servicio externo. Vas a ver la barra completa dividida: 12 ms tu código, 34 ms la consulta, 890 ms el proveedor de pagos. Esa imagen es la que convence a un equipo entero de que valió la pena.

Cuidado con el texto de las consultas

La instrumentación de SQL permite capturar el texto completo de cada consulta. Es utilísimo para depurar y es un riesgo real de fuga: si tus consultas llevan valores en línea, vas a mandar datos de clientes al sistema de observabilidad. Actívalo solo en desarrollo, o asegúrate de que todo vaya parametrizado.

Agregar tus propios tramos

using System.Diagnostics;
using OpenTelemetry.Trace;
 
public class ProcesadorPedidos
{
    // Una sola instancia estática por componente
    private static readonly ActivitySource Fuente =
        new("Pedidos.Procesador", "1.0.0");
 
    public async Task<Resultado> ProcesarAsync(Pedido pedido)
    {
        using var actividad = Fuente.StartActivity("procesar-pedido");
 
        // Atributos de negocio: baja cardinalidad, alto valor
        actividad?.SetTag("pedido.canal", pedido.Canal);
        actividad?.SetTag("pedido.lineas", pedido.Lineas.Count);
        actividad?.SetTag("pedido.requiere_factura", pedido.RequiereFactura);
 
        try
        {
            var resultado = await EjecutarAsync(pedido);
            actividad?.SetStatus(ActivityStatusCode.Ok);
            return resultado;
        }
        catch (Exception ex)
        {
            actividad?.SetStatus(ActivityStatusCode.Error, ex.Message);
            actividad?.RecordException(ex);
            throw;
        }
    }
}

.WithTracing(t => t
    .AddSource("Pedidos.Procesador")      // ← el nombre debe coincidir exacto
    .AddAspNetCoreInstrumentation(/* ... */)
    // ... el resto igual
)

Regla para los atributos

Etiqueta con valores de baja cardinalidad: canal, tipo de cliente, forma de pago, sucursal. El identificador del pedido está bien en una traza —son individuales por naturaleza—, pero nunca como dimensión de una métrica. Ahí es donde las facturas de observabilidad se descontrolan.

Prepararlo para producción

OTEL_SERVICE_NAME=api-pedidos
OTEL_EXPORTER_OTLP_ENDPOINT=http://collector.interno:4317
OTEL_EXPORTER_OTLP_PROTOCOL=grpc
 
# Muestreo: 10% de las trazas, respetando la decisión del servicio origen
OTEL_TRACES_SAMPLER=parentbased_traceidratio
OTEL_TRACES_SAMPLER_ARG=0.1
 
# Atributos comunes a todo lo que emita el servicio
OTEL_RESOURCE_ATTRIBUTES=deployment.environment=produccion,service.namespace=ventas

Por qué un Collector

Absorbe los picos con su propia cola, te deja cambiar de destino sin volver a desplegar aplicaciones, permite filtrar o depurar atributos sensibles antes de que salgan, y habilita el muestreo por cola —quedarte con el 100% de las trazas con error y con un porcentaje del resto—, que es la única forma sensata de controlar el costo sin perder lo importante.

Sobre el parentbased

Con varios servicios instrumentados, el muestreo debe decidirse una sola vez, al inicio del recorrido, y respetarse aguas abajo. Si cada servicio decide por su cuenta, terminas con trazas incompletas: el tramo de entrada existe y el del servicio siguiente no. Es de los errores más frustrantes de diagnosticar.

Instrumentación completa

Imprimir o guardar como PDF

¿Instrumentaste una API y ahora tienes que hacerlo con quince?

Lo hacemos contigo. Definimos el estándar de instrumentación para tu stack, montamos el Collector con el muestreo y el filtrado de datos sensibles ya resueltos, instrumentamos los servicios críticos y dejamos a tu equipo capacitado para replicarlo en el resto.

• —Observabilidad y OpenTelemetry para .NET
• —Instrumentación de aplicaciones .NET Framework legacy
• —Diagnóstico de rendimiento, memoria y concurrencia
• —Mantenimiento y monitoreo de servidores

Diagnóstico de observabilidad sin costo. Revisamos tu stack y te decimos qué instrumentar primero.