Skip to content
← Todas las publicaciones
· Delta1 Labs ObservabilityKeyright

Instrumentar la verificación de licencias con OpenTelemetry

Instrumentas cada llamada a la base de datos y cada petición HTTP saliente de tu aplicación, pero la única dependencia que decide si el software puede ejecutarse —la comprobación de licencia— suele ser invisible hasta que un cliente abre un ticket. Esta guía conecta una verificación de Keyright con OpenTelemetry igual que cualquier dependencia crítica: un Meter con un contador de verificaciones, un histograma de duración y un medidor de caducidad; un span de ActivitySource alrededor del refresco que registra si la respuesta llegó en línea, desde la caché o desde la ventana de gracia; las etiquetas de baja cardinalidad que hacen un panel y las de alta cardinalidad (la clave, el titular, el id de máquina) que nunca deben ser valores de etiqueta; y el cableado OTLP y las cuatro alertas que merecen una llamada.

Tienes un ActivitySource alrededor de tus llamadas HTTP salientes, un histograma sobre los viajes de ida y vuelta a la base de datos y un panel que se enciende en cuanto tu proveedor de pagos se ralentiza. Luego mira la única llamada que decide si tu software puede ejecutarse esta noche —la verificación de licencia— y casi siempre es un punto ciego. Falla, se ralentiza, empieza a servir discretamente a cada cliente desde una concesión en caché porque tu instancia de Keyright está brevemente inalcanzable, y lo primero que alguien se entera es por un ticket de soporte.

Una comprobación de licencia es una llamada a una dependencia. Merece el mismo trato que cualquier otra: una métrica sobre la que puedas alertar y un span que puedas leer cuando una activación es misteriosamente lenta. Esta entrada conecta una verificación de Keyright con OpenTelemetry de principio a fin y, lo que es igual de importante, mantiene el único secreto implicado fuera de tu backend de telemetría.

Dos señales, dos funciones

Las métricas y las trazas responden a preguntas distintas, y quieres ambas.

  • Las métricas responden a «¿está sana la flota ahora mismo?». Son contadores e histogramas baratos y pre-agregados: cuántas verificaciones tuvieron éxito, cuántas se denegaron, cuánto tardaron, cuán cerca está la licencia activa de caducar. Esto es lo que lee un panel y una regla de alerta.
  • Las trazas responden a «¿por qué fue esta en concreto lenta o errónea?». Un span alrededor de una única verificación lleva su tiempo, su resultado y si la respuesta vino del servicio o de una concesión en caché: el detalle que necesitas la única vez que un cliente de una región concreta informa de un bloqueo.

La tentación es apoyarse en los registros para todo. Los registros son la herramienta equivocada para la primera pregunta: no puedes preguntar de forma barata «¿qué fracción de las verificaciones de los últimos cinco minutos se denegó?» a un agregador de registros, pero un contador la responde gratis.

Un Meter y sus instrumentos

Todo empieza con un Meter y los instrumentos colgados de él. Decláralos una sola vez, de forma estática, para que haya un único lugar que posea los nombres y las unidades.

using System.Diagnostics;
using System.Diagnostics.Metrics;
using Keyright;   // LicenseInfo, LicenseStatus, RefreshStatus

public static class LicenseTelemetry
{
    public const string MeterName = "Delta1.Licensing";
    public const string ActivitySourceName = "Delta1.Licensing";

    private static readonly Meter Meter = new(MeterName, "1.0.0");
    internal static readonly ActivitySource Activity = new(ActivitySourceName, "1.0.0");

    // How many verifications, tagged by status/outcome/source.
    private static readonly Counter<long> VerifyCount =
        Meter.CreateCounter<long>("keyright.verify.count",
            unit: "{verification}",
            description: "License verifications, tagged by status and source.");

    // How long each verification took.
    private static readonly Histogram<double> VerifyDuration =
        Meter.CreateHistogram<double>("keyright.verify.duration",
            unit: "ms",
            description: "Wall time spent verifying a license.");

    // How close the active license is to expiry (an async gauge, polled by the SDK).
    private static volatile int _daysRemaining = -1;
    static LicenseTelemetry() =>
        Meter.CreateObservableGauge("keyright.license.days_remaining",
            () => _daysRemaining,
            unit: "d",
            description: "Days until the active license expires; -1 when unknown.");

    public static void SetDaysRemaining(int days) => _daysRemaining = days;
}

Tres instrumentos, tres preguntas. El Counter<long> es la tasa de verificaciones y, una vez etiquetado, la tasa de denegaciones. El Histogram<double> es la latencia y, como una verificación puede ir a la red, su cola es lo que vigilas. El ObservableGauge es una lectura por extracción: OpenTelemetry llama al callback en el momento de la recolección, así que nunca emites un punto a menos que un scrape lo pida, lo cual es exactamente lo correcto para un valor que cambia despacio como «días hasta la caducidad».

Registrar una verificación

El método Validate() de Keyright devuelve un LicenseInfo cuyo Status es un enum acotado (Valid, Expired, Revoked, SignatureInvalid, MachineMismatch, ClockTampered, NoLicense) y cuyos DaysRemaining / IsExpiringSoon ya usas en otros sitios. La ruta de refresco, a través de RefreshAsync, te dice de dónde vino la respuesta: del servicio, un acierto de caché «304 not modified», o una concesión en caché servida porque el servicio estaba inalcanzable. Esa procedencia es la etiqueta más útil que puedes adjuntar.

public static void RecordVerify(LicenseInfo info, double elapsedMs, string source)
{
    // Keep this list SHORT and BOUNDED — see the cardinality rule below.
    var tags = new TagList
    {
        { "status",  info.Status.ToString() },                              // 7 values
        { "outcome", info.Status == LicenseStatus.Valid ? "allow" : "deny" }, // 2 values
        { "source",  source },                                              // online | cache | grace
        { "expiring_soon", info.IsExpiringSoon }                            // true | false
    };

    VerifyCount.Add(1, tags);
    VerifyDuration.Record(elapsedMs, tags);
    SetDaysRemaining(info.DaysRemaining);
}

Las etiquetas que conservas y las que te costarán caras

El coste de una métrica no es el número de puntos, sino el número de combinaciones de etiquetas distintas, porque cada una es una serie temporal separada que tu backend almacena e indexa. Cuatro etiquetas acotadas como las de arriba se multiplican hasta unas pocas docenas de series: bien. Añade una etiqueta no acotada y el recuento de series explota con tu base de clientes. Esto se llama explosión de cardinalidad, y una comprobación de licencia es un campo minado para ello, porque los campos más obviamente relevantes son justo los que no debes usar como etiquetas.

  • La clave de licencia es un secreto al portador. Nunca debe ser un valor de etiqueta: eso envía la clave directamente a tu almacén de métricas y a tu backend de trazas, el mismo error que advierte la guía de registro, solo que por otra tubería.
  • El nombre del titular, la huella de máquina y cualquier huella de clave no están acotados. Una serie por cliente o por dispositivo anula el sentido de una métrica pre-agregada y dispara discretamente tu factura de observabilidad.

La regla es sencilla: las etiquetas son para cosas con un conjunto de valores pequeño y fijo. La identidad va en un span, donde es un atributo puntual de una única traza que muestreaste, no una etiqueta multiplicada sobre cada punto para siempre.

keyright.verify → Meter → OTLPLicenseInfoStatusDaysRemainingIsExpiringSoon+ source (refresh)keep as tags (bounded)status · outcomesource · expiring_soon~ dozens of seriesnever a tag (unbounded / secret)license key · licenseemachine id · fingerprintcardinality blowout → span onlyMeterverify.countCounter<long>verify.durationHistogram<double>days_remainingObservableGaugeOTLPexportersampled span attributeslicensee, key-id → one trace, not a labelBounded fields become metric labels; identity rides a span, so the key never enters the metrics store.

Trazar la ruta de refresco

Las métricas te dicen que subieron las denegaciones; un span te dice por qué una verificación se comportó como lo hizo. Envuelve la verificación en una actividad, mide su tiempo con un Stopwatch monótono (el reloj de pared puede saltar a mitad de la medición) y registra la procedencia como atributos y eventos del span.

public async Task<LicenseInfo> VerifyAsync(string licenseKey, CancellationToken ct)
{
    using Activity? span = LicenseTelemetry.Activity.StartActivity(
        "license.verify", ActivityKind.Client);

    var sw = Stopwatch.StartNew();
    string source = "online";

    // Pull the freshest lease we can; fall through to cache/grace on an outage.
    RefreshResult refresh = await _client.RefreshAsync(ct);
    source = refresh.Status switch
    {
        RefreshStatus.Refreshed          => "online",
        RefreshStatus.NotModified        => "cache",   // 304 — nothing changed
        RefreshStatus.ServiceUnreachable => "grace",   // served from a signed cached lease
        _                                => "online"
    };

    LicenseInfo info = _client.Validate(licenseKey);
    sw.Stop();

    // Identity and detail live on the span — one trace, not a metric label.
    span?.SetTag("license.status", info.Status.ToString());
    span?.SetTag("license.source", source);
    span?.SetTag("license.days_remaining", info.DaysRemaining);
    span?.SetTag("license.key_id", info.KeyId);   // non-secret handle, if your payload carries one
    span?.SetStatus(info.Status == LicenseStatus.Valid
        ? ActivityStatusCode.Ok
        : ActivityStatusCode.Error);

    if (source == "grace")
        span?.AddEvent(new ActivityEvent("served-from-grace-window"));

    LicenseTelemetry.RecordVerify(info, sw.Elapsed.TotalMilliseconds, source);
    return info;
}

Fíjate en el reparto de tareas. license.key_id —un identificador no secreto, nunca la clave en bruto— va en el span, donde es un único atributo de una traza muestreada, no una etiqueta estampada en una serie temporal para siempre. El evento source == "grace" es la miga de pan que, meses después, explica por qué una verificación se mantuvo en verde durante una hora mientras el servicio estaba caído.

Cableando el exportador

Registra el meter y la fuente con el SDK de OpenTelemetry y apúntalos a tu colector. Los instrumentos de licencia viajan por la misma tubería OTLP que el resto de tu aplicación; no hay nada específico de licencias en el transporte.

builder.Services.AddOpenTelemetry()
    .ConfigureResource(r => r.AddService("acme-designer"))
    .WithMetrics(m => m
        .AddMeter(LicenseTelemetry.MeterName)
        .AddView("keyright.verify.duration", new ExplicitBucketHistogramConfiguration
        {
            // Buckets sized for a call that is usually local but sometimes hits the network.
            Boundaries = new double[] { 1, 5, 10, 25, 50, 100, 250, 500, 1000 }
        })
        .AddOtlpExporter())
    .WithTracing(t => t
        .AddSource(LicenseTelemetry.ActivitySourceName)
        .AddOtlpExporter());

Los límites explícitos del histograma importan: los buckets por defecto están afinados para trabajo de menos de un milisegundo, y agruparán cada verificación que va a la red en un único bucket de desbordamiento donde ya no puedes ver la cola. Dimensiona los buckets para la llamada que realmente estás haciendo.

Las cuatro cosas que merece la pena alertar

Con el contador, el histograma y el medidor fluyendo, cuatro reglas cubren los modos de fallo que de verdad llaman a alguien. Expresadas de forma aproximada e independiente del backend:

  1. Tasa de denegaciones. Que rate(keyright.verify.count{outcome="deny"}) suba es o bien una revocación que se propagó, o bien un reloj mal puesto en una flota de máquinas, o bien un desajuste de clave de firma tras una rotación. Un escalón repentino es la señal.
  2. Saturación de gracia. Una proporción distinta de cero y creciente de source="grace" significa que tu instancia ha estado inalcanzable el tiempo suficiente para que los clientes vivan de concesiones en caché. Aún no es visible para el cliente, lo cual es justo por lo que quieres la alerta antes de que se agote MaxOfflineDuration y se convierta en una caída.
  3. Cola de latencia de verificación. El p99 de keyright.verify.duration es tu aviso temprano de que el viaje de ida y vuelta del refresco se está degradando, mucho antes de que se convierta en tiempos de espera agotados.
  4. Días restantes. Que keyright.license.days_remaining baje por debajo de un umbral (digamos 7) es la versión para toda la flota del aviso de renovación: una alerta en lugar de un cliente sorprendido por cada caducidad.

El beneficio

Nada de esto cambia lo que decide la comprobación de licencia: la puerta sigue fallando cerrada ante una clave revocada o caducada. Lo que cambia es que la decisión ya no es invisible. Una verificación es ahora una dependencia de primera clase en tu panel: puedes ver su tasa, su latencia y el momento en que pasa discretamente de responder en línea a responder desde la gracia. Y como el diseño traza una línea dura entre las etiquetas acotadas y la identidad, obtienes toda esa observabilidad sin que una sola clave de licencia, nombre de titular o id de máquina aterrice jamás en tu backend de telemetría.

Prueba Nebula.NET

Endurece tu código .NET en minutos — empieza con la edición gratuita.