Skip to content
← Tous les articles
· Delta1 Labs ObservabilityKeyright

Instrumenter la vérification de licence avec OpenTelemetry

Vous instrumentez chaque appel à la base de données et chaque requête HTTP sortante de votre application, mais la seule dépendance qui décide si le logiciel a le droit de s'exécuter — le contrôle de licence — reste généralement invisible jusqu'à ce qu'un client ouvre un ticket. Ce guide pratique branche une vérification Keyright sur OpenTelemetry comme n'importe quelle dépendance critique : un Meter avec un compteur de vérifications, un histogramme de durée et une jauge d'expiration ; un span ActivitySource autour du rafraîchissement qui enregistre si la réponse est venue en ligne, du cache ou de la fenêtre de grâce ; les étiquettes à faible cardinalité qui font un tableau de bord et celles à haute cardinalité (la clé, le titulaire, l'id machine) qui ne doivent jamais devenir des valeurs d'étiquette ; et le câblage OTLP ainsi que les quatre alertes qui méritent un appel.

Vous avez un ActivitySource autour de vos appels HTTP sortants, un histogramme sur vos allers-retours vers la base de données et un tableau de bord qui s’allume dès que votre prestataire de paiement ralentit. Regardez ensuite le seul appel qui décide si votre logiciel a le droit de s’exécuter ce soir — la vérification de licence — et c’est presque toujours un angle mort. Elle échoue, elle ralentit, elle se met discrètement à servir chaque client depuis un bail en cache parce que votre instance Keyright est brièvement injoignable, et la première chose dont on entend parler, c’est un ticket de support.

Un contrôle de licence est un appel de dépendance. Il mérite le même traitement que n’importe quel autre : une métrique sur laquelle vous pouvez déclencher une alerte et un span que vous pouvez lire quand une activation est mystérieusement lente. Cet article branche une vérification Keyright sur OpenTelemetry de bout en bout et, tout aussi important, garde le seul secret impliqué hors de votre backend de télémétrie.

Deux signaux, deux rôles

Les métriques et les traces répondent à des questions différentes, et vous voulez les deux.

  • Les métriques répondent à « la flotte est-elle en bonne santé en ce moment ? ». Ce sont des compteurs et des histogrammes bon marché et pré-agrégés : combien de vérifications ont réussi, combien ont été refusées, combien de temps elles ont pris, à quel point la licence active est proche de l’expiration. C’est ce que lit un tableau de bord et une règle d’alerte.
  • Les traces répondent à « pourquoi celle-ci en particulier a-t-elle été lente ou fausse ? ». Un span autour d’une seule vérification porte son temps, son résultat et l’indication de savoir si la réponse est venue du service ou d’un bail en cache : le détail dont vous avez besoin la seule fois où un client d’une région donnée signale un blocage.

La tentation est de s’appuyer sur les journaux pour tout. Les journaux sont le mauvais outil pour la première question : vous ne pouvez pas demander à bas coût « quelle fraction des vérifications des cinq dernières minutes a été refusée ? » à un agrégateur de journaux, mais un compteur y répond gratuitement.

Un Meter et ses instruments

Tout commence par un Meter et les instruments qui y sont accrochés. Déclarez-les une seule fois, de façon statique, pour qu’il y ait un unique endroit qui possède les noms et les unités.

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;
}

Trois instruments, trois questions. Le Counter<long> est le taux de vérifications et, une fois étiqueté, le taux de refus. L’Histogram<double> est la latence et, comme une vérification peut passer par le réseau, sa queue est ce que vous surveillez. L’ObservableGauge est une lecture par extraction : OpenTelemetry appelle le callback au moment de la collecte, donc vous n’émettez jamais un point à moins qu’un scrape ne le demande, ce qui est exactement ce qu’il faut pour une valeur qui évolue lentement comme « jours avant l’expiration ».

Enregistrer une vérification

La méthode Validate() de Keyright renvoie un LicenseInfo dont le Status est un enum borné (Valid, Expired, Revoked, SignatureInvalid, MachineMismatch, ClockTampered, NoLicense) et dont les DaysRemaining / IsExpiringSoon vous servent déjà ailleurs. Le chemin de rafraîchissement, via RefreshAsync, vous indique d’où la réponse est venue : du service, un succès de cache « 304 not modified », ou un bail en cache servi parce que le service était injoignable. Cette provenance est l’étiquette la plus utile que vous puissiez attacher.

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);
}

Les étiquettes que vous gardez, et celles qui vous coûteront cher

Le coût d’une métrique n’est pas le nombre de points : c’est le nombre de combinaisons d’étiquettes distinctes, car chacune est une série temporelle distincte que votre backend stocke et indexe. Quatre étiquettes bornées comme celles ci-dessus se multiplient jusqu’à quelques dizaines de séries : parfait. Ajoutez une seule étiquette non bornée et le nombre de séries explose avec votre base de clients. On appelle cela une explosion de cardinalité, et un contrôle de licence est un champ de mines pour cela, parce que les champs les plus manifestement pertinents sont justement ceux qu’il ne faut pas utiliser comme étiquettes.

  • La clé de licence est un secret au porteur. Elle ne doit jamais être une valeur d’étiquette : cela expédie la clé droit dans votre magasin de métriques et votre backend de traces, la même erreur que celle contre laquelle le guide de journalisation met en garde, simplement par un autre tuyau.
  • Le nom du titulaire, l’empreinte machine et toute empreinte de clé ne sont pas bornés. Une série par client ou par appareil ruine l’intérêt d’une métrique pré-agrégée et fait discrètement grimper votre facture d’observabilité.

La règle est simple : les étiquettes sont pour des choses à ensemble de valeurs petit et fixe. L’identité va dans un span, où elle est un attribut ponctuel d’une seule trace que vous avez échantillonnée, pas une étiquette multipliée sur chaque point pour toujours.

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.

Tracer le chemin de rafraîchissement

Les métriques vous disent que les refus ont augmenté ; un span vous dit pourquoi une vérification s’est comportée comme elle l’a fait. Enveloppez la vérification dans une activité, mesurez son temps avec un Stopwatch monotone (l’horloge murale peut sauter en plein milieu de la mesure) et enregistrez la provenance sous forme d’attributs et d’événements du 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;
}

Notez la répartition des tâches. license.key_id — un identifiant non secret, jamais la clé brute — va sur le span, où il est un unique attribut d’une trace échantillonnée, pas une étiquette estampillée sur une série temporelle pour toujours. L’événement source == "grace" est le fil d’Ariane qui, des mois plus tard, explique pourquoi une vérification est restée au vert pendant une heure alors que le service était hors service.

Câbler l’exportateur

Enregistrez le meter et la source auprès du SDK OpenTelemetry et pointez-les vers votre collecteur. Les instruments de licence empruntent le même tuyau OTLP que le reste de votre application ; il n’y a rien de spécifique aux licences dans le transport.

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());

Les limites explicites de l’histogramme comptent : les buckets par défaut sont réglés pour un travail inférieur à la milliseconde, et ils tasseront chaque vérification passée par le réseau dans un unique bucket de débordement où vous ne pouvez plus voir la queue. Dimensionnez les buckets pour l’appel que vous faites réellement.

Les quatre choses qui méritent une alerte

Avec le compteur, l’histogramme et la jauge qui coulent, quatre règles couvrent les modes de défaillance qui appellent vraiment quelqu’un. Exprimées de façon approximative et indépendante du backend :

  1. Taux de refus. Un rate(keyright.verify.count{outcome="deny"}) qui grimpe est soit une révocation qui s’est propagée, soit une horloge mal réglée sur une flotte de machines, soit un décalage de clé de signature après une rotation. Une marche soudaine est le signal.
  2. Saturation de grâce. Une proportion non nulle et croissante de source="grace" signifie que votre instance est injoignable depuis assez longtemps pour que les clients vivent de baux en cache. Ce n’est pas encore visible pour le client, ce qui est justement pourquoi vous voulez l’alerte avant que MaxOfflineDuration ne s’épuise et que cela ne devienne une panne.
  3. Queue de latence de vérification. Le p99 de keyright.verify.duration est votre avertissement précoce que l’aller-retour du rafraîchissement se dégrade, bien avant qu’il ne se transforme en délais d’attente dépassés.
  4. Jours restants. Un keyright.license.days_remaining qui passe sous un seuil (disons 7) est la version à l’échelle de la flotte du rappel de renouvellement : une alerte au lieu d’un client surpris par expiration.

Le bénéfice

Rien de tout cela ne change ce que la vérification de licence décide : la barrière échoue toujours fermée face à une clé révoquée ou expirée. Ce qui change, c’est que la décision n’est plus invisible. Une vérification est désormais une dépendance de premier ordre sur votre tableau de bord : vous pouvez voir son taux, sa latence et le moment où elle bascule discrètement de répondre en ligne à répondre depuis la grâce. Et parce que la conception trace une ligne nette entre les étiquettes bornées et l’identité, vous obtenez toute cette observabilité sans qu’une seule clé de licence, un nom de titulaire ou un id machine n’atterrisse jamais dans votre backend de télémétrie.

Essayez Nebula.NET

Renforcez votre code .NET en quelques minutes — commencez avec l'édition gratuite.