OpenTelemetry Visibility

Entitlement checks are control-flow: they decide whether requests proceed, degrade, or get billed. When they misbehave — slow, degraded, or suddenly denying — you want to see it in the same dashboards and traces as the rest of your system, not in a separate silo. The packaged exporter registers instrumentation against your existing OpenTelemetry setup; it composes with any OTLP-speaking vendor and no-ops silently when no OTel SDK is registered.

Enable in one line

instrumentMonetizeKit() returns a DecisionObserver that emits spans and metrics through your process's registered tracer and meter providers:

import { MonetizeKit } from "@monetizekit/node";
import { instrumentMonetizeKit } from "@monetizekit/node/otel";

const apiKey = process.env.MONETIZEKIT_API_KEY;
if (!apiKey) throw new Error("MONETIZEKIT_API_KEY is required");

export const mk = new MonetizeKit({
  apiKey,
  observers: [instrumentMonetizeKit()],
});

Sampling is parent-based and never overridden: if the caller's trace is unsampled, the decision span is too. Observer failures are swallowed twice over (by the SDK and by the exporter itself) — a broken telemetry pipeline can never affect an entitlement decision.

What gets emitted

One span per decision — monetizekit.entitlement_check for single checks, monetizekit.batch_check for batch results — nested inside whatever span is active when the check runs. Names and attributes are stable public API: renames are treated as breaking changes and ship with migration notes.

Metrics: bounded by design

Three instruments cover the operational questions. Metric attributes carry decision, cache, degradation, and feature-key dimensions — and deliberately never customer or evaluation ids, so time-series cardinality (and your monitoring bill) cannot grow with your account count:

Customer-level detail belongs on spans and in the analytics stream, not in metrics. Traces and metrics are independently enableable via instrumentMonetizeKit({ traces, metrics }).

From a span to the exact evaluation

Every check response carries the id of its evaluation-log record as evaluationId, and the exporter renders it as a ready-made deep link: monetizekit.inspector_url points at /observability/inspector/{evaluationId} in the dashboard, which resolves that one record directly — plan version, resolution reason, usage context, evaluation timing. No searching. A trace showing a denial becomes the evaluation record explaining it, one click apart.

Alerts worth paging on

Express these in your metrics backend of choice — the instrument and attribute names are the ones emitted above:

Manual pattern: span events instead of spans

If you'd rather attach decisions to your existing request spans than create a child span per check, implement DecisionObserver directly — the packaged exporter and this pattern use the same extension point and the same attribute names:

import { trace } from "@opentelemetry/api";
import { MonetizeKit, type DecisionObserver } from "@monetizekit/node";

const spanEventObserver: DecisionObserver = {
  onDecision(event) {
    trace.getActiveSpan()?.addEvent("monetizekit.decision", {
      "monetizekit.feature_key": event.featureKey ?? "",
      "monetizekit.decision": event.allowed ? "allowed" : "denied",
      "monetizekit.reason_code": event.reasonCode ?? "",
      "monetizekit.cache_hit": event.cached,
      "monetizekit.degraded": event.degraded,
      "monetizekit.latency_ms": event.latencyMs,
    });
  },
};

export const mk = new MonetizeKit({
  apiKey: process.env.MONETIZEKIT_API_KEY,
  observers: [spanEventObserver],
});

FAQ

Related guides