Lizenzprüfung mit OpenTelemetry instrumentieren
Sie instrumentieren jeden Datenbankaufruf und jede ausgehende HTTP-Anfrage Ihrer Anwendung, aber die eine Abhängigkeit, die entscheidet, ob die Software laufen darf – die Lizenzprüfung – bleibt meist unsichtbar, bis ein Kunde ein Ticket öffnet. Diese Anleitung verdrahtet eine Keyright-Prüfung mit OpenTelemetry wie jede andere kritische Abhängigkeit: ein Meter mit einem Prüfzähler, einem Dauer-Histogramm und einer Ablauf-Anzeige; ein ActivitySource-Span um den Refresh-Pfad, der festhält, ob die Antwort online, aus dem Cache oder aus dem Kulanzfenster kam; die Tags mit niedriger Kardinalität, die ein Dashboard ergeben, und jene mit hoher Kardinalität (der Schlüssel, der Lizenznehmer, die Maschinen-ID), die niemals Tag-Werte werden dürfen; sowie die OTLP-Verdrahtung und die vier Alarme, die einen Anruf wert sind.
Sie haben eine ActivitySource um Ihre ausgehenden HTTP-Aufrufe, ein Histogramm über Ihre Datenbank-Roundtrips und ein Dashboard, das aufleuchtet, sobald Ihr Zahlungsanbieter langsam wird. Sehen Sie sich nun den einen Aufruf an, der entscheidet, ob Ihre Software heute Abend laufen darf – die Lizenzprüfung – und fast immer ist das ein blinder Fleck. Sie schlägt fehl, sie wird langsam, sie beginnt klammheimlich, jeden Kunden aus einem zwischengespeicherten Lease zu bedienen, weil Ihre Keyright-Instanz kurz nicht erreichbar ist, und das Erste, wovon jemand erfährt, ist ein Support-Ticket.
Eine Lizenzprüfung ist ein Abhängigkeitsaufruf. Sie verdient dieselbe Behandlung wie jeder andere: eine Metrik, auf die Sie alarmieren können, und einen Span, den Sie lesen können, wenn eine Aktivierung auf rätselhafte Weise langsam ist. Dieser Beitrag verdrahtet eine Keyright-Prüfung durchgängig mit OpenTelemetry und hält – ebenso wichtig – das eine beteiligte Geheimnis aus Ihrem Telemetrie-Backend heraus.
Zwei Signale, zwei Aufgaben
Metriken und Traces beantworten unterschiedliche Fragen, und Sie wollen beide.
- Metriken beantworten „ist die Flotte gerade gesund?“. Sie sind billige, voraggregierte Zähler und Histogramme: wie viele Prüfungen erfolgreich waren, wie viele abgelehnt wurden, wie lange sie dauerten, wie nah die aktive Lizenz am Ablauf ist. Das ist es, was ein Dashboard und eine Alarmregel lesen.
- Traces beantworten „warum war genau diese langsam oder falsch?“. Ein Span um eine einzelne Prüfung trägt deren Dauer, deren Ergebnis und ob die Antwort vom Dienst oder aus einem zwischengespeicherten Lease kam – das Detail, das Sie das eine Mal brauchen, wenn ein Kunde in einer bestimmten Region von einem Hänger berichtet.
Die Versuchung ist, sich für alles auf Logs zu stützen. Logs sind das falsche Werkzeug für die erste Frage: Sie können einen Log-Aggregator nicht billig fragen „welcher Anteil der Prüfungen in den letzten fünf Minuten wurde abgelehnt?“, aber ein Zähler beantwortet das umsonst.
Ein Meter und seine Instrumente
Alles beginnt mit einem Meter und den daran gehängten Instrumenten. Deklarieren Sie sie einmalig, statisch, damit es eine einzige Stelle gibt, die die Namen und Einheiten besitzt.
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;
}
Drei Instrumente, drei Fragen. Der Counter<long> ist die Rate der Prüfungen und, einmal getaggt, die Rate der Ablehnungen. Das Histogram<double> ist die Latenz, und weil eine Prüfung ins Netz gehen kann, ist ihr Ausläufer das, was Sie beobachten. Die ObservableGauge ist eine Pull-basierte Ablesung: OpenTelemetry ruft das Callback zum Erhebungszeitpunkt auf, Sie geben also nie einen Punkt aus, es sei denn, ein Scrape fragt danach – was für einen sich langsam ändernden Wert wie „Tage bis zum Ablauf“ genau richtig ist.
Eine Prüfung aufzeichnen
Die Methode Validate() von Keyright gibt ein LicenseInfo zurück, dessen Status ein beschränkter Enum ist (Valid, Expired, Revoked, SignatureInvalid, MachineMismatch, ClockTampered, NoLicense) und dessen DaysRemaining / IsExpiringSoon Sie andernorts bereits nutzen. Der Refresh-Pfad über RefreshAsync sagt Ihnen, woher die Antwort kam: vom Dienst, ein „304 not modified“-Cache-Treffer oder ein zwischengespeichertes Lease, das bedient wurde, weil der Dienst nicht erreichbar war. Diese Herkunft ist das nützlichste Tag, das Sie anhängen können.
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);
}
Die Tags, die Sie behalten, und die, die Sie teuer zu stehen kommen
Die Kosten einer Metrik sind nicht die Anzahl der Punkte – es ist die Anzahl der verschiedenen Tag-Kombinationen, denn jede ist eine eigene Zeitreihe, die Ihr Backend speichert und indiziert. Vier beschränkte Tags wie oben multiplizieren sich zu einigen Dutzend Reihen: in Ordnung. Fügen Sie ein unbeschränktes Tag hinzu, und die Reihenzahl explodiert mit Ihrem Kundenstamm. Das nennt man Kardinalitätsexplosion, und eine Lizenzprüfung ist dafür ein Minenfeld, denn die offensichtlich relevantesten Felder sind genau jene, die Sie nicht als Tags verwenden dürfen.
- Der Lizenzschlüssel ist ein Inhabergeheimnis. Er darf niemals ein Tag-Wert sein – das verschickt den Schlüssel direkt in Ihren Metrikspeicher und Ihr Trace-Backend, derselbe Fehler, vor dem die Logging-Anleitung warnt, nur durch eine andere Leitung.
- Der Name des Lizenznehmers, der Maschinen-Fingerabdruck und jeder Schlüssel-Fingerabdruck sind unbeschränkt. Eine Reihe pro Kunde oder pro Gerät macht den Sinn einer voraggregierten Metrik zunichte und treibt klammheimlich Ihre Observability-Rechnung hoch.
Die Regel ist einfach: Tags sind für Dinge mit einer kleinen, festen Wertemenge. Identität gehört in einen Span, wo sie ein einmaliges Attribut eines einzelnen, von Ihnen gesampelten Traces ist, kein Tag, das für immer über jeden Punkt vervielfacht wird.
Den Refresh-Pfad tracen
Metriken sagen Ihnen, dass die Ablehnungen gestiegen sind; ein Span sagt Ihnen, warum sich eine Prüfung so verhalten hat, wie sie es tat. Umschließen Sie die Prüfung mit einer Activity, messen Sie ihre Dauer mit einer monotonen Stopwatch (die Wanduhr kann mitten in der Messung springen) und halten Sie die Herkunft als Span-Attribute und -Events fest.
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;
}
Beachten Sie die Arbeitsteilung. license.key_id – ein nicht geheimer Handle, niemals der rohe Schlüssel – kommt auf den Span, wo es ein einzelnes Attribut eines gesampelten Traces ist, kein Tag, das für immer auf eine Zeitreihe gestempelt wird. Das Event source == "grace" ist die Brotkrume, die Monate später erklärt, warum eine Prüfung eine Stunde lang grün blieb, während der Dienst ausgefallen war.
Den Exporter verdrahten
Registrieren Sie den Meter und die Source beim OpenTelemetry-SDK und richten Sie sie auf Ihren Collector. Die Lizenzinstrumente reisen durch dieselbe OTLP-Leitung wie der Rest Ihrer Anwendung; am Transport ist nichts lizenzspezifisch.
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());
Die expliziten Histogramm-Grenzen sind wichtig: Die Standard-Buckets sind auf Arbeit unter einer Millisekunde abgestimmt, und sie quetschen jede netzgebundene Prüfung in einen einzigen Überlauf-Bucket, in dem Sie den Ausläufer nicht mehr sehen können. Dimensionieren Sie die Buckets für den Aufruf, den Sie tatsächlich machen.
Die vier Dinge, die einen Alarm wert sind
Mit fließendem Zähler, Histogramm und Anzeige decken vier Regeln die Fehlerarten ab, die wirklich jemanden anpiepsen. Grob und Backend-unabhängig formuliert:
- Ablehnungsrate. Ein steigendes
rate(keyright.verify.count{outcome="deny"})ist entweder ein Widerruf, der sich verbreitet hat, oder eine falsch gestellte Uhr auf einer Maschinenflotte, oder eine Signaturschlüssel-Diskrepanz nach einer Rotation. Eine plötzliche Stufe ist das Signal. - Kulanz-Sättigung. Ein von null verschiedener und steigender Anteil
source="grace"bedeutet, dass Ihre Instanz lange genug nicht erreichbar war, dass Clients von zwischengespeicherten Leases leben. Für den Kunden ist das noch nicht sichtbar – was genau der Grund ist, warum Sie den Alarm wollen, bevorMaxOfflineDurationaufgebraucht ist und es zu einem Ausfall wird. - Latenz-Ausläufer der Prüfung. Das p99 von
keyright.verify.durationist Ihre Frühwarnung, dass der Refresh-Roundtrip sich verschlechtert, lange bevor er sich in Timeouts verwandelt. - Verbleibende Tage. Ein
keyright.license.days_remaining, der unter eine Schwelle (sagen wir 7) fällt, ist die flottenweite Fassung des Erneuerungshinweises: ein Alarm statt eines pro Ablauf überraschten Kunden.
Der Gewinn
Nichts davon ändert, was die Lizenzprüfung entscheidet: Das Tor fällt bei einem widerrufenen oder abgelaufenen Schlüssel weiterhin geschlossen. Was sich ändert, ist, dass die Entscheidung nicht mehr unsichtbar ist. Eine Prüfung ist nun eine erstklassige Abhängigkeit auf Ihrem Dashboard: Sie sehen ihre Rate, ihre Latenz und den Moment, in dem sie klammheimlich davon, online zu antworten, zu, aus der Kulanz zu antworten, umschwenkt. Und weil das Design eine harte Linie zwischen beschränkten Tags und Identität zieht, erhalten Sie all diese Observability, ohne dass jemals ein einziger Lizenzschlüssel, Lizenznehmername oder eine Maschinen-ID in Ihrem Telemetrie-Backend landet.
Nebula.NET testen
Härten Sie Ihren .NET-Code in wenigen Minuten — starten Sie mit der kostenlosen Edition.