Cosmos.OpenTelemetry.Functions 0.1.1

Cosmos.OpenTelemetry.Functions

Configuración OpenTelemetry del worker aislado de Azure Functions para los bounded contexts de Cosmos. Reemplaza el bloque AddOpenTelemetry()…UseAzureMonitorExporter() que cada Function App repetía por una sola línea, y suma la exportación por OTLP al Gateway de observabilidad.

Uso

using Cosmos.OpenTelemetry.Functions;

services.AddCosmosFunctionsTelemetry(
    configuration,                      // en Program.cs: builder.Configuration
    "Billing",                          // dominio → atributo cosmos.dominio
    "Wolverine", "Marten", "Cosmos.ControlPlane.Billing.*"); // ActivitySources (admiten comodín)

Se pasa la configuración del host (builder.Configuration en Program.cs, que en Functions incluye los app settings como variables de entorno). En un test se usa una configuración en memoria (new ConfigurationBuilder().AddInMemoryCollection(...)), sin tocar las variables del proceso. Es el mismo patrón de los service defaults de .NET Aspire.

Es la única configuración de telemetría del worker: no combinar con UseAzureMonitorExporter() ni UseOtlpExporter(), y no usar el Distro UseAzureMonitor() en el worker. Microsoft lo desaconseja: «avoid using the Azure Monitor distro in the worker process to prevent duplicate telemetry», porque trae la instrumentación de ASP.NET Core y el host ya emite la request (Use OpenTelemetry with Azure Functions — Duplicate request telemetry).

La IConfiguration que se pasa tiene que ser la misma que está registrada en el contenedor: la condición la lee el paquete, pero el exporter OTLP lee el resto de sus claves de la registrada (y, si no hay ninguna, del entorno del proceso). En Program.cs eso ya se cumple con builder.Configuration; en un test con ServiceCollection hay que registrarla (services.AddSingleton(configuration)).

Qué registra

Exporters condicionales

Cada exporter se activa solo si su clave existe en la configuración al registrar los servicios. Así el mismo build se despliega antes que los app settings y no exporta por OTLP hasta que se configure el endpoint, app por app. Ojo: en una app que ya tiene la connection string de AI, el despliegue cambia lo que AI recibe (sin muestreo, logs con scopes). Desde 0.1.1 las métricas System.Runtime del worker ya no llegan a AI (en 0.1.0 sí).

Sin ninguna de las dos, la telemetría se recolecta pero no sale del proceso (desarrollo local). Ojo con los logs: UseFunctionsWorkerDefaults() le anuncia al host la capacidad WorkerOpenTelemetryEnabled y el host deja de reenviar los logs del worker. Sin variables, esos logs no llegan a ningún destino, ni siquiera al AI del host.

El muestreo lo fija el paquete. Mientras AI está activo, su sampler gobierna todas las trazas (también las que salen por OTLP), y OTEL_TRACES_SAMPLER/OTEL_TRACES_SAMPLER_ARG y la sección AzureMonitorExporter de la configuración no tienen efecto. Para bajar volumen hay que cambiar el código o quitar la connection string. Sin AI, el SDK sí respeta OTEL_TRACES_SAMPLER. El sampler de AI con ratio 1 muestrea siempre y no depende del padre: si el host muestrea sus requests, el worker emite igual (spans sin padre en el destino).

Los atributos cosmos.* en AI. El exporter de Azure Monitor no copia los atributos del resource a requests, dependencies ni traces: cosmos.proceso y cosmos.dominio solo aparecen en la métrica _OTELRESOURCE_ (en customMetrics). Para filtrar por proceso o dominio en AI se usa cloud_RoleName/cloud_RoleInstance; en el Gateway sí son atributos consultables.

El host de Functions (host.json con "telemetryMode": "OpenTelemetry") exporta por su cuenta con las mismas variables. Este paquete solo configura el worker.

Nota sobre el namespace

Dentro de un namespace Cosmos.*, un nombre calificado OpenTelemetry.Trace.X escrito en el cuerpo del código resuelve primero a Cosmos.OpenTelemetry. Usa directivas using OpenTelemetry.Trace; al inicio del archivo (resuelven desde el namespace global) o global::OpenTelemetry….